Added: incubator/unomi/website/versions/1.2/configuration.html URL: http://svn.apache.org/viewvc/incubator/unomi/website/versions/1.2/configuration.html?rev=1810306&view=auto ============================================================================== --- incubator/unomi/website/versions/1.2/configuration.html (added) +++ incubator/unomi/website/versions/1.2/configuration.html Mon Oct 2 08:11:40 2017 @@ -0,0 +1,568 @@ + +<!DOCTYPE html> +<!-- + Generated by Apache Maven Doxia at 2017-10-02 + Rendered using Reflow Maven Skin 1.1.1 (http://andriusvelykis.github.io/reflow-maven-skin) +--> +<html xml:lang="en" lang="en"> + + <head> + <meta charset="UTF-8" /> + <title>Configuration | Apache Unomi</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="description" content="" /> + <meta http-equiv="content-language" content="en" /> + + <link href="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/css/bootstrap.min.css"; rel="stylesheet" /> + <link href="../..//css/docs.css" rel="stylesheet" /> + <link href="../..//css/reflow-skin.css" rel="stylesheet" /> + + <link href="http://yandex.st/highlightjs/7.5/styles/github.min.css"; rel="stylesheet" /> + + <link href="../..//css/lightbox.css" rel="stylesheet" /> + + <link href="../..//css/site.css" rel="stylesheet" /> + <link href="../..//css/print.css" rel="stylesheet" media="print" /> + + <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements --> + <!--[if lt IE 9]> + <script src="http://html5shim.googlecode.com/svn/trunk/html5.js";></script> + <![endif]--> + + + + <!-- Google Analytics --> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-70313240-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + + </script> + </head> + + <body class="page-versions-12-configuration project-unomi-root" data-spy="scroll" data-offset="60" data-target="#toc-scroll-target"> + + <div class="navbar navbar-fixed-top"> + <div class="navbar-inner"> + <div class="container"> + <a class="btn btn-navbar" data-toggle="collapse" data-target="#top-nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </a> + <a class="brand" href="../.."><img src="http://unomi.incubator.apache.org/images/unomi-86x20.png"; /></a> + <div class="nav-collapse collapse" id="top-nav-collapse"> + <ul class="nav pull-right"> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../download.html" title="Packages">Packages</a></li> + <li ><a href="../../license.html" title="License">License</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../" title="Site Home">Site Home</a></li> + <li ><a href="../../main.html" title="Main documentation">Main documentation</a></li> + <li ><a href="../../usecases.html" title="More use cases">More use cases</a></li> + <li ><a href="../../rest-api-doc/index.html" title="REST API documentation">REST API documentation</a></li> + <li ><a href="../../unomi-api/apidocs/index.html" title="API Javadoc">API Javadoc</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Standard <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="https://www.oasis-open.org/committees/cxs/"; title="OASIS Context Server Technical Committee" class="externalLink">OASIS Context Server Technical Committee</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Privacy <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../privacy-policy.html" title="Site policy">Site policy</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a></li> + <li ><a href="../../source-repository.html" title="Source">Source</a></li> + <li ><a href="../../issue-tracking.html" title="Issues">Issues</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Community <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a></li> + <li ><a href="../../team-list.html" title="Team">Team</a></li> + <li ><a href="../../maturity-model-report.html" title="Maturity model report card">Maturity model report card</a></li> + <li ><a href="http://www.apache.org"; title="The Apache Software Foundation" class="externalLink">The Apache Software Foundation</a></li> + <li ><a href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsorship" class="externalLink">Sponsorship</a></li> + <li ><a href="http://www.apache.org/foundation/thanks.html"; title="Thanks" class="externalLink">Thanks</a></li> + </ul> + </li> + </ul> + </div><!--/.nav-collapse --> + </div> + </div> + </div> + + <div class="container"> + + <!-- Masthead + ================================================== --> + + <header> + <div> + <ul class="breadcrumb"> + <li class="publishDate version-date">Last Published: 2017-10-02</li> + </ul> + </div> + </header> + + <div class="main-body"> + <div class="row"> + <div class="span8"> + <div class="body-content"> +<!-- ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to You under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. --> +<div class="page-header"> + <h1 id="configuration">Configuration</h1> +</div> +<div class="section"> + <h2 id="Changing_the_default_configuration">Changing the default configuration</h2> + <p>If you want to change the default configuration, you can perform any modification you want in the $MY_KARAF_HOME/etc directory.</p> + <p>The context server configuration is kept in the $MY_KARAF_HOME/etc/org.apache.unomi.cluster.cfg . It defines the addresses where it can be found :</p> + <div class="source"> + <div class="source"> + <pre>contextserver.publicAddress=https://localhost:9443 +contextserver.internalAddress=http://127.0.0.1:8181 +</pre> + </div> + </div> + <p>If you need to specify an Elasticsearch cluster name, or a host and port that are different than the default, it is recommended to do this BEFORE you start the server for the first time, or you will loose all the data you have stored previously.</p> + <p>To change these settings, you will need to modify a file called </p> + <div class="source"> + <div class="source"> + <pre>$MY_KARAF_HOME/etc/org.apache.unomi.persistence.elasticsearch.cfg +</pre> + </div> + </div> + <p>with the following contents:</p> + <div class="source"> + <div class="source"> + <pre>cluster.name=contextElasticSearch +# The elasticSearchAddresses may be a comma seperated list of host names and ports such as +# hostA:9300,hostB:9300 +# Note: the port number must be repeated for each host. +elasticSearchAddresses=localhost:9300 +index.name=context +</pre> + </div> + </div> +</div> +<div class="section"> + <h2 id="Secured_events_configuration">Secured events configuration</h2> + <p>If you need to secure some events, that will be sent only by a trusted third party server, you can update the file :</p> + <div class="source"> + <div class="source"> + <pre>$MY_KARAF_HOME/etc/org.apache.unomi.thirdparty.cfg +</pre> + </div> + </div> + <p>Ususally, login events, which operate on profiles and do merge on protected properties, must be secured. For each trusted third party server, you need to add these 3 lines :</p> + <div class="source"> + <div class="source"> + <pre>thirdparty.provider1.key=secret-key +thirdparty.provider1.ipAddresses=127.0.0.1,::1 +thirdparty.provider1.allowedEvents=login,download +</pre> + </div> + </div> + <p>The events set in allowedEvents will be secured and will only be accepted if the call comes from the specified IP address, and if the secret-key is passed in the X-Unomi-Peer header. </p> +</div> +<div class="section"> + <h2 id="Installing_the_MaxMind_GeoIPLite2_IP_lookup_database">Installing the MaxMind GeoIPLite2 IP lookup database</h2> + <p>The Context Server requires an IP database in order to resolve IP addresses to user location. The GeoLite2 database can be downloaded from MaxMind here : <a class="externalLink" href="http://dev.maxmind.com/geoip/geoip2/geolite2/";>http://dev.maxmind.com/geoip/geoip2/geolite2/</a></p> + <p>Simply download the GeoLite2-City.mmdb file into the âetcâ directory.</p> +</div> +<div class="section"> + <h2 id="Installing_Geonames_database">Installing Geonames database</h2> + <p>Context server includes a geocoding service based on the geonames database ( <a class="externalLink" href="http://www.geonames.org/";>http://www.geonames.org/</a> ). It can be used to create conditions on countries or cities.</p> + <p>In order to use it, you need to install the Geonames database into . Get the âallCountries.zipâ database from here : <a class="externalLink" href="http://download.geonames.org/export/dump/";>http://download.geonames.org/export/dump/</a></p> + <p>Download it and put it in the âetcâ directory, without unzipping it. Edit $MY_KARAF_HOME/etc/org.apache.unomi.geonames.cfg and set request.geonamesDatabase.forceImport to true, import should start right away. Otherwise, import should start at the next startup. Import runs in background, but can take about 15 minutes. At the end, you should have about 4 million entries in the geonames index.</p> +</div> +<div class="section"> + <h2 id="REST_API_Security">REST API Security</h2> + <p>The Context Server REST API is protected using JAAS authentication and using Basic or Digest HTTP auth. By default, the login/password for the REST API full administrative access is âkaraf/karafâ.</p> + <p>The generated package is also configured with a default SSL certificate. You can change it by following these steps :</p> + <ol style="list-style-type: decimal"> + <li> <p>Replace the existing keystore in $MY_KARAF_HOME/etc/keystore by your own certificate :</p> <p><a class="externalLink" href="http://wiki.eclipse.org/Jetty/Howto/Configure_SSL";>http://wiki.eclipse.org/Jetty/Howto/Configure_SSL</a></p></li> + <li> <p>Update the keystore and certificate password in $MY_KARAF_HOME/etc/custom.properties file :</p></li> + </ol> + <div class="source"> + <div class="source"> + <pre> org.osgi.service.http.secure.enabled = true + org.ops4j.pax.web.ssl.keystore=${karaf.etc}/keystore + org.ops4j.pax.web.ssl.password=changeme + org.ops4j.pax.web.ssl.keypassword=changeme + org.osgi.service.http.port.secure=9443 +</pre> + </div> + </div> + <p>You should now have SSL setup on Karaf with your certificate, and you can test it by trying to access it on port 9443.</p> + <ol style="list-style-type: decimal"> + <li> <p>Changing the default Karaf password can be done by modifying the etc/users.properties file</p></li> + <li> <p>You will also need to change the user/password information in the org.apache.unomi.cluster.cfg file : </p></li> + </ol> + <div class="source"> + <div class="source"> + <pre> cluster.group=default + cluster.jmxUsername=karaf + cluster.jmxPassword=karaf + cluster.jmxPort=1099 +</pre> + </div> + </div> +</div> +<div class="section"> + <h2 id="Automatic_profile_merging">Automatic profile merging</h2> + <p>The context server is capable of merging profiles based on a common property value. In order to use this, you must add the MergeProfileOnPropertyAction to a rule (such as a login rule for example), and configure it with the name of the property that will be used to identify the profiles to be merged. An example could be the âemailâ property, meaning that if two (or more) profiles are found to have the same value for the âemailâ property they will be merged by this action.</p> + <p>Upon merge, the old profiles are marked with a âmergedWithâ property that will be used on next profile access to delete the original profile and replace it with the merged profile (aka âmasterâ profile). Once this is done, all cookie tracking will use the merged profile.</p> + <p>To test, simply configure the action in the âloginâ or âfacebookLoginâ rules and set it up on the âemailâ property. Upon sending one of the events, all matching profiles will be merged.</p> +</div> +<div class="section"> + <h2 id="Securing_a_production_environment">Securing a production environment</h2> + <p>Before going live with a project, you should <i>absolutely</i> read the following section that will help you setup a proper secure environment for running your context server. </p> + <p>Step 1: Install and configure a firewall </p> + <p>You should setup a firewall around your cluster of context servers and/or Elasticsearch nodes. If you have an application-level firewall you should only allow the following connections open to the whole world : </p> + <ul> + <li><a class="externalLink" href="http://localhost:8181/context.js";>http://localhost:8181/context.js</a></li> + <li><a class="externalLink" href="http://localhost:8181/eventcollector";>http://localhost:8181/eventcollector</a></li> + </ul> + <p>All other ports should not be accessible to the world.</p> + <p>For your Context Server client applications (such as the Jahia CMS), you will need to make the following ports accessible : </p> + <div class="source"> + <div class="source"> + <pre>8181 (Context Server HTTP port) +9443 (Context Server HTTPS port) +</pre> + </div> + </div> + <p>The context server actually requires HTTP Basic Auth for access to the Context Server administration REST API, so it is highly recommended that you design your client applications to use the HTTPS port for accessing the REST API.</p> + <p>The user accounts to access the REST API are actually routed through Karafâs JAAS support, which you may find the documentation for here : </p> + <ul> + <li><a class="externalLink" href="http://karaf.apache.org/manual/latest/users-guide/security.html";>http://karaf.apache.org/manual/latest/users-guide/security.html</a></li> + </ul> + <p>The default username/password is </p> + <div class="source"> + <div class="source"> + <pre>karaf/karaf +</pre> + </div> + </div> + <p>You should really change this default username/password as soon as possible. To do so, simply modify the following file : </p> + <div class="source"> + <div class="source"> + <pre>$MY_KARAF_HOME/etc/users.properties +</pre> + </div> + </div> + <p>For your context servers, and for any standalone Elasticsearch nodes you will need to open the following ports for proper node-to-node communication : 9200 (Elasticsearch REST API), 9300 (Elasticsearch TCP transport)</p> + <p>Of course any ports listed here are the default ports configured in each server, you may adjust them if needed.</p> + <p>Step 2 : Follow industry recommended best practices for securing Elasticsearch</p> + <p>You may find more valuable recommendations here : </p> + <ul> + <li><a class="externalLink" href="https://www.elastic.co/blog/found-elasticsearch-security";>https://www.elastic.co/blog/found-elasticsearch-security</a></li> + <li><a class="externalLink" href="https://www.elastic.co/blog/scripting-security";>https://www.elastic.co/blog/scripting-security</a></li> + </ul> + <p>Step 4 : Setup a proxy in front of the context server</p> + <p>As an alternative to an application-level firewall, you could also route all traffic to the context server through a proxy, and use it to filter any communication.</p> +</div> +<div class="section"> + <h2 id="Integrating_with_an_Apache_HTTP_web_server">Integrating with an Apache HTTP web server</h2> + <p>If you want to setup an Apache HTTP web server in from of Apache Unomi, here is an example configuration using mod_proxy.</p> + <p>In your Unomi package directory, in /etc/org.apache.unomi.cluster.cfg for unomi.apache.org</p> + <p>contextserver.publicAddress=https://unomi.apache.org/ contextserver.internalAddress=http://192.168.1.1:8181</p> + <p>and you will also need to change the contextserver.domain in the /etc/org.apache.unomi.web.cfg file</p> + <p>contextserver.domain=apache.org</p> + <p>Main virtual host config:</p> + <div class="source"> + <div class="source"> + <pre><VirtualHost *:80> + Include /var/www/vhosts/unomi.apache.org/conf/common.conf +</VirtualHost> + +<IfModule mod_ssl.c> + <VirtualHost *:443> + Include /var/www/vhosts/unomi.apache.org/conf/common.conf + + SSLEngine on + + SSLCertificateFile /var/www/vhosts/unomi.apache.org/conf/ssl/24d5b9691e96eafa.crt + SSLCertificateKeyFile /var/www/vhosts/unomi.apache.org/conf/ssl/apache.org.key + SSLCertificateChainFile /var/www/vhosts/unomi.apache.org/conf/ssl/gd_bundle-g2-g1.crt + + + <FilesMatch "\.(cgi|shtml|phtml|php)$"> + SSLOptions +StdEnvVars + </FilesMatch> + <Directory /usr/lib/cgi-bin> + SSLOptions +StdEnvVars + </Directory> + BrowserMatch "MSIE [2-6]" \ + nokeepalive ssl-unclean-shutdown \ + downgrade-1.0 force-response-1.0 + BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown + + </VirtualHost> +</IfModule> +</pre> + </div> + </div> + <p>common.conf:</p> + <div class="source"> + <div class="source"> + <pre>ServerName unomi.apache.org +ServerAdmin [email protected] + +DocumentRoot /var/www/vhosts/unomi.apache.org/html +CustomLog /var/log/apache2/access-unomi.apache.org.log combined +<Directory /> + Options FollowSymLinks + AllowOverride None +</Directory> +<Directory /var/www/vhosts/unomi.apache.org/html> + Options FollowSymLinks MultiViews + AllowOverride None + Order allow,deny + allow from all +</Directory> +<Location /cxs> + Order deny,allow + deny from all + allow from 88.198.26.2 + allow from www.apache.org +</Location> + +RewriteEngine On +RewriteCond %{REQUEST_METHOD} ^(TRACE|TRACK) +RewriteRule .* - [F] +ProxyPreserveHost On +ProxyPass /server-status ! +ProxyPass /robots.txt ! + +RewriteCond %{HTTP_USER_AGENT} Googlebot [OR] +RewriteCond %{HTTP_USER_AGENT} msnbot [OR] +RewriteCond %{HTTP_USER_AGENT} Slurp +RewriteRule ^.* - [F,L] + +ProxyPass / http://localhost:8181/ connectiontimeout=20 timeout=300 ttl=120 +ProxyPassReverse / http://localhost:8181/ +</pre> + </div> + </div> +</div> +<div class="section"> + <h2 id="Changing_the_default_tracking_location">Changing the default tracking location</h2> + <p>When performing localhost requests to Apache Unomi, a default location will be used to insert values into the session to make the location-based personalization still work. You can find the default location settings in the file : </p> + <div class="source"> + <div class="source"> + <pre>org.apache.unomi.plugins.request.cfg +</pre> + </div> + </div> + <p>that contains the following default settings:</p> + <div class="source"> + <div class="source"> + <pre># The following settings represent the default position that is used for localhost requests +defaultSessionCountryCode=CH +defaultSessionCountryName=Switzerland +defaultSessionCity=Geneva +defaultSessionAdminSubDiv1=2660645 +defaultSessionAdminSubDiv2=6458783 +defaultSessionIsp=Cablecom +defaultLatitude=46.1884341 +defaultLongitude=6.1282508 +</pre> + </div> + </div> + <p>You might want to change these for testing or for demonstration purposes.</p> +</div> +<div class="section"> + <h2 id="Apache_Karaf_SSH_Console">Apache Karaf SSH Console</h2> + <p>The Apache Karaf SSH console is available inside Apache Unomi, but the port has been changed from the default value of 8101 to 8102 to avoid conflicts with other Karaf-based products. So to connect to the SSH console you should use:</p> + <div class="source"> + <div class="source"> + <pre>ssh -p 8102 karaf@localhost +</pre> + </div> + </div> + <p>or the user/password you have setup to protect the system if you have changed it.</p> +</div> + </div> + </div> + <div class="span4"> + <div id="toc-sidebar"> + <div class="well"> + <ul class="nav nav-list"> + <li class="nav-header">Table of Contents</li> + <li class="dropdown"><a href="#configuration" title="Configuration">Configuration <b class="caret"></b></a> + <ul class="nav nav-list"> + <li><a href="#Changing_the_default_configuration" title="Changing the default configuration">Changing the default configuration</a> + <li><a href="#Secured_events_configuration" title="Secured events configuration">Secured events configuration</a> + <li><a href="#Installing_the_MaxMind_GeoIPLite2_IP_lookup_database" title="Installing the MaxMind GeoIPLite2 IP lookup database">Installing the MaxMind GeoIPLite2 IP lookup database</a> + <li><a href="#Installing_Geonames_database" title="Installing Geonames database">Installing Geonames database</a> + <li><a href="#REST_API_Security" title="REST API Security">REST API Security</a> + <li><a href="#Automatic_profile_merging" title="Automatic profile merging">Automatic profile merging</a> + <li><a href="#Securing_a_production_environment" title="Securing a production environment">Securing a production environment</a> + <li><a href="#Integrating_with_an_Apache_HTTP_web_server" title="Integrating with an Apache HTTP web server">Integrating with an Apache HTTP web server</a> + <li><a href="#Changing_the_default_tracking_location" title="Changing the default tracking location">Changing the default tracking location</a> + <li><a href="#Apache_Karaf_SSH_Console" title="Apache Karaf SSH Console">Apache Karaf SSH Console</a> + <li class="divider"></li> + </ul> + </li> + </ul> + </div> + </div> + </div> + </div> + </div> + + </div><!-- /container --> + + <!-- Footer + ================================================== --> + <footer class="well"> + <div class="container"> + <div class="row"> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Download</li> + <li > + <a href="../../download.html" title="Packages">Packages</a> + </li> + <li > + <a href="../../license.html" title="License">License</a> + </li> + <li class="nav-header">Contribute</li> + <li > + <a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a> + </li> + <li > + <a href="../../source-repository.html" title="Source">Source</a> + </li> + <li > + <a href="../../issue-tracking.html" title="Issues">Issues</a> + </li> + </ul> + </div> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Documentation</li> + <li > + <a href="../../" title="Site Home">Site Home</a> + </li> + <li > + <a href="../../main.html" title="Main documentation">Main documentation</a> + </li> + <li > + <a href="../../usecases.html" title="More use cases">More use cases</a> + </li> + <li > + <a href="../../rest-api-doc/index.html" title="REST API documentation">REST API documentation</a> + </li> + <li > + <a href="../../unomi-api/apidocs/index.html" title="API Javadoc">API Javadoc</a> + </li> + </ul> + </div> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Standard</li> + <li > + <a href="https://www.oasis-open.org/committees/cxs/"; title="OASIS Context Server Technical Committee" class="externalLink">OASIS Context Server Technical Committee</a> + </li> + <li class="nav-header">Privacy</li> + <li > + <a href="../../privacy-policy.html" title="Site policy">Site policy</a> + </li> + <li class="nav-header">Community</li> + <li > + <a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a> + </li> + <li > + <a href="../../team-list.html" title="Team">Team</a> + </li> + <li > + <a href="../../maturity-model-report.html" title="Maturity model report card">Maturity model report card</a> + </li> + <li > + <a href="http://www.apache.org"; title="The Apache Software Foundation" class="externalLink">The Apache Software Foundation</a> + </li> + <li > + <a href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsorship" class="externalLink">Sponsorship</a> + </li> + <li > + <a href="http://www.apache.org/foundation/thanks.html"; title="Thanks" class="externalLink">Thanks</a> + </li> + </ul> + </div> + <div class="span3 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Project Documentation</li> + <li > + <a href="../../project-info.html" title="Project Information">Project Information <i class="icon-chevron-right"></i></a> + </li> + </ul> + </div> + <div class="span3 bottom-description"> + <blockquote>Powered by Apache Karaf</blockquote> + </div> + </div> + </div> + </footer> + + <div class="container subfooter"> + <div class="row"> + <div class="span12"> + <p class="pull-right"><a href="#">Back to top</a></p> + <p class="copyright">Copyright ©2014-2017 <a href="http://www.apache.org";>Apache Software Foundation</a>. All Rights Reserved.</p> + <p><a href="http://github.com/andriusvelykis/reflow-maven-skin"; title="Reflow Maven skin">Reflow Maven skin</a> by <a href="http://andrius.velykis.lt"; target="_blank" title="Andrius Velykis">Andrius Velykis</a>.</p> + </div> + </div> + </div> + + <!-- Le javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js";></script> + + <script src="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/js/bootstrap.min.js";></script> + <script src="../..//js/lightbox.min.js"></script> + <script src="../..//js/reflow-scroll.js"></script> + <script src="http://yandex.st/highlightjs/7.5/highlight.min.js";></script> + + <script src="../..//js/reflow-skin.js"></script> + + </body> +</html> \ No newline at end of file
Added: incubator/unomi/website/versions/1.2/connectors.html URL: http://svn.apache.org/viewvc/incubator/unomi/website/versions/1.2/connectors.html?rev=1810306&view=auto ============================================================================== --- incubator/unomi/website/versions/1.2/connectors.html (added) +++ incubator/unomi/website/versions/1.2/connectors.html Mon Oct 2 08:11:40 2017 @@ -0,0 +1,296 @@ + +<!DOCTYPE html> +<!-- + Generated by Apache Maven Doxia at 2017-10-02 + Rendered using Reflow Maven Skin 1.1.1 (http://andriusvelykis.github.io/reflow-maven-skin) +--> +<html xml:lang="en" lang="en"> + + <head> + <meta charset="UTF-8" /> + <title>Connectors | Apache Unomi</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="description" content="" /> + <meta http-equiv="content-language" content="en" /> + + <link href="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/css/bootstrap.min.css"; rel="stylesheet" /> + <link href="../..//css/docs.css" rel="stylesheet" /> + <link href="../..//css/reflow-skin.css" rel="stylesheet" /> + + <link href="http://yandex.st/highlightjs/7.5/styles/github.min.css"; rel="stylesheet" /> + + <link href="../..//css/lightbox.css" rel="stylesheet" /> + + <link href="../..//css/site.css" rel="stylesheet" /> + <link href="../..//css/print.css" rel="stylesheet" media="print" /> + + <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements --> + <!--[if lt IE 9]> + <script src="http://html5shim.googlecode.com/svn/trunk/html5.js";></script> + <![endif]--> + + + + <!-- Google Analytics --> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-70313240-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + + </script> + </head> + + <body class="page-versions-12-connectors project-unomi-root" data-spy="scroll" data-offset="60" data-target="#toc-scroll-target"> + + <div class="navbar navbar-fixed-top"> + <div class="navbar-inner"> + <div class="container"> + <a class="btn btn-navbar" data-toggle="collapse" data-target="#top-nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </a> + <a class="brand" href="../.."><img src="http://unomi.incubator.apache.org/images/unomi-86x20.png"; /></a> + <div class="nav-collapse collapse" id="top-nav-collapse"> + <ul class="nav pull-right"> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../download.html" title="Packages">Packages</a></li> + <li ><a href="../../license.html" title="License">License</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../" title="Site Home">Site Home</a></li> + <li ><a href="../../main.html" title="Main documentation">Main documentation</a></li> + <li ><a href="../../usecases.html" title="More use cases">More use cases</a></li> + <li ><a href="../../rest-api-doc/index.html" title="REST API documentation">REST API documentation</a></li> + <li ><a href="../../unomi-api/apidocs/index.html" title="API Javadoc">API Javadoc</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Standard <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="https://www.oasis-open.org/committees/cxs/"; title="OASIS Context Server Technical Committee" class="externalLink">OASIS Context Server Technical Committee</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Privacy <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../privacy-policy.html" title="Site policy">Site policy</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a></li> + <li ><a href="../../source-repository.html" title="Source">Source</a></li> + <li ><a href="../../issue-tracking.html" title="Issues">Issues</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Community <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a></li> + <li ><a href="../../team-list.html" title="Team">Team</a></li> + <li ><a href="../../maturity-model-report.html" title="Maturity model report card">Maturity model report card</a></li> + <li ><a href="http://www.apache.org"; title="The Apache Software Foundation" class="externalLink">The Apache Software Foundation</a></li> + <li ><a href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsorship" class="externalLink">Sponsorship</a></li> + <li ><a href="http://www.apache.org/foundation/thanks.html"; title="Thanks" class="externalLink">Thanks</a></li> + </ul> + </li> + </ul> + </div><!--/.nav-collapse --> + </div> + </div> + </div> + + <div class="container"> + + <!-- Masthead + ================================================== --> + + <header> + <div> + <ul class="breadcrumb"> + <li class="publishDate version-date">Last Published: 2017-10-02</li> + </ul> + </div> + </header> + + <div class="main-body"> + <div class="row"> + <div class="span8"> + <div class="body-content"> +<!-- ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to You under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. --> +<div class="page-header"> + <h1 id="connectors">Connectors</h1> +</div> +<p>Apache Unomi provides the following connector:</p> +<ul> + <li><a href="salesforce-connector.html">Salesforce CRM connector</a></li> +</ul> +<div class="section"> + <h2 id="Call_for_contributors">Call for contributors</h2> + <p>We are looking for help with the development of additional connectors. Any contribution (large or small) is more than welcome. Feel free to discuss this in our <a href="../../mail-lists.html">mailing list</a>.</p> +</div> + </div> + </div> + <div class="span4"> + <div id="toc-sidebar"> + <div class="well"> + <ul class="nav nav-list"> + <li class="nav-header">Table of Contents</li> + <li class="dropdown"><a href="#connectors" title="Connectors">Connectors <b class="caret"></b></a> + <ul class="nav nav-list"> + <li><a href="#Call_for_contributors" title="Call for contributors">Call for contributors</a> + <li class="divider"></li> + </ul> + </li> + </ul> + </div> + </div> + </div> + </div> + </div> + + </div><!-- /container --> + + <!-- Footer + ================================================== --> + <footer class="well"> + <div class="container"> + <div class="row"> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Download</li> + <li > + <a href="../../download.html" title="Packages">Packages</a> + </li> + <li > + <a href="../../license.html" title="License">License</a> + </li> + <li class="nav-header">Contribute</li> + <li > + <a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a> + </li> + <li > + <a href="../../source-repository.html" title="Source">Source</a> + </li> + <li > + <a href="../../issue-tracking.html" title="Issues">Issues</a> + </li> + </ul> + </div> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Documentation</li> + <li > + <a href="../../" title="Site Home">Site Home</a> + </li> + <li > + <a href="../../main.html" title="Main documentation">Main documentation</a> + </li> + <li > + <a href="../../usecases.html" title="More use cases">More use cases</a> + </li> + <li > + <a href="../../rest-api-doc/index.html" title="REST API documentation">REST API documentation</a> + </li> + <li > + <a href="../../unomi-api/apidocs/index.html" title="API Javadoc">API Javadoc</a> + </li> + </ul> + </div> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Standard</li> + <li > + <a href="https://www.oasis-open.org/committees/cxs/"; title="OASIS Context Server Technical Committee" class="externalLink">OASIS Context Server Technical Committee</a> + </li> + <li class="nav-header">Privacy</li> + <li > + <a href="../../privacy-policy.html" title="Site policy">Site policy</a> + </li> + <li class="nav-header">Community</li> + <li > + <a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a> + </li> + <li > + <a href="../../team-list.html" title="Team">Team</a> + </li> + <li > + <a href="../../maturity-model-report.html" title="Maturity model report card">Maturity model report card</a> + </li> + <li > + <a href="http://www.apache.org"; title="The Apache Software Foundation" class="externalLink">The Apache Software Foundation</a> + </li> + <li > + <a href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsorship" class="externalLink">Sponsorship</a> + </li> + <li > + <a href="http://www.apache.org/foundation/thanks.html"; title="Thanks" class="externalLink">Thanks</a> + </li> + </ul> + </div> + <div class="span3 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Project Documentation</li> + <li > + <a href="../../project-info.html" title="Project Information">Project Information <i class="icon-chevron-right"></i></a> + </li> + </ul> + </div> + <div class="span3 bottom-description"> + <blockquote>Powered by Apache Karaf</blockquote> + </div> + </div> + </div> + </footer> + + <div class="container subfooter"> + <div class="row"> + <div class="span12"> + <p class="pull-right"><a href="#">Back to top</a></p> + <p class="copyright">Copyright ©2014-2017 <a href="http://www.apache.org";>Apache Software Foundation</a>. All Rights Reserved.</p> + <p><a href="http://github.com/andriusvelykis/reflow-maven-skin"; title="Reflow Maven skin">Reflow Maven skin</a> by <a href="http://andrius.velykis.lt"; target="_blank" title="Andrius Velykis">Andrius Velykis</a>.</p> + </div> + </div> + </div> + + <!-- Le javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js";></script> + + <script src="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/js/bootstrap.min.js";></script> + <script src="../..//js/lightbox.min.js"></script> + <script src="../..//js/reflow-scroll.js"></script> + <script src="http://yandex.st/highlightjs/7.5/highlight.min.js";></script> + + <script src="../..//js/reflow-skin.js"></script> + + </body> +</html> \ No newline at end of file Added: incubator/unomi/website/versions/1.2/custom-extensions.html URL: http://svn.apache.org/viewvc/incubator/unomi/website/versions/1.2/custom-extensions.html?rev=1810306&view=auto ============================================================================== --- incubator/unomi/website/versions/1.2/custom-extensions.html (added) +++ incubator/unomi/website/versions/1.2/custom-extensions.html Mon Oct 2 08:11:40 2017 @@ -0,0 +1,671 @@ + +<!DOCTYPE html> +<!-- + Generated by Apache Maven Doxia at 2017-10-02 + Rendered using Reflow Maven Skin 1.1.1 (http://andriusvelykis.github.io/reflow-maven-skin) +--> +<html xml:lang="en" lang="en"> + + <head> + <meta charset="UTF-8" /> + <title>Custom extensions | Apache Unomi</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="description" content="" /> + <meta http-equiv="content-language" content="en" /> + + <link href="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/css/bootstrap.min.css"; rel="stylesheet" /> + <link href="../..//css/docs.css" rel="stylesheet" /> + <link href="../..//css/reflow-skin.css" rel="stylesheet" /> + + <link href="http://yandex.st/highlightjs/7.5/styles/github.min.css"; rel="stylesheet" /> + + <link href="../..//css/lightbox.css" rel="stylesheet" /> + + <link href="../..//css/site.css" rel="stylesheet" /> + <link href="../..//css/print.css" rel="stylesheet" media="print" /> + + <!-- Le HTML5 shim, for IE6-8 support of HTML5 elements --> + <!--[if lt IE 9]> + <script src="http://html5shim.googlecode.com/svn/trunk/html5.js";></script> + <![endif]--> + + + + <!-- Google Analytics --> + <script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-70313240-1']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + + </script> + </head> + + <body class="page-versions-12-custom-extensions project-unomi-root" data-spy="scroll" data-offset="60" data-target="#toc-scroll-target"> + + <div class="navbar navbar-fixed-top"> + <div class="navbar-inner"> + <div class="container"> + <a class="btn btn-navbar" data-toggle="collapse" data-target="#top-nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </a> + <a class="brand" href="../.."><img src="http://unomi.incubator.apache.org/images/unomi-86x20.png"; /></a> + <div class="nav-collapse collapse" id="top-nav-collapse"> + <ul class="nav pull-right"> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Download <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../download.html" title="Packages">Packages</a></li> + <li ><a href="../../license.html" title="License">License</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../" title="Site Home">Site Home</a></li> + <li ><a href="../../main.html" title="Main documentation">Main documentation</a></li> + <li ><a href="../../usecases.html" title="More use cases">More use cases</a></li> + <li ><a href="../../rest-api-doc/index.html" title="REST API documentation">REST API documentation</a></li> + <li ><a href="../../unomi-api/apidocs/index.html" title="API Javadoc">API Javadoc</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Standard <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="https://www.oasis-open.org/committees/cxs/"; title="OASIS Context Server Technical Committee" class="externalLink">OASIS Context Server Technical Committee</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Privacy <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../privacy-policy.html" title="Site policy">Site policy</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Contribute <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a></li> + <li ><a href="../../source-repository.html" title="Source">Source</a></li> + <li ><a href="../../issue-tracking.html" title="Issues">Issues</a></li> + </ul> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Community <b class="caret"></b></a> + <ul class="dropdown-menu"> + <li ><a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a></li> + <li ><a href="../../team-list.html" title="Team">Team</a></li> + <li ><a href="../../maturity-model-report.html" title="Maturity model report card">Maturity model report card</a></li> + <li ><a href="http://www.apache.org"; title="The Apache Software Foundation" class="externalLink">The Apache Software Foundation</a></li> + <li ><a href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsorship" class="externalLink">Sponsorship</a></li> + <li ><a href="http://www.apache.org/foundation/thanks.html"; title="Thanks" class="externalLink">Thanks</a></li> + </ul> + </li> + </ul> + </div><!--/.nav-collapse --> + </div> + </div> + </div> + + <div class="container"> + + <!-- Masthead + ================================================== --> + + <header> + <div> + <ul class="breadcrumb"> + <li class="publishDate version-date">Last Published: 2017-10-02</li> + </ul> + </div> + </header> + + <div class="main-body"> + <div class="row"> + <div class="span8"> + <div class="body-content"> +<!-- ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to You under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. --> +<div class="page-header"> + <h1 id="custom_extensions">Custom extensions</h1> +</div> +<p>Apache Unomi is a pluggeable server that may be extended in many ways. This document assumes you are familiar with the <a href="concepts.html">Apache Unomi concepts</a> . This document is mostly a reference document on the different things that may be used inside an extension. If you are looking for complete samples, please see the <a href="samples.html">samples page</a>.</p> +<div class="section"> + <h2 id="Creating_an_extension">Creating an extension</h2> + <p>An extension is simply a Maven project, with a Maven pom that looks like this:</p> + <div class="source"> + <div class="source"> + <pre><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> + <parent> + <groupId>org.apache.unomi</groupId> + <artifactId>unomi-extensions</artifactId> + <version>1.2.0-incubating-SNAPSHOT</version> + </parent> + + <modelVersion>4.0.0</modelVersion> + + <artifactId>unomi-extension-example</artifactId> + <name>Apache Unomi :: Extensions :: Example</name> + <description>Service implementation for the Apache Unomi Context Server extension that integrates with the Geonames database</description> + <version>1.2.0-incubating-SNAPSHOT</version> + <packaging>bundle</packaging> + + <dependencies> + <!-- This dependency is not required but generally used in extensions --> + <dependency> + <groupId>org.apache.unomi</groupId> + <artifactId>unomi-api</artifactId> + <version>1.2.0-incubating-SNAPSHOT</version> + <scope>provided</scope> + </dependency> + </dependencies> + + <build> + <plugins> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <extensions>true</extensions> + <configuration> + <instructions> + <Embed-Dependency>*;scope=compile|runtime</Embed-Dependency> + <Import-Package> + sun.misc;resolution:=optional, + * + </Import-Package> + </instructions> + </configuration> + </plugin> + </plugins> + </build> +</project> +</pre> + </div> + </div> + <p>An extension may contain many different kinds of Apache Unomi objects, as well as custom OSGi services or anything that is needed to build your application.</p> +</div> +<div class="section"> + <h2 id="Predefined_segments">Predefined segments</h2> + <p>You may provide pre-defined segments by simply adding a JSON file in the src/main/resources/META-INF/cxs/segments directory of your Maven project. Here is an example of a pre-defined segment:</p> + <div class="source"> + <div class="source"> + <pre>{ + "metadata": { + "id": "leads", + "name": "Leads", + "scope": "systemscope", + "description": "You can customize the list below by editing the leads segment.", + "readOnly":true + }, + "condition": { + "parameterValues": { + "subConditions": [ + { + "parameterValues": { + "propertyName": "properties.leadAssignedTo", + "comparisonOperator": "exists" + }, + "type": "profilePropertyCondition" + } + ], + "operator" : "and" + }, + "type": "booleanCondition" + } +} +</pre> + </div> + </div> + <p>Basically this segment uses a condition to test if the profile has a property <tt>leadAssignedTo</tt> that exists. All profiles that match this condition will be part of the pre-defined segment.</p> +</div> +<div class="section"> + <h2 id="Predefined_rules">Predefined rules</h2> + <p>You may provide pre-defined rules by simply adding a JSON file in the src/main/resources/META-INF/cxs/rules directory of your Maven project. Here is an example of a pre-defined rule:</p> + <div class="source"> + <div class="source"> + <pre>{ + "metadata" : { + "id": "evaluateProfileSegments", + "name": "Evaluate segments", + "description" : "Evaluate segments when a profile is modified", + "readOnly":true + }, + + "condition" : { + "type": "profileUpdatedEventCondition", + "parameterValues": { + } + }, + + "actions" : [ + { + "type": "evaluateProfileSegmentsAction", + "parameterValues": { + } + } + ] + +} +</pre> + </div> + </div> + <p>In this example we provide a rule that will execute when a predefined composed condition of type âprofileUpdatedEventConditionâ is received. See below to see how predefined composed conditions are declared. Once the condition is matched, the actions will be executed in sequence. In this example there is only a single action of type âevaluateProfileSegmentsActionâ that is defined so it will be executed by Apache Unomiâs rule engine. You can also see below how custom actions may be defined. </p> +</div> +<div class="section"> + <h2 id="Predefined_properties">Predefined properties</h2> + <p>By default Apache Unomi comes with a set of pre-defined properties, but in many cases it is useful to add additional predefined property definitions. You can create property definitions for session or profile properties by creating them in different directories.</p> + <p>For session properties you must create a JSON file in the following directory in your Maven project:</p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/META-INF/cxs/properties/sessions +</pre> + </div> + </div> + <p>For profile properties you must create the JSON file inside the directory in your Maven project:</p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/META-INF/cxs/properties/profiles +</pre> + </div> + </div> + <p>Here is an example of a property definition JSON file</p> + <div class="source"> + <div class="source"> + <pre>{ + "metadata": { "id": "city", "name": "City" }, + "type": "string", + "tags": ["contactProfileProperties"], + "defaultValue": "", + "automaticMappingsFrom": [ ], + "rank": "304.0" +} +</pre> + </div> + </div> +</div> +<div class="section"> + <h2 id="Predefined_child_conditions">Predefined child conditions</h2> + <p>You can define new predefined conditions that are actually conditions inheriting from a parent condition and setting pre-defined parameter values. You can do this by creating a JSON file in: </p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/META-INF/cxs/conditions +</pre> + </div> + </div> + <p>Here is an example of a JSON file that defines a profileUpdateEventCondition that inherits from a parent condition of type eventTypeCondition. </p> + <div class="source"> + <div class="source"> + <pre>{ + "metadata": { + "id": "profileUpdatedEventCondition", + "name": "profileUpdatedEventCondition", + "description": "", + "tags": [ + "event", + "eventCondition" + ], + "readOnly": true + }, + "parentCondition": { + "type": "eventTypeCondition", + "parameterValues": { + "eventTypeId": "profileUpdated" + } + }, + + "parameters": [ + ] +} +</pre> + </div> + </div> +</div> +<div class="section"> + <h2 id="Predefined_personas">Predefined personas</h2> + <p>Personas may also be pre-defined by creating JSON files in the following directory:</p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/META-INF/cxs/personas +</pre> + </div> + </div> + <p>Here is an example of a persona definition JSON file: </p> + <div class="source"> + <div class="source"> + <pre>{ + "persona": { + "itemId": "usVisitor", + "properties": { + "description": "Represents a visitor browsing from inside the continental US", + "firstName": "U.S.", + "lastName": "Visitor" + }, + "segments": [] + }, + "sessions": [ + { + "itemId": "aa3b04bd-8f4d-4a07-8e96-d33ffa04d3d9", + "profileId": "usVisitor", + "properties": { + "operatingSystemName": "OS X 10.9 Mavericks", + "sessionCountryName": "United States", + "location": { + "lat":37.422, + "lon":-122.084058 + }, + "userAgentVersion": "37.0.2062.120", + "sessionCountryCode": "US", + "deviceCategory": "Personal computer", + "operatingSystemFamily": "OS X", + "userAgentName": "Chrome", + "sessionCity": "Mountain View", + "remoteHost": "www.google.com", + "remoteAddr": "66.249.66.1" + }, + "timeStamp": "2014-09-18T11:40:54Z", + "lastEventDate": "2014-09-18T11:40:59Z", + "duration": 4790 + } + ] +} +</pre> + </div> + </div> + <p>You can see that itâs also possible to define sessions for personas.</p> +</div> +<div class="section"> + <h2 id="Custom_actions">Custom actions</h2> + <p>Custom actions are a powerful way to integrate with external systems by being able to define custom logic that will be executed by an Apache Unomi rule. An action is defined by a JSON file created in the following directory:</p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/META-INF/cxs/actions +</pre> + </div> + </div> + <p>Here is an example of a JSON action definition:</p> + <div class="source"> + <div class="source"> + <pre>{ + "metadata": { + "id": "addToListsAction", + "name": "addToListsAction", + "description": "", + "tags": [ + "demographic", + "hidden.availableToEndUser" + ], + "readOnly": true + }, + "actionExecutor": "addToLists", + "parameters": [ + { + "id": "listIdentifiers", + "type": "string", + "multivalued": true + } + ] +} +</pre> + </div> + </div> + <p>The <tt>actionExecutor</tt> identifier refers to a service property that is defined in the OSGi Blueprint service registration. Note that any OSGi service registration may be used, but in these examples we use OSGi Blueprint. The definition for the above JSON file will be found in a file called <tt>src/main/resources/OSGI-INF/blueprint/blueprint.xml</tt> with the following content:</p> + <div class="source"> + <div class="source"> + <pre><?xml version="1.0" encoding="UTF-8"?> +<blueprint xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" + xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd"> + + <reference id="profileService" interface="org.apache.unomi.api.services.ProfileService"/> + <reference id="eventService" interface="org.apache.unomi.api.services.EventService"/> + + <!-- Action executors --> + + <service auto-export="interfaces"> + <service-properties> + <entry key="actionExecutorId" value="addToLists"/> + </service-properties> + <bean class="org.apache.unomi.lists.actions.AddToListsAction"> + <property name="profileService" ref="profileService"/> + <property name="eventService" ref="eventService"/> + </bean> + </service> + +</blueprint> +</pre> + </div> + </div> + <p>You can note here the <tt>actionExecutorId</tt> that corresponds to the <tt>actionExecutor</tt> in the JSON file.</p> + <p>The implementation of the action is available here : <a class="externalLink" href="https://github.com/apache/incubator-unomi/blob/master/extensions/lists-extension/actions/src/main/java/org/apache/unomi/lists/actions/AddToListsAction.java";>org.apache.unomi.lists.actions.AddToListsAction</a> </p> +</div> +<div class="section"> + <h2 id="Custom_conditions">Custom conditions</h2> + <p>Custom conditions are different from predefined child conditions because they implement their logic using Java classes. They are also declared by adding a JSON file into the conditions directory:</p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/META-INF/cxs/conditions +</pre> + </div> + </div> + <p>Here is an example of JSON custom condition definition:</p> + <div class="source"> + <div class="source"> + <pre>{ + "metadata": { + "id": "matchAllCondition", + "name": "matchAllCondition", + "description": "", + "tags": [ + "logical", + "profileCondition", + "eventCondition", + "sessionCondition", + "sourceEventCondition" + ], + "readOnly": true + }, + "conditionEvaluator": "matchAllConditionEvaluator", + "queryBuilder": "matchAllConditionESQueryBuilder", + + "parameters": [ + ] +} +</pre> + </div> + </div> + <p>Note the <tt>conditionEvaluator</tt> and the <tt>queryBuilder</tt> values. These reference OSGi service properties that are declared in an OSGi Blueprint configuration file (other service definitions may also be used such as Declarative Services or even Java registered services). Here is an example of an OSGi Blueprint definition corresponding to the above JSON condition definition file.</p> + <div class="source"> + <div class="source"> + <pre>src/main/resources/OSGI-INF/blueprint/blueprint.xml + +<blueprint xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" + xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd"> + + <service + interface="org.apache.unomi.persistence.elasticsearch.conditions.ConditionESQueryBuilder"> + <service-properties> + <entry key="queryBuilderId" value="matchAllConditionESQueryBuilder"/> + </service-properties> + <bean class="org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionESQueryBuilder"/> + </service> + + <service interface="org.apache.unomi.persistence.elasticsearch.conditions.ConditionEvaluator"> + <service-properties> + <entry key="conditionEvaluatorId" value="matchAllConditionEvaluator"/> + </service-properties> + <bean class="org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionEvaluator"/> + </service> + +</blueprint> +</pre> + </div> + </div> + <p>You can find the implementation of the two classes here : </p> + <ul> + <li><a class="externalLink" href="https://github.com/apache/incubator-unomi/blob/master/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/MatchAllConditionESQueryBuilder.java";>org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionESQueryBuilder</a></li> + <li><a class="externalLink" href="https://github.com/apache/incubator-unomi/blob/master/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/MatchAllConditionEvaluator.java";>org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionEvaluator</a></li> + </ul> +</div> + </div> + </div> + <div class="span4"> + <div id="toc-sidebar"> + <div class="well"> + <ul class="nav nav-list"> + <li class="nav-header">Table of Contents</li> + <li class="dropdown"><a href="#custom_extensions" title="Custom extensions">Custom extensions <b class="caret"></b></a> + <ul class="nav nav-list"> + <li><a href="#Creating_an_extension" title="Creating an extension">Creating an extension</a> + <li><a href="#Predefined_segments" title="Predefined segments">Predefined segments</a> + <li><a href="#Predefined_rules" title="Predefined rules">Predefined rules</a> + <li><a href="#Predefined_properties" title="Predefined properties">Predefined properties</a> + <li><a href="#Predefined_child_conditions" title="Predefined child conditions">Predefined child conditions</a> + <li><a href="#Predefined_personas" title="Predefined personas">Predefined personas</a> + <li><a href="#Custom_actions" title="Custom actions">Custom actions</a> + <li><a href="#Custom_conditions" title="Custom conditions">Custom conditions</a> + <li class="divider"></li> + </ul> + </li> + </ul> + </div> + </div> + </div> + </div> + </div> + + </div><!-- /container --> + + <!-- Footer + ================================================== --> + <footer class="well"> + <div class="container"> + <div class="row"> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Download</li> + <li > + <a href="../../download.html" title="Packages">Packages</a> + </li> + <li > + <a href="../../license.html" title="License">License</a> + </li> + <li class="nav-header">Contribute</li> + <li > + <a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a> + </li> + <li > + <a href="../../source-repository.html" title="Source">Source</a> + </li> + <li > + <a href="../../issue-tracking.html" title="Issues">Issues</a> + </li> + </ul> + </div> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Documentation</li> + <li > + <a href="../../" title="Site Home">Site Home</a> + </li> + <li > + <a href="../../main.html" title="Main documentation">Main documentation</a> + </li> + <li > + <a href="../../usecases.html" title="More use cases">More use cases</a> + </li> + <li > + <a href="../../rest-api-doc/index.html" title="REST API documentation">REST API documentation</a> + </li> + <li > + <a href="../../unomi-api/apidocs/index.html" title="API Javadoc">API Javadoc</a> + </li> + </ul> + </div> + <div class="span2 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Standard</li> + <li > + <a href="https://www.oasis-open.org/committees/cxs/"; title="OASIS Context Server Technical Committee" class="externalLink">OASIS Context Server Technical Committee</a> + </li> + <li class="nav-header">Privacy</li> + <li > + <a href="../../privacy-policy.html" title="Site policy">Site policy</a> + </li> + <li class="nav-header">Community</li> + <li > + <a href="../../mail-lists.html" title="Mailing lists">Mailing lists</a> + </li> + <li > + <a href="../../team-list.html" title="Team">Team</a> + </li> + <li > + <a href="../../maturity-model-report.html" title="Maturity model report card">Maturity model report card</a> + </li> + <li > + <a href="http://www.apache.org"; title="The Apache Software Foundation" class="externalLink">The Apache Software Foundation</a> + </li> + <li > + <a href="http://www.apache.org/foundation/sponsorship.html"; title="Sponsorship" class="externalLink">Sponsorship</a> + </li> + <li > + <a href="http://www.apache.org/foundation/thanks.html"; title="Thanks" class="externalLink">Thanks</a> + </li> + </ul> + </div> + <div class="span3 bottom-nav"> + <ul class="nav nav-list"> + <li class="nav-header">Project Documentation</li> + <li > + <a href="../../project-info.html" title="Project Information">Project Information <i class="icon-chevron-right"></i></a> + </li> + </ul> + </div> + <div class="span3 bottom-description"> + <blockquote>Powered by Apache Karaf</blockquote> + </div> + </div> + </div> + </footer> + + <div class="container subfooter"> + <div class="row"> + <div class="span12"> + <p class="pull-right"><a href="#">Back to top</a></p> + <p class="copyright">Copyright ©2014-2017 <a href="http://www.apache.org";>Apache Software Foundation</a>. All Rights Reserved.</p> + <p><a href="http://github.com/andriusvelykis/reflow-maven-skin"; title="Reflow Maven skin">Reflow Maven skin</a> by <a href="http://andrius.velykis.lt"; target="_blank" title="Andrius Velykis">Andrius Velykis</a>.</p> + </div> + </div> + </div> + + <!-- Le javascript + ================================================== --> + <!-- Placed at the end of the document so the pages load faster --> + <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js";></script> + + <script src="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.2/js/bootstrap.min.js";></script> + <script src="../..//js/lightbox.min.js"></script> + <script src="../..//js/reflow-scroll.js"></script> + <script src="http://yandex.st/highlightjs/7.5/highlight.min.js";></script> + + <script src="../..//js/reflow-skin.js"></script> + + </body> +</html> \ No newline at end of file
![http://unomi.incubator.apache.org/images/unomi-86x20.png"](http://unomi.incubator.apache.org/images/unomi-86x20.png"){kind=link}