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 2020/05/15 08:38:33 UTC
svn commit: r1877780 [3/3] - in /unomi/website/manual: 1_1_x/ 1_2_x/ 1_3_x/
1_4_x/ 1_5_x/ 1_5_x/connectors/ 1_5_x/images/ 1_5_x/samples/ latest/
Modified: unomi/website/manual/latest/index.html
URL: http://svn.apache.org/viewvc/unomi/website/manual/latest/index.html?rev=1877780&r1=1877779&r2=1877780&view=diff
==============================================================================
--- unomi/website/manual/latest/index.html (original)
+++ unomi/website/manual/latest/index.html Fri May 15 08:38:33 2020
@@ -70,12 +70,13 @@
<li><a href="#_installing_the_maxmind_geoiplite2_ip_lookup_database">2.5.5. Installing the MaxMind GeoIPLite2 IP lookup database</a></li>
<li><a href="#_installing_geonames_database">2.5.6. Installing Geonames database</a></li>
<li><a href="#_rest_api_security">2.5.7. REST API Security</a></li>
-<li><a href="#_automatic_profile_merging">2.5.8. Automatic profile merging</a></li>
-<li><a href="#_securing_a_production_environment">2.5.9. Securing a production environment</a></li>
-<li><a href="#_integrating_with_an_apache_http_web_server">2.5.10. Integrating with an Apache HTTP web server</a></li>
-<li><a href="#_changing_the_default_tracking_location">2.5.11. Changing the default tracking location</a></li>
-<li><a href="#_apache_karaf_ssh_console">2.5.12. Apache Karaf SSH Console</a></li>
-<li><a href="#_elasticsearch_authentication_and_security">2.5.13. ElasticSearch authentication and security</a></li>
+<li><a href="#_scripting_security">2.5.8. Scripting security</a></li>
+<li><a href="#_automatic_profile_merging">2.5.9. Automatic profile merging</a></li>
+<li><a href="#_securing_a_production_environment">2.5.10. Securing a production environment</a></li>
+<li><a href="#_integrating_with_an_apache_http_web_server">2.5.11. Integrating with an Apache HTTP web server</a></li>
+<li><a href="#_changing_the_default_tracking_location">2.5.12. Changing the default tracking location</a></li>
+<li><a href="#_apache_karaf_ssh_console">2.5.13. Apache Karaf SSH Console</a></li>
+<li><a href="#_elasticsearch_authentication_and_security">2.5.14. ElasticSearch authentication and security</a></li>
</ul>
</li>
<li><a href="#_useful_apache_unomi_urls">2.6. Useful Apache Unomi URLs</a></li>
@@ -270,6 +271,12 @@
<li><a href="#_existing_action_types_descriptors">8.22.1. Existing action types descriptors</a></li>
</ul>
</li>
+<li><a href="#_updating_events_using_the_context_servlet">8.23. Updating Events Using the Context Servlet</a>
+<ul class="sectlevel3">
+<li><a href="#_solution">8.23.1. Solution</a></li>
+<li><a href="#_defining_rules">8.23.2. Defining Rules</a></li>
+</ul>
+</li>
</ul>
</li>
<li><a href="#_integration_samples">9. Integration samples</a>
@@ -1151,8 +1158,57 @@ Then you can use the test page to try yo
<div class="sect3">
<h4 id="_tracking_page_views">2.4.3. Tracking page views</h4>
<div class="paragraph">
+<p>In the initialize call, the tracker will generate an implicit page view event, which by default will be populated with
+the following information:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-javascript" data-lang="javascript"> window.digitalData.page = window.digitalData.page || {
+ path: location.pathname + location.hash,
+ pageInfo: {
+ pageName: document.title,
+ pageID : location.pathname + location.hash,
+ pagePath : location.pathname + location.hash,
+ destinationURL: location.href
+ }
+ }</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Now if you want to provide your own custom page information for the initial page view, you can simply do it like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-`javascript" data-lang="`javascript"> unomiTracker.initialize({
+ scope: 'myScope',
+ url: 'http://unomi:8181', // we use an empty URL to make it relative to this page.
+ initialPageProperties: {
+ path: path,
+ pageInfo: {
+ destinationURL: location.href,
+ tags: ["tag1", "tag2", "tag3"],
+ categories: ["category1", "category2", "category3"]
+ },
+ interests: {
+ "interest1": 1,
+ "interest2": 2,
+ "interest3": 3
+ }
+ }
+ });</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>`</p>
+</div>
+<div class="paragraph">
+<p>Also note that the FIRST call to unomiTracker.page() will be IGNORED because of this initial page view.This is the
+way that the Analytics.js library handles it.So make sure you are aware of this when calling it.This is to avoid having
+two page views on a single call and to be compatible with old versions that did use the explicit call.</p>
+</div>
+<div class="paragraph">
<p>By default the script will track page views, but maybe you want to take control over this mechanism of add page views
-to a single page application. In order to generate a page view programmatically from Javascript you can use code similar
+to a single page application.In order to generate a page view programmatically from Javascript you can use code similar
to this :</p>
</div>
<div class="listingblock">
@@ -1229,8 +1285,8 @@ object passed to the unomiTracker call.
</tbody>
</table>
<div class="paragraph">
-<p>The <code>interests</code> object is basically list of interests with "weights" attached to them. These interests will be accumulated
-in Apache Unomi on profiles to indicate growing interest over time for specific topics. These are freely defined and
+<p>The <code>interests</code> object is basically list of interests with "weights" attached to them.These interests will be accumulated
+in Apache Unomi on profiles to indicate growing interest over time for specific topics.These are freely defined and
will be accepted by Apache Unomi without needing to declare them previously anywhere (the same is true for tags and
categories).</p>
</div>
@@ -1755,7 +1811,29 @@ org.ops4j.pax.web.ssl.keypassword=${env:
</div>
</div>
<div class="sect3">
-<h4 id="_automatic_profile_merging">2.5.8. Automatic profile merging</h4>
+<h4 id="_scripting_security">2.5.8. Scripting security</h4>
+<div class="paragraph">
+<p>By default, scripting (using in conditions, segments and rules) is controlled by a custom classloader that is quite
+restrictive and using a white-list/black list system. It is controlled through the following property in the
+<code>unomi.custom.system.properties</code> file:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>org.apache.unomi.scripting.allow=${env:UNOMI_ALLOW_SCRIPTING_CLASSES:-org.apache.unomi.api.Event,org.apache.unomi.api.Profile,org.apache.unomi.api.Session,org.apache.unomi.api.Item,org.apache.unomi.api.CustomItem,ognl.*,java.lang.Object,java.util.Map,java.lang.Integer,org.mvel2.*}
+org.apache.unomi.scripting.forbid=${env:UNOMI_FORBID_SCRIPTING_CLASSES:-}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you encounter any errors while trying to access a class in a condition or an action it might be due to this
+restrictive configuration.</p>
+</div>
+<div class="paragraph">
+<p>If you need, for example when adding a custom item type, to adjust these, please be careful as scripts may be called
+directly from the context.json personalization conditions and therefore should be kept minimal.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_automatic_profile_merging">2.5.9. Automatic profile merging</h4>
<div class="paragraph">
<p>Apache Unomi 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
@@ -1774,7 +1852,7 @@ Upon sending one of the events, all matc
</div>
</div>
<div class="sect3">
-<h4 id="_securing_a_production_environment">2.5.9. Securing a production environment</h4>
+<h4 id="_securing_a_production_environment">2.5.10. 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>
@@ -1884,7 +1962,7 @@ a proxy, and use it to filter any commun
</div>
</div>
<div class="sect3">
-<h4 id="_integrating_with_an_apache_http_web_server">2.5.10. Integrating with an Apache HTTP web server</h4>
+<h4 id="_integrating_with_an_apache_http_web_server">2.5.11. 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>
@@ -1982,7 +2060,7 @@ ProxyPassReverse / http://localhost:8181
</div>
</div>
<div class="sect3">
-<h4 id="_changing_the_default_tracking_location">2.5.11. Changing the default tracking location</h4>
+<h4 id="_changing_the_default_tracking_location">2.5.12. 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 modify the default location settings using the
@@ -2010,7 +2088,7 @@ org.apache.unomi.ip.default.longitude=${
</div>
</div>
<div class="sect3">
-<h4 id="_apache_karaf_ssh_console">2.5.12. Apache Karaf SSH Console</h4>
+<h4 id="_apache_karaf_ssh_console">2.5.13. 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>
@@ -2026,7 +2104,7 @@ shell commands in the "Shell commands" s
</div>
</div>
<div class="sect3">
-<h4 id="_elasticsearch_authentication_and_security">2.5.13. ElasticSearch authentication and security</h4>
+<h4 id="_elasticsearch_authentication_and_security">2.5.14. ElasticSearch authentication and security</h4>
<div class="paragraph">
<p>With ElasticSearch 7, it’s possible to secure the access to your data. (<a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.5/secure-cluster.html">https://www.elastic.co/guide/en/elasticsearch/reference/7.5/secure-cluster.html</a>)</p>
</div>
@@ -3806,7 +3884,7 @@ It has also been engaged in some goals (
},
"systemProperties": {
"mergeIdentifier": "bill",
- " *lists* ": [
+ "lists": [
"userListId"
],
"goals": {
@@ -4444,6 +4522,11 @@ You can imagine conditions checking inco
<td class="tableblock halign-left valign-top"><p class="tableblock">A list of references to objects that may have generated this rule. Goals and segments dynamically generate rules to react to incoming events. It is not recommend to manipulate rules that have linkedItems as it may break functionality.</p></td>
</tr>
<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">raiseEventOnlyOnce</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">If true, the rule will only be executed once for a given event.</p></td>
+</tr>
+<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">raiseEventOnlyOnceForProfile</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Boolean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If true, the rule will only be executed once for a given profile and a matching event. Warning: this functionality has a performance impact since it looks up past events.</p></td>
@@ -5441,9 +5524,9 @@ In this case it was a search form that c
"profileId": "bc1e1238-a9ac-4b3a-8f63-5eec205cfcd5",
"timeStamp": "2020-01-31T08:51:15Z",
"properties": {
- " *targetId* ": "f7d1f1b9-4415-4ff1-8fee-407b109364f7",
- " *targetType* ": "profile",
- " *add* ": {
+ "targetId": "f7d1f1b9-4415-4ff1-8fee-407b109364f7",
+ "targetType": "profile",
+ "add": {
"properties.phoneNumber": "+1-123-555-12345",
"properties.countryName": "US",
"properties.city": "Las Vegas",
@@ -6126,6 +6209,92 @@ discover more. But the list below should
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_updating_events_using_the_context_servlet">8.23. Updating Events Using the Context Servlet</h3>
+<div class="paragraph">
+<p>One of the use cases that needed to be supported by Unomi is the ability to build a user profile based on Internal System events or <a href="https://en.wikipedia.org/wiki/Change_data_capture">Change Data Capture</a> which usally transported through internal messaging queues such as Kafka.</p>
+</div>
+<div class="paragraph">
+<p>This can easily achieved using the <code>KafkaInjector</code> module built in within Unomi.</p>
+</div>
+<div class="paragraph">
+<p>But, as streaming system usually operates in <a href="https://dzone.com/articles/kafka-clients-at-most-once-at-least-once-exactly-o">at-least-once</a> semantics,
+we need to have a way to guarantee we wont have duplicate events in the system.</p>
+</div>
+<div class="sect3">
+<h4 id="_solution">8.23.1. Solution</h4>
+<div class="paragraph">
+<p>One of the solutions to this scenario is to have the ability to control and pass in the <code>eventId</code> property from outside of Unomi,
+Using an authorized 3rd party. This way whenever an event with the same <code>itemId</code> will be processed once again he wont be appended to list of events, but will be updated.</p>
+</div>
+<div class="paragraph">
+<p>Here is an example of a request contains the <code>itemdId</code></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -X POST http://localhost:8181/context.json \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
+{
+ "events":[
+ {
+ "itemId": "exampleEventId",
+ "eventType":"view",
+ "scope": "example",
+ "properties" : {
+ "firstName" : "example"
+ }
+ }
+ ]
+}
+EOF</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Make sure to use an authorized third party using <code>X-Unomi-Peer</code> requests headers and that the <code>eventType</code> is in the list of allowed events</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_defining_rules">8.23.2. Defining Rules</h4>
+<div class="paragraph">
+<p>Another use case we support is the ability to define a rule on the above mentioned events.
+If we have a rule that increment a property on profile level, we would want the action to be executed only once per event id.
+this can be achieved by adding <code>"raiseEventOnlyOnce": false</code> to the rule definition.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code>curl -X POST http://localhost:8181/context.json \
+-H "Content-Type: application/json" \
+-d @- <<'EOF'
+{
+ "metadata": {
+ "id": "updateNumberOfOrders",
+ "name": "update number of orders on orderCreated eventType",
+ "description": "update number of orders on orderCreated eventType"
+ },
+ "raiseEventOnlyOnce": false,
+ "condition": {
+ "type": "eventTypeCondition",
+ "parameterValues": {
+ "eventTypeId": "orderCreated"
+ }
+ },
+ "actions": [
+ {
+ "parameterValues": {
+ "setPropertyName": "properties.nbOfOrders",
+ "setPropertyValue": "script::profile.properties.?nbOfOrders != null ? (profile.properties.nbOfOrders + 1) : 1",
+ "storeInSession": false
+ },
+ "type": "setPropertyAction"
+ }
+ ]
+}
+EOF</code></pre>
+</div>
+</div>
+</div>
+</div>
</div>
</div>
<div class="sect1">
@@ -6247,7 +6416,7 @@ mvn clean install</code></pre>
</div>
<div class="listingblock">
<div class="content">
-<pre class="highlight"><code>cp target/tweet-button-plugin-1.5.0-SNAPSHOT.jar ../../package/target/unomi-1.5.0-SNAPSHOT/deploy</code></pre>
+<pre class="highlight"><code>cp target/tweet-button-plugin-2.0.0-SNAPSHOT.jar ../../package/target/unomi-2.0.0-SNAPSHOT/deploy</code></pre>
</div>
</div>
</div>
@@ -7648,9 +7817,9 @@ created, EXECUTE means the rule’s
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">event-list</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">[max-entries] [--csv]</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">[max-entries] [event-type] [--csv]</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">List the last events processed by Apache Unomi. The <code>max-entries</code> parameter can be used to control how many events are
-displayed (default is 100). The <code>--csv</code> argument is used to output the list as a CSV list instead of an ASCII table.</p></td>
+displayed (default is 100). The <code>event-type</code> makes it possible to filter the list by event type. The <code>--csv</code> argument is used to output the list as a CSV list instead of an ASCII table.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">event-search</p></td>
@@ -8529,7 +8698,7 @@ They allow to modify an item, that would
</div>
<div id="footer">
<div id="footer-text">
-Last updated 2020-02-17 15:25:35 +0100
+Last updated 2020-05-14 19:49:53 UTC
</div>
</div>
</body>