Repository: incubator-unomi Updated Branches: refs/heads/master b11a1e4fa -> f2117f691
Documentation changes : - New custom extensions page - Minor improvements - Added a new main documentation page and removed the sub-menus that were causing issues. Signed-off-by: Serge Huber <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/incubator-unomi/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-unomi/commit/f2117f69 Tree: http://git-wip-us.apache.org/repos/asf/incubator-unomi/tree/f2117f69 Diff: http://git-wip-us.apache.org/repos/asf/incubator-unomi/diff/f2117f69 Branch: refs/heads/master Commit: f2117f691da1f4c00caf7a2fd2272eb75bbf366c Parents: b11a1e4 Author: Serge Huber <[email protected]> Authored: Fri Jul 21 16:57:00 2017 +0200 Committer: Serge Huber <[email protected]> Committed: Fri Jul 21 16:57:07 2017 +0200 ---------------------------------------------------------------------- src/site/markdown/main.md | 39 +++ .../versions/master/custom-extensions.md | 336 +++++++++++++++++++ .../markdown/versions/master/getting-started.md | 10 +- .../markdown/versions/master/twitter-sample.md | 10 +- src/site/site.xml | 24 +- 5 files changed, 393 insertions(+), 26 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f2117f69/src/site/markdown/main.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/main.md b/src/site/markdown/main.md new file mode 100644 index 0000000..18b8cd4 --- /dev/null +++ b/src/site/markdown/main.md @@ -0,0 +1,39 @@ +<!-- + ~ 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. + --> + +# General documentation + +In this section we regroup the documentation by Apache Unomi version. + +## Version 1.1 (current) + +- [Building and deploying](versions/1.1/building-and-deploying.html) +- [Getting started](versions/1.1/getting-started.html) +- [Configuration](versions/1.1/configuration.html) +- [Cluster setup](versions/1.1/clustering.html) +- [Concepts](versions/1.1/concepts.html) + +## Master (snapshot, in development) + +- [Building and deploying](versions/master/building-and-deploying.html) +- [Getting started](versions/master/getting-started.html) +- [Configuration](versions/master/configuration.html) +- [Samples](versions/master/samples.html) +- [Connectors](versions/master/connectors.html) +- [Cluster setup](versions/master/clustering.html) +- [Concepts](versions/master/concepts.html) +- [Custom extensions](versions/master/custom-extensions.html) http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f2117f69/src/site/markdown/versions/master/custom-extensions.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/versions/master/custom-extensions.md b/src/site/markdown/versions/master/custom-extensions.md new file mode 100644 index 0000000..82acbf7 --- /dev/null +++ b/src/site/markdown/versions/master/custom-extensions.md @@ -0,0 +1,336 @@ +<!-- + ~ 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. + --> + +# Custom extensions + +Apache Unomi is a pluggeable server that may be extended in many ways. This document assumes you are familiar with the +[Apache Unomi concepts](concepts.html) . 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 [samples page](samples.html). + +## Creating an extension + +An extension is simply a Maven project, with a Maven pom that looks like this: + + <project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <parent> + <groupId>org.apache.unomi</groupId> + <artifactId>unomi-extensions</artifactId> + <version>1.2.0-incubating-SNAPSHOT</version> + </parent> + + <modelVersion>4.0.0</modelVersion> + + <artifactId>unomi-extension-example</artifactId> + <name>Apache Unomi :: Extensions :: Example</name> + <description>Service implementation for the Apache Unomi Context Server extension that integrates with the Geonames database</description> + <version>1.2.0-incubating-SNAPSHOT</version> + <packaging>bundle</packaging> + + <dependencies> + <!-- This dependency is not required but generally used in extensions --> + <dependency> + <groupId>org.apache.unomi</groupId> + <artifactId>unomi-api</artifactId> + <version>1.2.0-incubating-SNAPSHOT</version> + <scope>provided</scope> + </dependency> + </dependencies> + + <build> + <plugins> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <extensions>true</extensions> + <configuration> + <instructions> + <Embed-Dependency>*;scope=compile|runtime</Embed-Dependency> + <Import-Package> + sun.misc;resolution:=optional, + * + </Import-Package> + </instructions> + </configuration> + </plugin> + </plugins> + </build> + </project> + +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. + +## Predefined rules + +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: + + { + "metadata" : { + "id": "evaluateProfileSegments", + "name": "Evaluate segments", + "description" : "Evaluate segments when a profile is modified", + "readOnly":true + }, + + "condition" : { + "type": "profileUpdatedEventCondition", + "parameterValues": { + } + }, + + "actions" : [ + { + "type": "evaluateProfileSegmentsAction", + "parameterValues": { + } + } + ] + + } + +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. + +## Predefined properties + +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. + +For session properties you must create a JSON file in the following directory in your Maven project: + + src/main/resources/META-INF/cxs/properties/sessions + +For profile properties you must create the JSON file inside the directory in your Maven project: + + src/main/resources/META-INF/cxs/properties/profiles + +Here is an example of a property definition JSON file + + { + "metadata": { "id": "city", "name": "City" }, + "type": "string", + "tags": ["contactProfileProperties"], + "defaultValue": "", + "automaticMappingsFrom": [ ], + "rank": "304.0" + } + +## Predefined child conditions + +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: + + src/main/resources/META-INF/cxs/conditions + +Here is an example of a JSON file that defines a profileUpdateEventCondition that inherits from a parent condition of +type eventTypeCondition. + + { + "metadata": { + "id": "profileUpdatedEventCondition", + "name": "profileUpdatedEventCondition", + "description": "", + "tags": [ + "event", + "eventCondition" + ], + "readOnly": true + }, + "parentCondition": { + "type": "eventTypeCondition", + "parameterValues": { + "eventTypeId": "profileUpdated" + } + }, + + "parameters": [ + ] + } + +## Predefined personas + +Personas may also be pre-defined by creating JSON files in the following directory: + + src/main/resources/META-INF/cxs/personas + +Here is an example of a persona definition JSON file: + + { + "persona": { + "itemId": "usVisitor", + "properties": { + "description": "Represents a visitor browsing from inside the continental US", + "firstName": "U.S.", + "lastName": "Visitor" + }, + "segments": [] + }, + "sessions": [ + { + "itemId": "aa3b04bd-8f4d-4a07-8e96-d33ffa04d3d9", + "profileId": "usVisitor", + "properties": { + "operatingSystemName": "OS X 10.9 Mavericks", + "sessionCountryName": "United States", + "location": { + "lat":37.422, + "lon":-122.084058 + }, + "userAgentVersion": "37.0.2062.120", + "sessionCountryCode": "US", + "deviceCategory": "Personal computer", + "operatingSystemFamily": "OS X", + "userAgentName": "Chrome", + "sessionCity": "Mountain View", + "remoteHost": "www.google.com", + "remoteAddr": "66.249.66.1" + }, + "timeStamp": "2014-09-18T11:40:54Z", + "lastEventDate": "2014-09-18T11:40:59Z", + "duration": 4790 + } + ] + } + +You can see that it's also possible to define sessions for personas. + +## Custom actions + +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: + + src/main/resources/META-INF/cxs/actions + +Here is an example of a JSON action definition: + + { + "metadata": { + "id": "addToListsAction", + "name": "addToListsAction", + "description": "", + "tags": [ + "demographic", + "hidden.availableToEndUser" + ], + "readOnly": true + }, + "actionExecutor": "addToLists", + "parameters": [ + { + "id": "listIdentifiers", + "type": "string", + "multivalued": true + } + ] + } + +The `actionExecutor` 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 `src/main/resources/OSGI-INF/blueprint/blueprint.xml` with the following +content: + + <?xml version="1.0" encoding="UTF-8"?> + <blueprint xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"; + xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd";> + + <reference id="profileService" interface="org.apache.unomi.api.services.ProfileService"/> + <reference id="eventService" interface="org.apache.unomi.api.services.EventService"/> + + <!-- Action executors --> + + <service auto-export="interfaces"> + <service-properties> + <entry key="actionExecutorId" value="addToLists"/> + </service-properties> + <bean class="org.apache.unomi.lists.actions.AddToListsAction"> + <property name="profileService" ref="profileService"/> + <property name="eventService" ref="eventService"/> + </bean> + </service> + + </blueprint> + +You can note here the `actionExecutorId` that corresponds to the `actionExecutor` in the JSON file. + +The implementation of the action is available here : [org.apache.unomi.lists.actions.AddToListsAction](https://github.com/apache/incubator-unomi/blob/master/extensions/lists-extension/actions/src/main/java/org/apache/unomi/lists/actions/AddToListsAction.java) + +## Custom conditions + +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: + + src/main/resources/META-INF/cxs/conditions + +Here is an example of JSON custom condition definition: + + { + "metadata": { + "id": "matchAllCondition", + "name": "matchAllCondition", + "description": "", + "tags": [ + "logical", + "profileCondition", + "eventCondition", + "sessionCondition", + "sourceEventCondition" + ], + "readOnly": true + }, + "conditionEvaluator": "matchAllConditionEvaluator", + "queryBuilder": "matchAllConditionESQueryBuilder", + + "parameters": [ + ] + } + +Note the `conditionEvaluator` and the `queryBuilder` 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. + + 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> + +You can find the implementation of the two classes here : + +- [org.apache.unomi.plugins.baseplugin.conditions.MatchAllConditionESQueryBuilder](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.MatchAllConditionEvaluator](https://github.com/apache/incubator-unomi/blob/master/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/MatchAllConditionEvaluator.java) + http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f2117f69/src/site/markdown/versions/master/getting-started.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/versions/master/getting-started.md b/src/site/markdown/versions/master/getting-started.md index a3c9893..6c4380d 100644 --- a/src/site/markdown/versions/master/getting-started.md +++ b/src/site/markdown/versions/master/getting-started.md @@ -53,7 +53,7 @@ available RESTful services or retrieve an initial context at `http://localhost:8 You can retrieve a context using curl like this : - curl http://localhost:8181/context.js?sessionId=1234 + curl http://localhost:8181/context.js?sessionId=1234 This will retrieve a JavaScript script that contains a `cxs` 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 @@ -63,7 +63,7 @@ events using the cxs.collectEvents() function). If you prefer to retrieve a pure JSON object, you can simply use a request formed like this: - curl http://localhost:8181/context.json?sessionId=1234 + curl http://localhost:8181/context.json?sessionId=1234 #### Accessing profile properties in a context @@ -73,7 +73,7 @@ of the context.js(on) servlet. Here is an example that will retrieve all the session and profile properties. - 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 + 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 The `requiredProfileProperties` and `requiredSessionProperties` 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 @@ -85,7 +85,7 @@ Java class. 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: - 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 + 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 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 @@ -97,7 +97,7 @@ to send events in a network optimal way you can use the eventcollector servlet ( 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: - 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 + 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 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. http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f2117f69/src/site/markdown/versions/master/twitter-sample.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/versions/master/twitter-sample.md b/src/site/markdown/versions/master/twitter-sample.md index cf470be..f4829df 100644 --- a/src/site/markdown/versions/master/twitter-sample.md +++ b/src/site/markdown/versions/master/twitter-sample.md @@ -18,6 +18,14 @@ Twitter sample ============== +## Overview +We will examine how a simple HTML page can interact with Unomi to enrich a user's profile. The use case we will follow +is a rather simple one: we use a Twitter button to record the number of times the visitor tweeted (as a `tweetNb` profile +integer property) as well as the URLs they tweeted from (as a `tweetedFrom` multi-valued string profile property). +A javascript script will use the Twitter API to react to clicks on this button +and update the user profile using a `ContextServlet` request triggering a custom event. This event will, in turn, +trigger a Unomi action on the server implemented using a Unomi plugin, a standard extension point for the server. + ### Building the tweet button sample In your local copy of the Unomi repository and run: @@ -93,8 +101,6 @@ We will look at the details of the context request and response later. # Example -## Overview -We will examine how a simple HTML page can interact with Unomi to enrich a user's profile. The use case we will follow is a rather simple one: we want to react to Twitter events by associating information to their profile. We will record the number of times the user tweeted (as a `tweetNb` profile integer property) as well as the URLs they tweeted from (as a `tweetedFrom` multi-valued string profile property). We will accomplish this using a simple HTML page on which we position a standard "Tweet" button. A javascript script will use the Twitter API to react to clicks on this button and update the user profile using a `ContextServlet` request triggering a custom event. This event will, in turn, trigger a Unomi action on the server implemented using a Unomi plugin, a standard extension point for the server. ## HTML page The code for the HTML page with our Tweet button can be found at https://github.com/apache/incubator-unomi/blob/master/wab/src/main/webapp/index.html. http://git-wip-us.apache.org/repos/asf/incubator-unomi/blob/f2117f69/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index 38e0ae7..1a93a2d 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -55,8 +55,9 @@ <!--tocTopMax>6</tocTopMax--> <topNav>Download|Documentation|Standard|Contribute|Privacy|Community</topNav> <bottomNav> - <column>Download|Documentation|Standard|Contribute|Privacy|Community</column> - <column>modules</column> + <column>Download|Contribute</column> + <column>Documentation</column> + <column>Community|Standard|Privacy</column> <column>reports</column> </bottomNav> <bottomDescription> @@ -107,23 +108,8 @@ </menu> <menu name="Documentation" inherit="top"> - <item name="Home" href="./" /> - <item name="Version 1.1 (current)"> - <item name="Building and deploying" href="versions/1.1/building-and-deploying.html" /> - <item name="Getting started" href="versions/1.1/getting-started.html"/> - <item name="Configuration" href="versions/1.1/configuration.html" /> - <item name="Cluster setup" href="versions/1.1/clustering.html" /> - <item name="Concepts" href="versions/master/1.1.html"/> - </item> - <item name="Master (snapshot)"> - <item name="Building and deploying" href="versions/master/building-and-deploying.html" /> - <item name="Getting started" href="versions/master/getting-started.html"/> - <item name="Configuration" href="versions/master/configuration.html" /> - <item name="Samples" href="/versions/master/samples.html" /> - <item name="Connectors" href="versions/master/connectors.html" /> - <item name="Cluster setup" href="versions/master/clustering.html" /> - <item name="Concepts" href="versions/master/concepts.html"/> - </item> + <item name="Site Home" href="./" /> + <item name="Main documentation" href="main.html" /> <item name="More use cases" href="usecases.html" /> <item name="REST API documentation" href="./rest-api-doc/index.html"/> <item name="API Javadoc" href="./unomi-api/apidocs/index.html"/>
