You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@unomi.apache.org by sh...@apache.org on 2018/11/05 13:51:53 UTC
svn commit: r1845788 [2/3] - in /incubator/unomi/website/manual: 1_3_x/
1_3_x/asciidoc/ 1_3_x/asciidoc/connectors/ 1_3_x/asciidoc/images/
1_3_x/asciidoc/samples/ latest/
Added: incubator/unomi/website/manual/1_3_x/asciidoc/configuration.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/configuration.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/configuration.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/configuration.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,529 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Configuration</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_configuration">Configuration</a></li>
+<li><a href="#_important">Important !</a></li>
+<li><a href="#_installation_steps">Installation steps</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="sect2">
+<h3 id="_configuration">Configuration</h3>
+<div class="sect3">
+<h4 id="_changing_the_default_configuration">Changing the default configuration</h4>
+<div class="paragraph">
+<p>If you want to change the default configuration, you can perform any modification you want in the $MY_KARAF_HOME/etc directory.</p>
+</div>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>contextserver.publicAddress=https://localhost:9443
+contextserver.internalAddress=http://127.0.0.1:8181</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>To change these settings, you will need to modify a file called</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>$MY_KARAF_HOME/etc/org.apache.unomi.persistence.elasticsearch.cfg</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>with the following contents:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>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</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_secured_events_configuration">Secured events configuration</h4>
+<div class="paragraph">
+<p>Unomi secures some events by default. You can find the default configuration in the following file (created after the
+first server startup):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>$MY_KARAF_HOME/etc/org.apache.unomi.thirdparty.cfg</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>thirdparty.provider1.key=secret-key
+thirdparty.provider1.ipAddresses=127.0.0.1,::1
+thirdparty.provider1.allowedEvents=login,updateProperties</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_installing_the_maxmind_geoiplite2_ip_lookup_database">Installing the MaxMind GeoIPLite2 IP lookup database</h4>
+<div class="paragraph">
+<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 href="http://dev.maxmind.com/geoip/geoip2/geolite2/">http://dev.maxmind.com/geoip/geoip2/geolite2/</a></p>
+</div>
+<div class="paragraph">
+<p>Simply download the GeoLite2-City.mmdb file into the "etc" directory.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_installing_geonames_database">Installing Geonames database</h4>
+<div class="paragraph">
+<p>Context server includes a geocoding service based on the geonames database ( <a href="http://www.geonames.org/">http://www.geonames.org/</a> ). It can be
+used to create conditions on countries or cities.</p>
+</div>
+<div class="paragraph">
+<p>In order to use it, you need to install the Geonames database into . Get the "allCountries.zip" database from here :
+<a href="http://download.geonames.org/export/dump/">http://download.geonames.org/export/dump/</a></p>
+</div>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_rest_api_security">REST API Security</h4>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>The generated package is also configured with a default SSL certificate. You can change it by following these steps :</p>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Replace the existing keystore in $MY_KARAF_HOME/etc/keystore by your own certificate :</p>
+</div>
+<div class="paragraph">
+<p><a href="http://wiki.eclipse.org/Jetty/Howto/Configure_SSL">http://wiki.eclipse.org/Jetty/Howto/Configure_SSL</a></p>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Update the keystore and certificate password in $MY_KARAF_HOME/etc/custom.properties file :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code> 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</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Changing the default Karaf password can be done by modifying the etc/users.properties file</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_automatic_profile_merging">Automatic profile merging</h4>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_securing_a_production_environment">Securing a production environment</h4>
+<div class="paragraph">
+<p>Before going live with a project, you should <em>absolutely</em> read the following section that will help you setup a proper
+secure environment for running your context server.</p>
+</div>
+<div class="paragraph">
+<p>Step 1: Install and configure a firewall</p>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="http://localhost:8181/context.js">http://localhost:8181/context.js</a></p>
+</li>
+<li>
+<p><a href="http://localhost:8181/eventcollector">http://localhost:8181/eventcollector</a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>All other ports should not be accessible to the world.</p>
+</div>
+<div class="paragraph">
+<p>For your Context Server client applications (such as the Jahia CMS), you will need to make the following ports
+accessible :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>8181 (Context Server HTTP port)
+9443 (Context Server HTTPS port)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="http://karaf.apache.org/manual/latest/users-guide/security.html">http://karaf.apache.org/manual/latest/users-guide/security.html</a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The default username/password is</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>karaf/karaf</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You should really change this default username/password as soon as possible. To do so, simply modify the following
+file :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>$MY_KARAF_HOME/etc/users.properties</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>Of course any ports listed here are the default ports configured in each server, you may adjust them if needed.</p>
+</div>
+<div class="paragraph">
+<p>Step 2 : Follow industry recommended best practices for securing Elasticsearch</p>
+</div>
+<div class="paragraph">
+<p>You may find more valuable recommendations here :</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="https://www.elastic.co/blog/found-elasticsearch-security">https://www.elastic.co/blog/found-elasticsearch-security</a></p>
+</li>
+<li>
+<p><a href="https://www.elastic.co/blog/scripting-security">https://www.elastic.co/blog/scripting-security</a></p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Step 4 : Setup a proxy in front of the context server</p>
+</div>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_integrating_with_an_apache_http_web_server">Integrating with an Apache HTTP web server</h4>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>In your Unomi package directory, in /etc/org.apache.unomi.cluster.cfg for unomi.apache.org</p>
+</div>
+<div class="paragraph">
+<p>contextserver.publicAddress=https://unomi.apache.org/
+ contextserver.internalAddress=http://192.168.1.1:8181</p>
+</div>
+<div class="paragraph">
+<p>and you will also need to change the contextserver.domain in the /etc/org.apache.unomi.web.cfg file</p>
+</div>
+<div class="paragraph">
+<p>contextserver.domain=apache.org</p>
+</div>
+<div class="paragraph">
+<p>Main virtual host config:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code><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></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>common.conf:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>ServerName unomi.apache.org
+ServerAdmin webmaster@apache.org
+
+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/</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_changing_the_default_tracking_location">Changing the default tracking location</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>org.apache.unomi.plugins.request.cfg</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>that contains the following default settings:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code># 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</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You might want to change these for testing or for demonstration purposes.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_apache_karaf_ssh_console">Apache Karaf SSH Console</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>ssh -p 8102 karaf@localhost</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>or the user/password you have setup to protect the system if you have changed it.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_elasticsearch_x_pack_support">ElasticSearch X-Pack Support</h4>
+<div class="paragraph">
+<p>It is now possible to use X-Pack to connect to ElasticSearch. However, for licensing reasons this is not provided out
+of the box. Here is the procedure to install X-Pack with Apache Unomi:</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_important">Important !</h3>
+<div class="paragraph">
+<p>Do not start Unomi directly with unomi:start, perform the following steps below first !</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_installation_steps">Installation steps</h3>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Create a directory for all the JARs that you will download, we will call it XPACK_JARS_DIRECTORY</p>
+</li>
+<li>
+<p>Download <a href="https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/5.6.3/x-pack-transport-5.6.3.jar">https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/5.6.3/x-pack-transport-5.6.3.jar</a> to XPACK_JARS_DIRECTORY</p>
+</li>
+<li>
+<p>Download <a href="https://artifacts.elastic.co/maven/org/elasticsearch/plugin/x-pack-api/5.6.3/x-pack-api-5.6.3.jar">https://artifacts.elastic.co/maven/org/elasticsearch/plugin/x-pack-api/5.6.3/x-pack-api-5.6.3.jar</a> to XPACK_JARS_DIRECTORY</p>
+</li>
+<li>
+<p>Download <a href="http://central.maven.org/maven2/com/unboundid/unboundid-ldapsdk/3.2.0/unboundid-ldapsdk-3.2.0.jar">http://central.maven.org/maven2/com/unboundid/unboundid-ldapsdk/3.2.0/unboundid-ldapsdk-3.2.0.jar</a> to XPACK_JARS_DIRECTORY</p>
+</li>
+<li>
+<p>Download <a href="http://central.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.55/bcpkix-jdk15on-1.55.jar">http://central.maven.org/maven2/org/bouncycastle/bcpkix-jdk15on/1.55/bcpkix-jdk15on-1.55.jar</a> to XPACK_JARS_DIRECTORY</p>
+</li>
+<li>
+<p>Download <a href="http://central.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.55/bcprov-jdk15on-1.55.jar">http://central.maven.org/maven2/org/bouncycastle/bcprov-jdk15on/1.55/bcprov-jdk15on-1.55.jar</a> to XPACK_JARS_DIRECTORY</p>
+</li>
+<li>
+<p>Download <a href="http://central.maven.org/maven2/com/sun/mail/javax.mail/1.5.3/javax.mail-1.5.3.jar">http://central.maven.org/maven2/com/sun/mail/javax.mail/1.5.3/javax.mail-1.5.3.jar</a> to XPACK_JARS_DIRECTORY
+.</p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>Edit etc/org.apache.unomi.persistence.elasticsearch.cfg to add the following settings:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>transportClientClassName=org.elasticsearch.xpack.client.PreBuiltXPackTransportClient
+transportClientJarDirectory=XPACK_JARS_DIRECTORY
+transportClientProperties=xpack.security.user=elastic:changeme</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can setup more properties (for example for SSL/TLS support) by seperating the properties with commas,
+as in the following example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>transportClientProperties=xpack.security.user=elastic:changeme,xpack.ssl.key=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.key,xpack.ssl.certificate=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.crt,xpack.ssl.certificate_authorities=/home/user/elasticsearch-5.6.3/config/x-pack/ca/ca.crt,xpack.security.transport.ssl.enabled=true</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Launch Karaf and launch unomi using the command from the shell :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>unomi:start</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Alternatively you could edit the configuration directly from the Karaf shell using the following commands:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>config:edit org.apache.unomi.persistence.elasticsearch
+config:property-set transportClientClassName org.elasticsearch.xpack.client.PreBuiltXPackTransportClient
+config:property-set transportClientJarDirectory XPACK_JARS_DIRECTORY
+config:property-set transportClientProperties xpack.security.user=elastic:changeme
+config:update
+unomi:start</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can setup more properties (for example for SSL/TLS support) by seperating the properties with commas,
+as in the following example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>config:property-set transportClientProperties xpack.security.user=elastic:changeme,xpack.ssl.key=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.key,xpack.ssl.certificate=/home/user/elasticsearch-5.6.3/config/x-pack/localhost/localhost.crt,xpack.ssl.certificate_authorities=/home/user/elasticsearch-5.6.3/config/x-pack/ca/ca.crt,xpack.security.transport.ssl.enabled=true</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/connectors/connectors.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/connectors/connectors.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/connectors/connectors.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/connectors/connectors.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Connectors</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_connectors">Connectors</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="sect2">
+<h3 id="_connectors">Connectors</h3>
+<div class="paragraph">
+<p>Apache Unomi provides the following connectors:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="salesforce-connectors.html">Salesforce CRM connectors</a></p>
+</li>
+</ul>
+</div>
+<div class="sect3">
+<h4 id="_call_for_contributors">Call for contributors</h4>
+<div class="paragraph">
+<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>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/connectors/salesforce-connector.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/connectors/salesforce-connector.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/connectors/salesforce-connector.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/connectors/salesforce-connector.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,286 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Apache Unomi Salesforce Connector</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_apache_unomi_salesforce_connector">Apache Unomi Salesforce Connector</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="sect2">
+<h3 id="_apache_unomi_salesforce_connector">Apache Unomi Salesforce Connector</h3>
+<div class="paragraph">
+<p>This connectors makes it possible to push and pull data to/from the Salesforce CRM. It can copy information between
+Apache Unomi profiles and Salesforce Leads.</p>
+</div>
+<div class="sect3">
+<h4 id="_getting_started">Getting started</h4>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Create a new developer account here:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>https://developer.salesforce.com/signup</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Create a new Connected App, by going into Setup -> App Manager and click "Create Connected App"</p>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>In the settings, make sure you do the following:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>Enable OAuth settings -> Activated
+Enable for device flow -> Activated (no need for a callback URL)
+Add all the selected OAuth scopes you want (or put all of them)
+Make sure Require Secret for Web Server flow is activated</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Make sure you retrieve the following information once you have created the app in the API (Enable OAuth Settings):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>Consumer key
+Consumer secret (click to see it)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>You must also retrieve your user’s security token, or create it if you don’t have one already. To do this simply
+click on your user at the top right, select "Settings", the click on "Reset my security token". You will receive an email
+with the security token.</p>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>You are now ready to configure the Apache Unomi Salesforce Connector. In the etc/org.apache.unomi.sfdc.cfg file
+change the following settings:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>sfdc.user.username=YOUR_USER_NAME
+sfdc.user.password=YOUR_PASSWORD
+sfdc.user.securityToken=YOUR_USER_SECURITY_TOKEN
+sfdc.consumer.key=CONNECTED_APP_CONSUMER_KEY
+sfdc.consumer.secret=CONNECTED_APP_SECRET</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Connected to the Apache Unomi Karaf Shell using :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>ssh -p 8102 karaf@localhost (default password is karaf)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Deploy into Apache Unomi using the following commands from the Apache Karaf shell:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>feature:repo-add mvn:org.apache.unomi/unomi-salesforce-connectors-karaf-kar/${project.version}/xml/features
+feature:install unomi-salesforce-connectors-karaf-kar</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>You can then test the connection to Salesforce by accessing the following URLs:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>https://localhost:9443/cxs/sfdc/version
+https://localhost:9443/cxs/sfdc/limits</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The first URL will give you information about the version of the connectors, so this makes it easy to check that the
+plugin is properly deployed, started and the correct version. The second URL will actually make a request to the
+Salesforce REST API to retrieve the limits of the Salesforce API.</p>
+</div>
+<div class="paragraph">
+<p>Both URLs are password protected by the Apache Unomi (Karaf) password. You can find this user and password information
+in the etc/users.properties file.</p>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>You can now use the connectors’s defined actions in rules to push or pull data to/from the Salesforce CRM. You can
+find more information about rules in the <a href="concepts.html">Concepts</a> and the <a href="getting-started.html">Getting Started</a> pages.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_upgrading_the_salesforce_connectors">Upgrading the Salesforce connectors</h4>
+<div class="paragraph">
+<p>If you followed all the steps in the Getting Started section, you can upgrade the Salesforce connectors by using the following steps:</p>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Compile the connectors using:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>cd extensions/salesforce-connectors
+mvn clean install</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Login to the Unomi Karaf Shell using:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>ssh -p 8102 karaf@localhost (password by default is karaf)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>Execute the following commands in the Karaf shell</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>feature:repo-refresh
+feature:uninstall unomi-salesforce-connectors-karaf-feature
+feature:install unomi-salesforce-connectors-karaf-feature</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>.</p>
+</div>
+<div class="paragraph">
+<p>You can then check that the new version is properly deployed by accessing the following URL and checking the build date:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>https://localhost:9443/cxs/sfdc/version</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(if asked for a password it’s the same karaf/karaf default)</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_using_the_salesforce_workbench_for_testing_rest_api">Using the Salesforce Workbench for testing REST API</h4>
+<div class="paragraph">
+<p>The Salesforce Workbench contains a REST API Explorer that is very useful to test requests. You may find it here :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>https://workbench.developerforce.com/restExplorer.php</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_setting_up_streaming_push_queries">Setting up Streaming Push queries</h4>
+<div class="paragraph">
+<p>Using the Salesforce Workbench, you can setting streaming push queries (Queries->Streaming push topics) such as the
+following example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>Name: LeadUpdates
+Query : SELECT Id,FirstName,LastName,Email,Company FROM Lead</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_executing_the_unit_tests">Executing the unit tests</h4>
+<div class="paragraph">
+<p>Before running the tests, make sure you have completed all the steps above, including the streaming push queries setup.</p>
+</div>
+<div class="paragraph">
+<p>By default the unit tests will not run as they need proper Salesforce credentials to run. To set this up create a
+properties file like the following one:</p>
+</div>
+<div class="paragraph">
+<p>test.properties</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>#
+# 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.
+#
+sfdc.user.username=YOUR_USER_NAME
+sfdc.user.password=YOUR_PASSWORD
+sfdc.user.securityToken=YOUR_USER_SECURITY_TOKEN
+sfdc.consumer.key=CONNECTED_APP_CONSUMER_KEY
+sfdc.consumer.secret=CONNECTED_APP_SECRET</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>and then use the following command line to reference the file:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>cd extensions/salesforce-connectors
+mvn clean install -DsfdcProperties=../test.properties</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(in case you’re wondering the ../ is because the test is located in the services sub-directory)</p>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/consent-api.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/consent-api.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/consent-api.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/consent-api.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,185 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Consent API</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_consent_api">Consent API</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="sect2">
+<h3 id="_consent_api">Consent API</h3>
+<div class="paragraph">
+<p>Starting with Apache Unomi 1.3 (still in development), a new API for consent management is now available. This API
+is designed to be able to store/retrieve/update visitor consents in order to comply with new
+privacy regulations such as the <a href="https://en.wikipedia.org/wiki/General_Data_Protection_Regulation">GDPR</a>.</p>
+</div>
+<div class="sect3">
+<h4 id="_profiles_with_consents">Profiles with consents</h4>
+<div class="paragraph">
+<p>Visitor profiles now contain a new Consent object that contains the following information:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>a scope</p>
+</li>
+<li>
+<p>a type identifier for the consent. This can be any key to reference a consent. Note that Unomi does not manage consent
+definitions, it only stores/retrieves consents for each profile based on this type</p>
+</li>
+<li>
+<p>a status : GRANT, DENY or REVOKED</p>
+</li>
+<li>
+<p>a status date (the date at which the status was updated)</p>
+</li>
+<li>
+<p>a revocation date, in order to comply with GDPR this is usually set at two years</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Here is an example of a Profile with a consent attached to it:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "profileId": "8cbe380f-57bb-419d-97bf-24bf30178550",
+ "sessionId": "0d755f4e-154a-45c8-9169-e852e1d706d9",
+ "consents": {
+ "example/newsletter": {
+ "scope": "example",
+ "typeIdentifier": "newsletter",
+ "status": "GRANTED",
+ "statusDate": "2018-05-22T09:44:33Z",
+ "revokeDate": "2020-05-21T09:44:33Z"
+ }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>It is of course possible to have multiple consents defined for a single visitor profile.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_consent_type_definitions">Consent type definitions</h4>
+<div class="paragraph">
+<p>Apache Unomi does not manage consent definitions, it leaves that to an external system (for example a CMS) so that it
+can handle user-facing UIs to create, update, internationalize and present consent definitions to end users.</p>
+</div>
+<div class="paragraph">
+<p>The only thing that is import to Apache Unomi to manage visitor consents is a globally unique key, that is called the
+consent type.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_creating_update_a_visitor_consent">Creating / update a visitor consent</h4>
+<div class="paragraph">
+<p>A new built-in event type called "modifyConsent" can be sent to Apache Unomi to update a consent for the current
+profile.</p>
+</div>
+<div class="paragraph">
+<p>Here is an example of such an event:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "events": [
+ {
+ "scope": "example",
+ "eventType": "modifyConsent",
+ "source": {
+ "itemType": "page",
+ "scope": "example",
+ "itemId": "anItemId"
+ },
+ "target": {
+ "itemType": "anyType",
+ "scope": "example",
+ "itemId": "anyItemId"
+ },
+ "properties": {
+ "consent": {
+ "typeIdentifier": "newsletter",
+ "scope": "example",
+ "status": "GRANTED",
+ "statusDate": "2018-05-22T09:27:09.473Z",
+ "revokeDate": "2020-05-21T09:27:09.473Z"
+ }
+ }
+ }
+ ]
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You could send it using the following curl request:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -H "Content-Type: application/json" -X POST -d '{"source":{"itemId":"homepage","itemType":"page","scope":"example"},"events":[{"scope":"example","eventType":"modifyConsent","source":{"itemType":"page","scope":"example","itemId":"anItemId"},"target":{"itemType":"anyType","scope":"example","itemId":"anyItemId"},"properties":{"consent":{"typeIdentifier":"newsletter","scope":"example","status":"GRANTED","statusDate":"2018-05-22T09:27:09.473Z","revokeDate":"2020-05-21T09:27:09.473Z"}}}]}' http://localhost:8181/context.json?sessionId=1234</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_how_it_works_internally">How it works (internally)</h4>
+<div class="paragraph">
+<p>Upon receiving this event, Apache Unomi will trigger the modifyAnyConsent rule that has the following definition:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "metadata" : {
+ "id": "modifyAnyConsent",
+ "name": "Modify any consent",
+ "description" : "Modify any consent and sets the consent in the profile",
+ "readOnly":true
+ },
+
+ "condition" : {
+ "type": "modifyAnyConsentEventCondition",
+ "parameterValues": {
+ }
+ },
+
+ "actions" : [
+ {
+ "type": "modifyConsentAction",
+ "parameterValues": {
+ }
+ }
+ ]
+
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As we can see this rule is pretty simple it will simply execute the modifyConsentAction that is implemented by the
+<a href="https://github.com/apache/incubator-unomi/blob/9f1bab437fd93826dc54d318ed00d3b2e3161437/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/actions/ModifyConsentAction.java">ModifyConsentAction Java class</a></p>
+</div>
+<div class="paragraph">
+<p>This class will update the current visitor profile to add/update/revoke any consents that are included in the event.</p>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/custom-extensions.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/custom-extensions.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/custom-extensions.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/custom-extensions.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,478 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Custom extensions</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_custom_extensions">Custom extensions</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="sect2">
+<h3 id="_custom_extensions">Custom extensions</h3>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_creating_an_extension">Creating an extension</h4>
+<div class="paragraph">
+<p>An extension is simply a Maven project, with a Maven pom that looks like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code><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>${project.version}</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>${project.version}</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>${project.version}</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></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_deployment_and_custom_definition">Deployment and custom definition</h4>
+<div class="paragraph">
+<p>When you deploy a custom bundle with a custom definition (see "Predefined xxx" chapters under) for the first time, the definition will automatically be deployed at your bundle start event <strong>if it does not exist</strong>, after that if you redeploy the same bundle there are two cases:
+1. Your bundle <strong>is a SNAPSHOT</strong> then every time you redeploy it the definition will be redeployed
+2. Your bundle <strong>is NOT a SNAPSHOT</strong> then the definition will not be redeployed, but you can redeploy it manually using the command <code>unomi:deploy-definition <bundleId> <fileName></code></p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_predefined_segments">Predefined segments</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "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"
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Basically this segment uses a condition to test if the profile has a property <code>leadAssignedTo</code> that exists. All profiles
+that match this condition will be part of the pre-defined segment.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_predefined_rules">Predefined rules</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "metadata" : {
+ "id": "evaluateProfileSegments",
+ "name": "Evaluate segments",
+ "description" : "Evaluate segments when a profile is modified",
+ "readOnly":true
+ },
+
+ "condition" : {
+ "type": "profileUpdatedEventCondition",
+ "parameterValues": {
+ }
+ },
+
+ "actions" : [
+ {
+ "type": "evaluateProfileSegmentsAction",
+ "parameterValues": {
+ }
+ }
+ ]
+
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>
+<div class="sect3">
+<h4 id="_predefined_properties">Predefined properties</h4>
+<div class="paragraph">
+<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>
+</div>
+<div class="paragraph">
+<p>For session properties you must create a JSON file in the following directory in your Maven project:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>src/main/resources/META-INF/cxs/properties/sessions</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>For profile properties you must create the JSON file inside the directory in your Maven project:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>src/main/resources/META-INF/cxs/properties/profiles</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here is an example of a property definition JSON file</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "metadata": {
+ "id": "city",
+ "name": "City",
+ "systemTags": ["properties", "profileProperties", "contactProfileProperties"]
+ },
+ "type": "string",
+ "defaultValue": "",
+ "automaticMappingsFrom": [ ],
+ "rank": "304.0"
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_predefined_child_conditions">Predefined child conditions</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>src/main/resources/META-INF/cxs/conditions</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here is an example of a JSON file that defines a profileUpdateEventCondition that inherits from a parent condition of
+type eventTypeCondition.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "metadata": {
+ "id": "profileUpdatedEventCondition",
+ "name": "profileUpdatedEventCondition",
+ "description": "",
+ "systemTags": [
+ "event",
+ "eventCondition"
+ ],
+ "readOnly": true
+ },
+ "parentCondition": {
+ "type": "eventTypeCondition",
+ "parameterValues": {
+ "eventTypeId": "profileUpdated"
+ }
+ },
+
+ "parameters": [
+ ]
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_predefined_personas">Predefined personas</h4>
+<div class="paragraph">
+<p>Personas may also be pre-defined by creating JSON files in the following directory:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>src/main/resources/META-INF/cxs/personas</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here is an example of a persona definition JSON file:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "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"
+ },
+ "timeStamp": "2014-09-18T11:40:54Z",
+ "lastEventDate": "2014-09-18T11:40:59Z",
+ "duration": 4790
+ }
+ ]
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can see that it’s also possible to define sessions for personas.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_custom_actions">Custom actions</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>src/main/resources/META-INF/cxs/actions</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here is an example of a JSON action definition:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "metadata": {
+ "id": "addToListsAction",
+ "name": "addToListsAction",
+ "description": "",
+ "systemTags": [
+ "demographic",
+ "availableToEndUser"
+ ],
+ "readOnly": true
+ },
+ "actionExecutor": "addToLists",
+ "parameters": [
+ {
+ "id": "listIdentifiers",
+ "type": "string",
+ "multivalued": true
+ }
+ ]
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <code>actionExecutor</code> 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 <code>src/main/resources/OSGI-INF/blueprint/blueprint.xml</code> with the following
+content:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code><?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 interface="org.apache.unomi.api.actions.ActionExecutor">
+ <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></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can note here the <code>actionExecutorId</code> that corresponds to the <code>actionExecutor</code> in the JSON file.</p>
+</div>
+<div class="paragraph">
+<p>The implementation of the action is available here : <a 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>
+<div class="sect3">
+<h4 id="_custom_conditions">Custom conditions</h4>
+<div class="paragraph">
+<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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>src/main/resources/META-INF/cxs/conditions</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here is an example of JSON custom condition definition:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>{
+ "metadata": {
+ "id": "matchAllCondition",
+ "name": "matchAllCondition",
+ "description": "",
+ "systemTags": [
+ "logical",
+ "profileCondition",
+ "eventCondition",
+ "sessionCondition",
+ "sourceEventCondition"
+ ],
+ "readOnly": true
+ },
+ "conditionEvaluator": "matchAllConditionEvaluator",
+ "queryBuilder": "matchAllConditionESQueryBuilder",
+
+ "parameters": [
+ ]
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Note the <code>conditionEvaluator</code> and the <code>queryBuilder</code> 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>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>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></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>You can find the implementation of the two classes here :</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a 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></p>
+</li>
+<li>
+<p><a 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></p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/extending-plugins.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/extending-plugins.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/extending-plugins.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/extending-plugins.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,206 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Types vs. instances</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_types_vs_instances">Types vs. instances</a></li>
+<li><a href="#_plugin_structure">Plugin structure</a></li>
+<li><a href="#_extension_points">Extension points</a></li>
+<li><a href="#_other_unomi_entities">Other Unomi entities</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="paragraph">
+<p>Unomi is architected so that users can provided extensions in the form of plugins.</p>
+</div>
+<div class="sect2">
+<h3 id="_types_vs_instances">Types vs. instances</h3>
+<div class="paragraph">
+<p>Several extension points in Unomi rely on the concept of type: the extension defines a prototype for what the actual items will be once parameterized with values known only at runtime. This is similar to the concept of classes in object-oriented programming: types define classes, providing the expected structure and which fields are expected to be provided at runtime, that are then instantiated when needed with actual values.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_plugin_structure">Plugin structure</h3>
+<div class="paragraph">
+<p>Being built on top of Apache Karaf, Unomi leverages OSGi to support plugins. A Unomi plugin is, thus, an OSGi bundle specifying some specific metadata to tell Unomi the kind of entities it provides. A plugin can provide the following entities to extend Unomi, each with its associated definition (as a JSON file), located in a specific spot within the <code>META-INF/cxs/</code> directory of the bundle JAR file:</p>
+</div>
+<table class="tableblock frame-all grid-all spread">
+<colgroup>
+<col style="width: 50%;">
+<col style="width: 50%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Entity</th>
+<th class="tableblock halign-left valign-top">Location in <code>cxs</code> directory</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">ActionType</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">actions</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">ConditionType</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">conditions</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Persona</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">personas</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">PropertyMergeStrategyType</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">mergers</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">PropertyType</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">properties then profiles or sessions subdirectory then <code><category name></code> directory</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Rule</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">rules</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Scoring</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">scorings</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Segment</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">segments</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">ValueType</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">values</p></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p><a href="http://aries.apache.org/modules/blueprint.html">Blueprint</a> is used to declare what the plugin provides and inject any required dependency. The Blueprint file is located, as usual, at <code>OSGI-INF/blueprint/blueprint.xml</code> in the bundle JAR file.</p>
+</div>
+<div class="paragraph">
+<p>The plugin otherwise follows a regular maven project layout and should depend on the Unomi API maven artifact:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-xml" data-lang="xml"><dependency>
+ <groupId>org.apache.unomi</groupId>
+ <artifactId>unomi-api</artifactId>
+ <version>...</version>
+</dependency></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Some plugins consists only of JSON definitions that are used to instantiate the appropriate structures at runtime while some more involved plugins provide code that extends Unomi in deeper ways.</p>
+</div>
+<div class="paragraph">
+<p>In both cases, plugins can provide more that one type of extension. For example, a plugin could provide both `ActionType`s and `ConditionType`s.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_extension_points">Extension points</h3>
+<div class="sect3">
+<h4 id="_actiontype">ActionType</h4>
+<div class="paragraph">
+<p><code>ActionType`s define new actions that can be used as consequences of Rules being triggered. When a rule triggers, it creates new actions based on the event data and the rule internal processes, providing values for parameters defined in the associated `ActionType</code>. Example actions include: âSet user property x to value yâ or âSend a message to service xâ.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_conditiontype">ConditionType</h4>
+<div class="paragraph">
+<p>`ConditionType`s define new conditions that can be applied to items (for example to decide whether a rule needs to be triggered or if a profile is considered as taking part in a campaign) or to perform queries against the stored Unomi data. They may be implemented in Java when attempting to define a particularly complex test or one that can better be optimized by coding it. They may also be defined as combination of other conditions. A simple condition could be: âUser is maleâ, while a more generic condition with parameters may test whether a given property has a specific value: âUser property x has value yâ.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_persona">Persona</h4>
+<div class="paragraph">
+<p>A persona is a "virtual" profile used to represent categories of profiles, and may also be used to test how a personalized experience would look like using this virtual profile. A persona can define predefined properties and sessions. Persona definition make it possible to âemulateâ a certain type of profile, e.g : US visitor, non-US visitor, etc.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_propertymergestrategytype">PropertyMergeStrategyType</h4>
+<div class="paragraph">
+<p>A strategy to resolve how to merge properties when merging profile together.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_propertytype">PropertyType</h4>
+<div class="paragraph">
+<p>Definition for a profile or session property, specifying how possible values are constrained, if the value is multi-valued (a vector of values as opposed to a scalar value). `PropertyType`s can also be categorized using systemTags or file system structure, using sub-directories to organize definition files.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rule">Rule</h4>
+<div class="paragraph">
+<p>`Rule`s are conditional sets of actions to be executed in response to incoming events. Triggering of rules is guarded by a condition: the rule is only triggered if the associated condition is satisfied. That condition can test the event itself, but also the profile or the session. Once a rule triggers, a list of actions can be performed as consequences. Also, when rules trigger, a specific event is raised so that other parts of Unomi can react accordingly.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_scoring">Scoring</h4>
+<div class="paragraph">
+<p>`Scoring`s are set of conditions associated with a value to assign to profiles when matching so that the associated users can be scored along that dimension. Each scoring element is evaluated and matching profiles' scores are incremented with the associated value.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_segments">Segments</h4>
+<div class="paragraph">
+<p>`Segment`s represent dynamically evaluated groups of similar profiles in order to categorize the associated users. To be considered part of a given segment, users must satisfies the segmentâs condition. If they match, users are automatically added to the segment. Similarly, if at any given point during, they cease to satisfy the segmentâs condition, they are automatically removed from it.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_tag">Tag</h4>
+<div class="paragraph">
+<p>`Tag`s are simple labels that are used to classify all other objects inside Unomi.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_valuetype">ValueType</h4>
+<div class="paragraph">
+<p>Definition for values that can be assigned to properties ("primitive" types).</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_other_unomi_entities">Other Unomi entities</h3>
+<div class="sect3">
+<h4 id="_userlist">UserList</h4>
+<div class="paragraph">
+<p>User list are simple static lists of users. The associated profile stores the lists it belongs to in a specific property.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_goal">Goal</h4>
+<div class="paragraph">
+<p>Goals represent tracked activities / actions that can be accomplished by site (or more precisely scope) visitors. These are tracked in general because they relate to specific business objectives or are relevant to measure site/scope performance.</p>
+</div>
+<div class="paragraph">
+<p>Goals can be defined at the scope level or in the context of a particular <code>Campaign</code>. Either types of goals behave exactly the same way with the exception of two notable differences:
+ - duration: scope-level goals are considered until removed while campaign-level goals are only considered for the campaign duration
+ - audience filtering: any visitor is considered for scope-level goals while campaign-level goals only consider visitors who match the campaign’s conditions</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_campaign">Campaign</h4>
+<div class="paragraph">
+<p>A goal-oriented, time-limited marketing operation that needs to be evaluated for return on investment performance by tracking the ratio of visits to conversions.</p>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/getting-started.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/getting-started.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/getting-started.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/getting-started.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,175 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<title>Getting started with Unomi</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article">
+<div id="header">
+<div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel2">
+<li><a href="#_getting_started_with_unomi">Getting started with Unomi</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div class="sect2">
+<h3 id="_getting_started_with_unomi">Getting started with Unomi</h3>
+<div class="paragraph">
+<p>We will first get you up and running with an example. We will then lift the corner of the cover somewhat and explain in greater details what just happened.</p>
+</div>
+<div class="sect3">
+<h4 id="_prerequisites">Prerequisites</h4>
+<div class="paragraph">
+<p>This document assumes that you are already familiar with Unomi’s <a href="concepts.html">concepts</a>. On the technical side, we also assume working knowledge of <a href="https://git-scm.com/">git</a> to be able to retrieve the code for Unomi and the example. Additionnally, you will require a working Java 7 or above install. Refer to <a href="http://www.oracle.com/technetwork/java/javase/">http://www.oracle.com/technetwork/java/javase/</a> for details on how to download and install Java SE 7 or greater.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_running_unomi">Running Unomi</h4>
+<div class="sect4">
+<h5 id="_building_unomi">Building Unomi</h5>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Get the code: <code>git clone <a href="https://git-wip-us.apache.org/repos/asf/incubator-unomi.git" class="bare">https://git-wip-us.apache.org/repos/asf/incubator-unomi.git</a></code></p>
+</li>
+<li>
+<p>Build and install according to the <a href="building-and-deploying.html">instructions</a> and install Unomi.</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_start_unomi">Start Unomi</h5>
+<div class="paragraph">
+<p>Start Unomi according to the <a href="building-and-deploying.html#Deploying_the_generated_package">instructions</a>. Once you have Karaf running,
+ you should wait until you see the following messages on the Karaf console:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>Initializing user list service endpoint...
+Initializing geonames service endpoint...
+Initializing segment service endpoint...
+Initializing scoring service endpoint...
+Initializing campaigns service endpoint...
+Initializing rule service endpoint...
+Initializing profile service endpoint...
+Initializing cluster service endpoint...</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This indicates that all the Unomi services are started and ready to react to requests. You can then open a browser and go to <code><a href="http://localhost:8181/cxs" class="bare">http://localhost:8181/cxs</a></code> to see the list of
+available RESTful services or retrieve an initial context at <code><a href="http://localhost:8181/context.json" class="bare">http://localhost:8181/context.json</a></code> (which isn’t very useful at this point).</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_request_examples">Request examples</h5>
+<div class="sect5">
+<h6 id="_retrieving_your_first_context">Retrieving your first context</h6>
+<div class="paragraph">
+<p>You can retrieve a context using curl like this :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl http://localhost:8181/context.js?sessionId=1234</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This will retrieve a JavaScript script that contains a <code>cxs</code> object that contains the context with the current user
+profile, segments, scores as well as functions that makes it easier to perform further requests (such as collecting
+events using the cxs.collectEvents() function).</p>
+</div>
+</div>
+<div class="sect5">
+<h6 id="_retrieving_a_context_as_a_json_object">Retrieving a context as a JSON object.</h6>
+<div class="paragraph">
+<p>If you prefer to retrieve a pure JSON object, you can simply use a request formed like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl http://localhost:8181/context.json?sessionId=1234</code></pre>
+</div>
+</div>
+</div>
+<div class="sect5">
+<h6 id="_accessing_profile_properties_in_a_context">Accessing profile properties in a context</h6>
+<div class="paragraph">
+<p>By default, in order to optimize the amount of data sent over the network, Apache Unomi will not send the content of
+the profile or session properties. If you need this data, you must send a JSON object to configure the resulting output
+of the context.js(on) servlet.</p>
+</div>
+<div class="paragraph">
+<p>Here is an example that will retrieve all the session and profile properties.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -H "Content-Type: application/json" -X POST -d '{"source":{"itemId":"homepage","itemType":"page","scope":"example"},"requiredProfileProperties":["*"],"requiredSessionProperties":["*"],"requireSegments":true}' http://localhost:8181/context.json?sessionId=1234</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <code>requiredProfileProperties</code> and <code>requiredSessionProperties</code> are properties that take an array of property names
+that should be retrieved. In this case we use the wildcard character '*' to say we want to retrieve all the available
+properties. The structure of the JSON object that you should send is a JSON-serialized version of the <a href="http://unomi.incubator.apache.org/unomi-api/apidocs/org/apache/unomi/api/ContextRequest.html">ContextRequest</a>
+Java class.</p>
+</div>
+</div>
+<div class="sect5">
+<h6 id="_sending_events_using_the_context_servlet">Sending events using the context servlet</h6>
+<div class="paragraph">
+<p>At the same time as you are retrieving the context, you can also directly send events in the ContextRequest object as
+illustrated in the following example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -H "Content-Type: application/json" -X POST -d '{"source":{"itemId":"homepage","itemType":"page","scope":"example"},"events":[{"eventType":"view","scope": "example","source":{"itemType": "site","scope":"example","itemId": "mysite"},"target":{"itemType":"page","scope":"example","itemId":"homepage","properties":{"pageInfo":{"referringURL":""}}}}]}' http://localhost:8181/context.json?sessionId=1234</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Upon received events, Apache Unomi will execute all the rules that match the current context, and return an updated context.
+This way of sending events is usually used upon first loading of a page. If you want to send events after the page has
+finished loading you could either do a second call and get an updating context, or if you don’t need the context and want
+to send events in a network optimal way you can use the eventcollector servlet (see below).</p>
+</div>
+</div>
+<div class="sect5">
+<h6 id="_sending_events_using_the_eventcollector_servlet">Sending events using the eventcollector servlet</h6>
+<div class="paragraph">
+<p>If you only need to send events without retrieving a context, you should use the eventcollector servlet that is optimized
+respond quickly and minimize network traffic. Here is an example of using this servlet:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -H "Content-Type: application/json" -X POST -d '{"events":[{"eventType":"view","scope": "example","source":{"itemType": "site","scope":"example","itemId": "mysite"},"target":{"itemType":"page","scope":"example","itemId":"homepage","properties":{"pageInfo":{"referringURL":""}}}}]}' http://localhost:8181/eventcollector?sessionId=1234</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Note that the eventcollector executes the rules but does not return a context. If is generally used after a page is loaded
+to send additional events.</p>
+</div>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_where_to_go_from_here">Where to go from here</h5>
+<div class="ulist">
+<ul>
+<li>
+<p>Read the <a href="twitter-samples.html">Twitter samples</a> documentation that contains a detailed example of how to integrate with Apache Unomi.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Added: incubator/unomi/website/manual/1_3_x/asciidoc/images/asf_logo_url.png
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/images/asf_logo_url.png?rev=1845788&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/unomi/website/manual/1_3_x/asciidoc/images/asf_logo_url.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/unomi/website/manual/1_3_x/asciidoc/images/incubator-logo.png
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/images/incubator-logo.png?rev=1845788&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/unomi/website/manual/1_3_x/asciidoc/images/incubator-logo.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/unomi/website/manual/1_3_x/asciidoc/images/unomi-request.png
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/images/unomi-request.png?rev=1845788&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/unomi/website/manual/1_3_x/asciidoc/images/unomi-request.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/unomi/website/manual/1_3_x/asciidoc/index.html
URL: http://svn.apache.org/viewvc/incubator/unomi/website/manual/1_3_x/asciidoc/index.html?rev=1845788&view=auto
==============================================================================
--- incubator/unomi/website/manual/1_3_x/asciidoc/index.html (added)
+++ incubator/unomi/website/manual/1_3_x/asciidoc/index.html Mon Nov 5 13:51:53 2018
@@ -0,0 +1,131 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="generator" content="Asciidoctor 1.5.6.1">
+<meta name="author" content="Apache Software Foundation">
+<title>Apache Unomi 1.x - Documentation</title>
+<link rel="stylesheet" href="./apache.css">
+</head>
+<body class="article toc2 toc-left">
+<div id="header">
+<h1>Apache Unomi 1.x - Documentation</h1>
+<div class="details">
+<span id="author" class="author">Apache Software Foundation</span><br>
+</div>
+<div id="toc" class="toc2">
+<div id="toctitle">Table of Contents</div>
+<ul class="sectlevel1">
+<li><a href="#_concepts">1. Concepts</a></li>
+<li><a href="#_extending_unomi_via_plugins">2. Extending Unomi via plugins</a></li>
+<li><a href="#_quick_start">3. Quick start</a></li>
+<li><a href="#_sample">4. Sample</a></li>
+<li><a href="#_connectors">5. Connectors</a></li>
+<li><a href="#_cluster_setup">6. Cluster setup</a></li>
+<li><a href="#_custom_extensions">7. Custom extensions</a></li>
+<li><a href="#_consent_api">8. Consent API</a></li>
+</ul>
+</div>
+</div>
+<div id="content">
+<div id="preamble">
+<div class="sectionbody">
+<div class="imageblock" style="text-align: center">
+<div class="content">
+<img src="images/incubator-logo.png" alt="incubator logo">
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_concepts">1. Concepts</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::concepts.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_extending_unomi_via_plugins">2. Extending Unomi via plugins</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::extending-plugins.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_quick_start">3. Quick start</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::building-and-deploying.adoc[]</p>
+</div>
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::getting-started.adoc[]</p>
+</div>
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::configuration.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_sample">4. Sample</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::samples/samples.adoc[]</p>
+</div>
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::samples/login-sample.adoc[]</p>
+</div>
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::samples/twitter-sample.adoc[]</p>
+</div>
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::samples/weather-update-sample.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_connectors">5. Connectors</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::connectors/connectors.adoc[]</p>
+</div>
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::connectors/salesforce-connector.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_cluster_setup">6. Cluster setup</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::clustering.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_custom_extensions">7. Custom extensions</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::custom-extensions.adoc[]</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_consent_api">8. Consent API</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Unresolved directive in index.adoc - include::consent-api.adoc[]</p>
+</div>
+</div>
+</div>
+</div>
+<div id="footer">
+<div id="footer-text">
+Last updated 2018-09-20 20:40:36 CEST
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file