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/02/17 14:52:57 UTC
svn commit: r1874137 [4/4] - in /unomi/website/manual: 1_1_x/ 1_2_x/ 1_3_x/
1_4_x/ 1_4_x/connectors/ 1_4_x/images/ 1_4_x/samples/ latest/ latest/images/
Modified: unomi/website/manual/latest/index.html
URL: http://svn.apache.org/viewvc/unomi/website/manual/latest/index.html?rev=1874137&r1=1874136&r2=1874137&view=diff
==============================================================================
--- unomi/website/manual/latest/index.html (original)
+++ unomi/website/manual/latest/index.html Mon Feb 17 14:52:56 2020
@@ -4,7 +4,7 @@
<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.7.1">
+<meta name="generator" content="Asciidoctor 1.5.8">
<meta name="author" content="Apache Software Foundation">
<title>Apache Unomi 1.x - Documentation</title>
<link rel="stylesheet" href="./apache.css">
@@ -23,261 +23,359 @@
<li><a href="#_five_minutes_quickstart">1.1. Five Minutes QuickStart</a></li>
</ul>
</li>
-<li><a href="#_concepts">2. Concepts</a>
+<li><a href="#_first_steps_with_apache_unomi">2. First steps with Apache Unomi</a>
<ul class="sectlevel2">
-<li><a href="#_items_and_types">2.1. Items and types</a></li>
-<li><a href="#_events">2.2. Events</a></li>
-<li><a href="#_profiles">2.3. Profiles</a></li>
-<li><a href="#_sessions">2.4. Sessions</a></li>
-<li><a href="#_segments">2.5. Segments</a></li>
-<li><a href="#_conditions">2.6. Conditions</a></li>
-<li><a href="#_rules">2.7. Rules</a>
+<li><a href="#_getting_started_with_unomi">2.1. Getting started with Unomi</a>
<ul class="sectlevel3">
-<li><a href="#_actions">2.7.1. Actions</a></li>
+<li><a href="#_prerequisites">2.1.1. Prerequisites</a></li>
+<li><a href="#_running_unomi">2.1.2. Running Unomi</a></li>
</ul>
</li>
-<li><a href="#_request_flow">2.8. Request flow</a></li>
+<li><a href="#_recipes">2.2. Recipes</a>
+<ul class="sectlevel3">
+<li><a href="#_introduction">2.2.1. Introduction</a></li>
+<li><a href="#_how_to_read_a_profile">2.2.2. How to read a profile</a></li>
+<li><a href="#_how_to_update_a_profile_from_the_public_internet">2.2.3. How to update a profile from the public internet</a></li>
+<li><a href="#_how_to_search_for_profile_events">2.2.4. How to search for profile events</a></li>
+<li><a href="#_how_to_create_a_new_rule">2.2.5. How to create a new rule</a></li>
+<li><a href="#_how_to_search_for_profiles">2.2.6. How to search for profiles</a></li>
+<li><a href="#_getting_updating_consents">2.2.7. Getting / updating consents</a></li>
+<li><a href="#_how_to_send_a_login_event_to_unomi">2.2.8. How to send a login event to Unomi</a></li>
</ul>
</li>
-<li><a href="#_first_steps_with_apache_unomi">3. First steps with Apache Unomi</a>
-<ul class="sectlevel2">
-<li><a href="#_getting_started_with_unomi">3.1. Getting started with Unomi</a>
+<li><a href="#_request_examples">2.3. Request examples</a>
<ul class="sectlevel3">
-<li><a href="#_prerequisites">3.1.1. Prerequisites</a></li>
-<li><a href="#_running_unomi">3.1.2. Running Unomi</a></li>
+<li><a href="#_retrieving_your_first_context">2.3.1. Retrieving your first context</a></li>
+<li><a href="#_retrieving_a_context_as_a_json_object">2.3.2. Retrieving a context as a JSON object.</a></li>
+<li><a href="#_accessing_profile_properties_in_a_context">2.3.3. Accessing profile properties in a context</a></li>
+<li><a href="#_sending_events_using_the_context_servlet">2.3.4. Sending events using the context servlet</a></li>
+<li><a href="#_sending_events_using_the_eventcollector_servlet">2.3.5. Sending events using the eventcollector servlet</a></li>
+<li><a href="#_where_to_go_from_here">2.3.6. Where to go from here</a></li>
</ul>
</li>
-<li><a href="#_recipes">3.2. Recipes</a>
+<li><a href="#_web_tracker">2.4. Web Tracker</a>
<ul class="sectlevel3">
-<li><a href="#_introduction">3.2.1. Introduction</a></li>
-<li><a href="#_how_to_read_a_profile">3.2.2. How to read a profile</a></li>
-<li><a href="#_how_to_update_a_profile_from_the_public_internet">3.2.3. How to update a profile from the public internet</a></li>
-<li><a href="#_how_to_search_for_profile_events">3.2.4. How to search for profile events</a></li>
-<li><a href="#_how_to_create_a_new_rule">3.2.5. How to create a new rule</a></li>
-<li><a href="#_how_to_search_for_profiles">3.2.6. How to search for profiles</a></li>
-<li><a href="#_getting_updating_consents">3.2.7. Getting / updating consents</a></li>
-<li><a href="#_how_to_send_a_login_event_to_unomi">3.2.8. How to send a login event to Unomi</a></li>
+<li><a href="#_getting_started">2.4.1. Getting started</a></li>
+<li><a href="#_how_to_contribute">2.4.2. How to contribute</a></li>
+<li><a href="#_tracking_page_views">2.4.3. Tracking page views</a></li>
+<li><a href="#_tracking_form_submissions">2.4.4. Tracking form submissions</a></li>
</ul>
</li>
-<li><a href="#_request_examples">3.3. Request examples</a>
+<li><a href="#_configuration">2.5. Configuration</a>
<ul class="sectlevel3">
-<li><a href="#_retrieving_your_first_context">3.3.1. Retrieving your first context</a></li>
-<li><a href="#_retrieving_a_context_as_a_json_object">3.3.2. Retrieving a context as a JSON object.</a></li>
-<li><a href="#_accessing_profile_properties_in_a_context">3.3.3. Accessing profile properties in a context</a></li>
-<li><a href="#_sending_events_using_the_context_servlet">3.3.4. Sending events using the context servlet</a></li>
-<li><a href="#_sending_events_using_the_eventcollector_servlet">3.3.5. Sending events using the eventcollector servlet</a></li>
-<li><a href="#_where_to_go_from_here">3.3.6. Where to go from here</a></li>
+<li><a href="#_centralized_configuration">2.5.1. Centralized configuration</a></li>
+<li><a href="#_changing_the_default_configuration_using_environment_variables_i_e_docker_configuration">2.5.2. Changing the default configuration using environment variables (i.e. Docker configuration)</a></li>
+<li><a href="#_changing_the_default_configuration_using_property_files">2.5.3. Changing the default configuration using property files</a></li>
+<li><a href="#_secured_events_configuration">2.5.4. Secured events configuration</a></li>
+<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>
+</ul>
+</li>
+<li><a href="#_useful_apache_unomi_urls">2.6. Useful Apache Unomi URLs</a></li>
+<li><a href="#_how_profile_tracking_works">2.7. How profile tracking works</a>
+<ul class="sectlevel3">
+<li><a href="#_steps">2.7.1. Steps</a></li>
+</ul>
+</li>
+<li><a href="#_context_request_flow">2.8. Context Request Flow</a></li>
</ul>
</li>
-<li><a href="#_web_tracker">3.4. Web Tracker</a>
+<li><a href="#_queries_and_aggregations">3. Queries and aggregations</a>
+<ul class="sectlevel2">
+<li><a href="#_query_counts">3.1. Query counts</a></li>
+<li><a href="#_metrics">3.2. Metrics</a></li>
+<li><a href="#_aggregations">3.3. Aggregations</a>
<ul class="sectlevel3">
-<li><a href="#_getting_started">3.4.1. Getting started</a></li>
-<li><a href="#_how_to_contribute">3.4.2. How to contribute</a></li>
-<li><a href="#_tracking_page_views">3.4.3. Tracking page views</a></li>
-<li><a href="#_tracking_form_submissions">3.4.4. Tracking form submissions</a></li>
+<li><a href="#_aggregation_types">3.3.1. Aggregation types</a></li>
+</ul>
+</li>
</ul>
</li>
-<li><a href="#_configuration">3.5. Configuration</a>
+<li><a href="#_profile_import_export">4. Profile import & export</a>
+<ul class="sectlevel2">
+<li><a href="#_importing_profiles">4.1. Importing profiles</a>
<ul class="sectlevel3">
-<li><a href="#_centralized_configuration">3.5.1. Centralized configuration</a></li>
-<li><a href="#_changing_the_default_configuration_using_environment_variables_i_e_docker_configuration">3.5.2. Changing the default configuration using environment variables (i.e. Docker configuration)</a></li>
-<li><a href="#_changing_the_default_configuration_using_property_files">3.5.3. Changing the default configuration using property files</a></li>
-<li><a href="#_secured_events_configuration">3.5.4. Secured events configuration</a></li>
-<li><a href="#_installing_the_maxmind_geoiplite2_ip_lookup_database">3.5.5. Installing the MaxMind GeoIPLite2 IP lookup database</a></li>
-<li><a href="#_installing_geonames_database">3.5.6. Installing Geonames database</a></li>
-<li><a href="#_rest_api_security">3.5.7. REST API Security</a></li>
-<li><a href="#_automatic_profile_merging">3.5.8. Automatic profile merging</a></li>
-<li><a href="#_securing_a_production_environment">3.5.9. Securing a production environment</a></li>
-<li><a href="#_integrating_with_an_apache_http_web_server">3.5.10. Integrating with an Apache HTTP web server</a></li>
-<li><a href="#_changing_the_default_tracking_location">3.5.11. Changing the default tracking location</a></li>
-<li><a href="#_apache_karaf_ssh_console">3.5.12. Apache Karaf SSH Console</a></li>
-<li><a href="#_elasticsearch_x_pack_support">3.5.13. ElasticSearch X-Pack Support</a></li>
+<li><a href="#_import_api">4.1.1. Import API</a></li>
</ul>
</li>
-<li><a href="#_useful_apache_unomi_urls">3.6. Useful Apache Unomi URLs</a></li>
-<li><a href="#_how_profile_tracking_works">3.7. How profile tracking works</a>
+<li><a href="#_exporting_profiles">4.2. Exporting profiles</a>
<ul class="sectlevel3">
-<li><a href="#_steps">3.7.1. Steps</a></li>
+<li><a href="#_export_api">4.2.1. Export API</a></li>
</ul>
</li>
+<li><a href="#_configuration_in_details">4.3. Configuration in details</a></li>
</ul>
</li>
-<li><a href="#_queries_and_aggregations">4. Queries and aggregations</a>
+<li><a href="#_consent_management">5. Consent management</a>
<ul class="sectlevel2">
-<li><a href="#_query_counts">4.1. Query counts</a></li>
-<li><a href="#_metrics">4.2. Metrics</a></li>
-<li><a href="#_aggregations">4.3. Aggregations</a>
+<li><a href="#_consent_api">5.1. Consent API</a>
<ul class="sectlevel3">
-<li><a href="#_aggregation_types">4.3.1. Aggregation types</a></li>
+<li><a href="#_profiles_with_consents">5.1.1. Profiles with consents</a></li>
+<li><a href="#_consent_type_definitions">5.1.2. Consent type definitions</a></li>
+<li><a href="#_creating_update_a_visitor_consent">5.1.3. Creating / update a visitor consent</a></li>
+<li><a href="#_how_it_works_internally">5.1.4. How it works (internally)</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#_privacy_management">6. Privacy management</a>
+<ul class="sectlevel2">
+<li><a href="#_setting_up_access_to_the_privacy_endpoint">6.1. Setting up access to the privacy endpoint</a></li>
+<li><a href="#_anonymizing_a_profile">6.2. Anonymizing a profile</a></li>
+<li><a href="#_downloading_profile_data">6.3. Downloading profile data</a></li>
+<li><a href="#_deleting_a_profile">6.4. Deleting a profile</a></li>
+<li><a href="#_related">6.5. Related</a></li>
</ul>
</li>
+<li><a href="#_cluster_setup">7. Cluster setup</a>
+<ul class="sectlevel2">
+<li><a href="#_cluster_setup_2">7.1. Cluster setup</a></li>
</ul>
</li>
-<li><a href="#_profile_import_export">5. Profile import & export</a>
+<li><a href="#_reference">8. Reference</a>
<ul class="sectlevel2">
-<li><a href="#_importing_profiles">5.1. Importing profiles</a>
+<li><a href="#_data_model_overview">8.1. Data Model Overview</a></li>
+<li><a href="#_scope">8.2. Scope</a>
<ul class="sectlevel3">
-<li><a href="#_import_api">5.1.1. Import API</a></li>
+<li><a href="#_example">8.2.1. Example</a></li>
</ul>
</li>
-<li><a href="#_exporting_profiles">5.2. Exporting profiles</a>
+<li><a href="#_item">8.3. Item</a>
<ul class="sectlevel3">
-<li><a href="#_export_api">5.2.1. Export API</a></li>
+<li><a href="#_structure_definition">8.3.1. Structure definition</a></li>
</ul>
</li>
-<li><a href="#_configuration_in_details">5.3. Configuration in details</a></li>
+<li><a href="#_metadata">8.4. Metadata</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_2">8.4.1. Structure definition</a></li>
+<li><a href="#_example_2">8.4.2. Example</a></li>
</ul>
</li>
-<li><a href="#_consent_management">6. Consent management</a>
-<ul class="sectlevel2">
-<li><a href="#_consent_api">6.1. Consent API</a>
+<li><a href="#_metadataitem">8.5. MetadataItem</a>
<ul class="sectlevel3">
-<li><a href="#_profiles_with_consents">6.1.1. Profiles with consents</a></li>
-<li><a href="#_consent_type_definitions">6.1.2. Consent type definitions</a></li>
-<li><a href="#_creating_update_a_visitor_consent">6.1.3. Creating / update a visitor consent</a></li>
-<li><a href="#_how_it_works_internally">6.1.4. How it works (internally)</a></li>
+<li><a href="#_structure_definition_3">8.5.1. Structure definition</a></li>
+<li><a href="#_example_3">8.5.2. Example</a></li>
</ul>
</li>
+<li><a href="#_event">8.6. Event</a>
+<ul class="sectlevel3">
+<li><a href="#_fields">8.6.1. Fields</a></li>
+<li><a href="#_event_types">8.6.2. Event types</a></li>
</ul>
</li>
-<li><a href="#_privacy_management">7. Privacy management</a>
+<li><a href="#_profile">8.7. Profile</a>
<ul class="sectlevel3">
-<li><a href="#_setting_up_access_to_the_privacy_endpoint">7.1. Setting up access to the privacy endpoint</a></li>
-<li><a href="#_anonymizing_a_profile">7.2. Anonymizing a profile</a></li>
-<li><a href="#_downloading_profile_data">7.3. Downloading profile data</a></li>
-<li><a href="#_deleting_a_profile">7.4. Deleting a profile</a></li>
-<li><a href="#_related">7.5. Related</a></li>
+<li><a href="#_structure_definition_4">8.7.1. Structure definition</a></li>
+<li><a href="#_example_4">8.7.2. Example</a></li>
</ul>
</li>
-<li><a href="#_cluster_setup">8. Cluster setup</a>
-<ul class="sectlevel2">
-<li><a href="#_cluster_setup_2">8.1. Cluster setup</a></li>
+<li><a href="#_persona">8.8. Persona</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_5">8.8.1. Structure definition</a></li>
+<li><a href="#_example_5">8.8.2. Example</a></li>
</ul>
</li>
-<li><a href="#_reference">9. Reference</a>
-<ul class="sectlevel2">
-<li><a href="#_built_in_conditions">9.1. Built-in conditions</a>
+<li><a href="#_consent">8.9. Consent</a>
<ul class="sectlevel3">
-<li><a href="#_existing_condition_descriptors">9.1.1. Existing condition descriptors</a></li>
+<li><a href="#_structure_definition_6">8.9.1. Structure definition</a></li>
+<li><a href="#_example_6">8.9.2. Example</a></li>
</ul>
</li>
-<li><a href="#_built_in_actions">9.2. Built-in actions</a>
+<li><a href="#_session">8.10. Session</a>
<ul class="sectlevel3">
-<li><a href="#_existing_actions_descriptors">9.2.1. Existing actions descriptors</a></li>
+<li><a href="#_structure_definition_7">8.10.1. Structure definition</a></li>
+<li><a href="#_example_7">8.10.2. Example</a></li>
</ul>
</li>
+<li><a href="#_segment">8.11. Segment</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_8">8.11.1. Structure definition</a></li>
+<li><a href="#_example_8">8.11.2. Example</a></li>
</ul>
</li>
-<li><a href="#_integration_samples">10. Integration samples</a>
-<ul class="sectlevel2">
-<li><a href="#_samples">10.1. Samples</a></li>
-<li><a href="#_login_sample">10.2. Login sample</a>
+<li><a href="#_condition">8.12. Condition</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_9">8.12.1. Structure definition</a></li>
+<li><a href="#_example_9">8.12.2. Example</a></li>
+</ul>
+</li>
+<li><a href="#_rule">8.13. Rule</a>
<ul class="sectlevel3">
-<li><a href="#_warning">10.2.1. Warning !</a></li>
-<li><a href="#_installing_the_samples">10.2.2. Installing the samples</a></li>
+<li><a href="#_structure_definition_10">8.13.1. Structure definition</a></li>
+<li><a href="#_example_10">8.13.2. Example</a></li>
</ul>
</li>
-<li><a href="#_twitter_sample">10.3. Twitter sample</a>
+<li><a href="#_action">8.14. Action</a>
<ul class="sectlevel3">
-<li><a href="#_overview">10.3.1. Overview</a></li>
-<li><a href="#_interacting_with_the_context_server">10.3.2. Interacting with the context server</a></li>
-<li><a href="#_retrieving_context_information_from_unomi_using_the_context_servlet">10.3.3. Retrieving context information from Unomi using the context servlet</a></li>
+<li><a href="#_structure_definition_11">8.14.1. Structure definition</a></li>
+<li><a href="#_example_11">8.14.2. Example</a></li>
</ul>
</li>
-<li><a href="#_example">10.4. Example</a>
+<li><a href="#_list">8.15. List</a>
<ul class="sectlevel3">
-<li><a href="#_html_page">10.4.1. HTML page</a></li>
-<li><a href="#_javascript">10.4.2. Javascript</a></li>
+<li><a href="#_structure_definition_12">8.15.1. Structure definition</a></li>
+<li><a href="#_example_12">8.15.2. Example</a></li>
+</ul>
+</li>
+<li><a href="#_goal">8.16. Goal</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_13">8.16.1. Structure definition</a></li>
+<li><a href="#_example_13">8.16.2. Example</a></li>
+</ul>
+</li>
+<li><a href="#_campaign">8.17. Campaign</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_14">8.17.1. Structure definition</a></li>
+<li><a href="#_example_14">8.17.2. Example</a></li>
+</ul>
+</li>
+<li><a href="#_scoring_plan">8.18. Scoring plan</a>
+<ul class="sectlevel3">
+<li><a href="#_structure_definition_15">8.18.1. Structure definition</a></li>
+<li><a href="#_example_15">8.18.2. Example</a></li>
+</ul>
+</li>
+<li><a href="#_data_model_changes_for_apache_unomi_1_5_0">8.19. Data Model changes for Apache Unomi 1.5.0</a>
+<ul class="sectlevel3">
+<li><a href="#_data_model_and_elasticsearch_7">8.19.1. Data model and ElasticSearch 7</a></li>
+<li><a href="#_api_changes">8.19.2. API changes</a></li>
+</ul>
+</li>
+<li><a href="#_built_in_event_types">8.20. Built-in Event types</a>
+<ul class="sectlevel3">
+<li><a href="#_login_event_type">8.20.1. Login event type</a></li>
+<li><a href="#_view_event_type">8.20.2. View event type</a></li>
+<li><a href="#_form_event_type">8.20.3. Form event type</a></li>
+<li><a href="#_update_properties_event_type">8.20.4. Update properties event type</a></li>
+<li><a href="#_identify_event_type">8.20.5. Identify event type</a></li>
+<li><a href="#_session_created_event_type">8.20.6. Session created event type</a></li>
+<li><a href="#_goal_event_type">8.20.7. Goal event type</a></li>
+<li><a href="#_modify_consent_event_type">8.20.8. Modify consent event type</a></li>
+</ul>
+</li>
+<li><a href="#_built_in_condition_types">8.21. Built-in condition types</a>
+<ul class="sectlevel3">
+<li><a href="#_existing_condition_type_descriptors">8.21.1. Existing condition type descriptors</a></li>
+</ul>
+</li>
+<li><a href="#_built_in_action_types">8.22. Built-in action types</a>
+<ul class="sectlevel3">
+<li><a href="#_existing_action_types_descriptors">8.22.1. Existing action types descriptors</a></li>
</ul>
</li>
-<li><a href="#_conclusion">10.5. Conclusion</a></li>
-<li><a href="#_annex">10.6. Annex</a></li>
-<li><a href="#_weather_update_sample">10.7. Weather update sample</a></li>
</ul>
</li>
-<li><a href="#_connectors">11. Connectors</a>
+<li><a href="#_integration_samples">9. Integration samples</a>
<ul class="sectlevel2">
-<li><a href="#_connectors_2">11.1. Connectors</a>
+<li><a href="#_samples">9.1. Samples</a></li>
+<li><a href="#_login_sample">9.2. Login sample</a>
<ul class="sectlevel3">
-<li><a href="#_call_for_contributors">11.1.1. Call for contributors</a></li>
+<li><a href="#_warning">9.2.1. Warning !</a></li>
+<li><a href="#_installing_the_samples">9.2.2. Installing the samples</a></li>
</ul>
</li>
-<li><a href="#_salesforce_connector">11.2. Salesforce Connector</a>
+<li><a href="#_twitter_sample">9.3. Twitter sample</a>
<ul class="sectlevel3">
-<li><a href="#_getting_started_2">11.2.1. Getting started</a></li>
-<li><a href="#_properties">11.2.2. Properties</a></li>
-<li><a href="#_hot_deploying_updates_to_the_salesforce_connector_for_developers">11.2.3. Hot-deploying updates to the Salesforce connector (for developers)</a></li>
-<li><a href="#_using_the_salesforce_workbench_for_testing_rest_api">11.2.4. Using the Salesforce Workbench for testing REST API</a></li>
-<li><a href="#_setting_up_streaming_push_queries">11.2.5. Setting up Streaming Push queries</a></li>
-<li><a href="#_executing_the_unit_tests">11.2.6. Executing the unit tests</a></li>
+<li><a href="#_overview">9.3.1. Overview</a></li>
+<li><a href="#_interacting_with_the_context_server">9.3.2. Interacting with the context server</a></li>
+<li><a href="#_retrieving_context_information_from_unomi_using_the_context_servlet">9.3.3. Retrieving context information from Unomi using the context servlet</a></li>
</ul>
</li>
-<li><a href="#_mailchimp_connector">11.3. MailChimp Connector</a>
+<li><a href="#_example_24">9.4. Example</a>
<ul class="sectlevel3">
-<li><a href="#_getting_started_3">11.3.1. Getting started</a></li>
+<li><a href="#_html_page">9.4.1. HTML page</a></li>
+<li><a href="#_javascript">9.4.2. Javascript</a></li>
</ul>
</li>
+<li><a href="#_conclusion">9.5. Conclusion</a></li>
+<li><a href="#_annex">9.6. Annex</a></li>
+<li><a href="#_weather_update_sample">9.7. Weather update sample</a></li>
</ul>
</li>
-<li><a href="#_developers">12. Developers</a>
+<li><a href="#_connectors">10. Connectors</a>
<ul class="sectlevel2">
-<li><a href="#_building">12.1. Building</a>
+<li><a href="#_connectors_2">10.1. Connectors</a>
<ul class="sectlevel3">
-<li><a href="#_initial_setup">12.1.1. Initial Setup</a></li>
-<li><a href="#_building_2">12.1.2. Building</a></li>
-<li><a href="#_installing_an_elasticsearch_server">12.1.3. Installing an ElasticSearch server</a></li>
-<li><a href="#_deploying_the_generated_binary_package">12.1.4. Deploying the generated binary package</a></li>
-<li><a href="#_deploying_into_an_existing_karaf_server">12.1.5. Deploying into an existing Karaf server</a></li>
-<li><a href="#_jdk_selection_on_mac_os_x">12.1.6. JDK Selection on Mac OS X</a></li>
-<li><a href="#_running_the_integration_tests">12.1.7. Running the integration tests</a></li>
-<li><a href="#_running_the_performance_tests">12.1.8. Running the performance tests</a></li>
-<li><a href="#_testing_with_an_example_page">12.1.9. Testing with an example page</a></li>
+<li><a href="#_call_for_contributors">10.1.1. Call for contributors</a></li>
+</ul>
+</li>
+<li><a href="#_salesforce_connector">10.2. Salesforce Connector</a>
+<ul class="sectlevel3">
+<li><a href="#_getting_started_2">10.2.1. Getting started</a></li>
+<li><a href="#_properties">10.2.2. Properties</a></li>
+<li><a href="#_hot_deploying_updates_to_the_salesforce_connector_for_developers">10.2.3. Hot-deploying updates to the Salesforce connector (for developers)</a></li>
+<li><a href="#_using_the_salesforce_workbench_for_testing_rest_api">10.2.4. Using the Salesforce Workbench for testing REST API</a></li>
+<li><a href="#_setting_up_streaming_push_queries">10.2.5. Setting up Streaming Push queries</a></li>
+<li><a href="#_executing_the_unit_tests">10.2.6. Executing the unit tests</a></li>
+</ul>
+</li>
+<li><a href="#_mailchimp_connector">10.3. MailChimp Connector</a>
+<ul class="sectlevel3">
+<li><a href="#_getting_started_3">10.3.1. Getting started</a></li>
+</ul>
+</li>
</ul>
</li>
-<li><a href="#_ssh_shell_commands">12.2. SSH Shell Commands</a>
+<li><a href="#_developers">11. Developers</a>
+<ul class="sectlevel2">
+<li><a href="#_building">11.1. Building</a>
<ul class="sectlevel3">
-<li><a href="#_using_the_shell">12.2.1. Using the shell</a></li>
-<li><a href="#_lifecycle_commands">12.2.2. Lifecycle commands</a></li>
-<li><a href="#_runtime_commands">12.2.3. Runtime commands</a></li>
+<li><a href="#_initial_setup">11.1.1. Initial Setup</a></li>
+<li><a href="#_building_2">11.1.2. Building</a></li>
+<li><a href="#_installing_an_elasticsearch_server">11.1.3. Installing an ElasticSearch server</a></li>
+<li><a href="#_deploying_the_generated_binary_package">11.1.4. Deploying the generated binary package</a></li>
+<li><a href="#_deploying_into_an_existing_karaf_server">11.1.5. Deploying into an existing Karaf server</a></li>
+<li><a href="#_jdk_selection_on_mac_os_x">11.1.6. JDK Selection on Mac OS X</a></li>
+<li><a href="#_running_the_integration_tests">11.1.7. Running the integration tests</a></li>
+<li><a href="#_running_the_performance_tests">11.1.8. Running the performance tests</a></li>
+<li><a href="#_testing_with_an_example_page">11.1.9. Testing with an example page</a></li>
</ul>
</li>
-<li><a href="#_types_vs_instances">12.3. Types vs. instances</a></li>
-<li><a href="#_plugin_structure">12.4. Plugin structure</a></li>
-<li><a href="#_extension_points">12.5. Extension points</a>
+<li><a href="#_ssh_shell_commands">11.2. SSH Shell Commands</a>
<ul class="sectlevel3">
-<li><a href="#_actiontype">12.5.1. ActionType</a></li>
-<li><a href="#_conditiontype">12.5.2. ConditionType</a></li>
-<li><a href="#_persona">12.5.3. Persona</a></li>
-<li><a href="#_propertymergestrategytype">12.5.4. PropertyMergeStrategyType</a></li>
-<li><a href="#_propertytype">12.5.5. PropertyType</a></li>
-<li><a href="#_rule">12.5.6. Rule</a></li>
-<li><a href="#_scoring">12.5.7. Scoring</a></li>
-<li><a href="#_segments_2">12.5.8. Segments</a></li>
-<li><a href="#_tag">12.5.9. Tag</a></li>
-<li><a href="#_valuetype">12.5.10. ValueType</a></li>
+<li><a href="#_using_the_shell">11.2.1. Using the shell</a></li>
+<li><a href="#_lifecycle_commands">11.2.2. Lifecycle commands</a></li>
+<li><a href="#_runtime_commands">11.2.3. Runtime commands</a></li>
</ul>
</li>
-<li><a href="#_other_unomi_entities">12.6. Other Unomi entities</a>
+<li><a href="#_writing_plugins">11.3. Writing Plugins</a></li>
+<li><a href="#_types_vs_instances">11.4. Types vs. instances</a></li>
+<li><a href="#_plugin_structure">11.5. Plugin structure</a></li>
+<li><a href="#_extension_points">11.6. Extension points</a>
<ul class="sectlevel3">
-<li><a href="#_userlist">12.6.1. UserList</a></li>
-<li><a href="#_goal">12.6.2. Goal</a></li>
-<li><a href="#_campaign">12.6.3. Campaign</a></li>
+<li><a href="#_actiontype">11.6.1. ActionType</a></li>
+<li><a href="#_conditiontype">11.6.2. ConditionType</a></li>
+<li><a href="#_persona_2">11.6.3. Persona</a></li>
+<li><a href="#_propertymergestrategytype">11.6.4. PropertyMergeStrategyType</a></li>
+<li><a href="#_propertytype">11.6.5. PropertyType</a></li>
+<li><a href="#_rule_2">11.6.6. Rule</a></li>
+<li><a href="#_scoring">11.6.7. Scoring</a></li>
+<li><a href="#_segments">11.6.8. Segments</a></li>
+<li><a href="#_tag">11.6.9. Tag</a></li>
+<li><a href="#_valuetype">11.6.10. ValueType</a></li>
</ul>
</li>
-<li><a href="#_custom_extensions">12.7. Custom extensions</a>
+<li><a href="#_custom_plugins">11.7. Custom plugins</a>
<ul class="sectlevel3">
-<li><a href="#_creating_an_extension">12.7.1. Creating an extension</a></li>
-<li><a href="#_deployment_and_custom_definition">12.7.2. Deployment and custom definition</a></li>
-<li><a href="#_predefined_segments">12.7.3. Predefined segments</a></li>
-<li><a href="#_predefined_rules">12.7.4. Predefined rules</a></li>
-<li><a href="#_predefined_properties">12.7.5. Predefined properties</a></li>
-<li><a href="#_predefined_child_conditions">12.7.6. Predefined child conditions</a></li>
-<li><a href="#_predefined_personas">12.7.7. Predefined personas</a></li>
-<li><a href="#_custom_actions">12.7.8. Custom actions</a></li>
-<li><a href="#_custom_conditions">12.7.9. Custom conditions</a></li>
+<li><a href="#_creating_a_plugin">11.7.1. Creating a plugin</a></li>
+<li><a href="#_deployment_and_custom_definition">11.7.2. Deployment and custom definition</a></li>
+<li><a href="#_predefined_segments">11.7.3. Predefined segments</a></li>
+<li><a href="#_predefined_rules">11.7.4. Predefined rules</a></li>
+<li><a href="#_predefined_properties">11.7.5. Predefined properties</a></li>
+<li><a href="#_predefined_child_conditions">11.7.6. Predefined child conditions</a></li>
+<li><a href="#_predefined_personas">11.7.7. Predefined personas</a></li>
+<li><a href="#_custom_action_types">11.7.8. Custom action types</a></li>
+<li><a href="#_custom_condition_types">11.7.9. Custom condition types</a></li>
</ul>
</li>
-<li><a href="#_migration_patches">12.8. Migration patches</a></li>
+<li><a href="#_migration_patches">11.8. Migration patches</a></li>
</ul>
</li>
</ul>
@@ -286,7 +384,7 @@
<div id="content">
<div id="preamble">
<div class="sectionbody">
-<div class="imageblock" style="text-align: center">
+<div class="imageblock text-center">
<div class="content">
<img src="images/asf_logo_url.png" alt="asf logo url">
</div>
@@ -299,11 +397,11 @@
<div class="sect2">
<h3 id="_five_minutes_quickstart">1.1. Five Minutes QuickStart</h3>
<div class="paragraph">
-<p>1) Install JDK 8 (<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" class="bare">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a>) and make sure you set the
-JAVA_HOME variable <a href="https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/" class="bare">https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/</a></p>
+<p>1) Install JDK 8 (<a href="https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html" class="bare">https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html</a>) and make sure you set the
+JAVA_HOME variable <a href="https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/" class="bare">https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/</a> (see our <a href="#_jdk_compatibility">Getting Started</a> guide for more information on JDK compatibility)</p>
</div>
<div class="paragraph">
-<p>2) Download ElasticSearch here : <a href="https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3" class="bare">https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3</a> (please <strong>make sure</strong> you use the proper version : 5.6.3)</p>
+<p>2) Download ElasticSearch here : <a href="https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2" class="bare">https://www.elastic.co/downloads/past-releases/elasticsearch-7-4-2</a> (please <strong>make sure</strong> you use the proper version : 7.4.2)</p>
</div>
<div class="paragraph">
<p>3) Uncompress it and change the <code>config/elasticsearch.yml</code> to include the following config : <code>cluster.name: contextElasticSearch</code></p>
@@ -333,413 +431,72 @@ JAVA_HOME variable <a href="https://docs
<p>11) If something goes wrong, you should check the logs in <code>./data/log/karaf.log</code>. If you get errors on ElasticSearch,
make sure you are using the proper version.</p>
</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_concepts">2. Concepts</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Apache Unomi gathers information about users actions, information that is processed and stored by Unomi services. The
-collected information can then be used to personalize content, derive insights on user behavior, categorize the user
-profiles into segments along user-definable dimensions or acted upon by algorithms.</p>
-</div>
-<div class="sect2">
-<h3 id="_items_and_types">2.1. Items and types</h3>
-<div class="paragraph">
-<p>Unomi structures the information it collects using the concept of <code>Item</code> which provides the base information (an
-identifier and a type) the context server needs to process and store the data. Items are persisted according to their
-type (structure) and identifier (identity). This base structure can be extended, if needed, using properties in the
-form of key-value pairs.</p>
-</div>
-<div class="paragraph">
-<p>These properties are further defined by the <code>Item</code>âs type definition which explicits the <code>Item</code>âs structure and
-semantics. By defining new types, users specify which properties (including the type of values they accept) are
-available to items of that specific type.</p>
-</div>
-<div class="paragraph">
-<p>Unomi defines default value types: <code>date</code>, <code>email</code>, <code>integer</code> and <code>string</code>, all pretty self-explanatory. While you can
-think of these value types as "primitive" types, it is possible to extend Unomi by providing additional value types.</p>
-</div>
-<div class="paragraph">
-<p>Additionally, most items are also associated to a scope, which is a concept that Unomi uses to group together related
-items. A given scope is represented in Unomi by a simple string identifier and usually represents an application or set
-of applications from which Unomi gathers data, depending on the desired analysis granularity. In the context of web
-sites, a scope could, for example, represent a site or family of related sites being analyzed. Scopes allow clients
-accessing the context server to filter data to only see relevant data.</p>
-</div>
-<div class="paragraph">
-<p><em>Base <code>Item</code> structure:</em></p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code class="language-json" data-lang="json">{
- "itemType": <type of the item>,
- "scope": <scope>,
- "itemId": <item identifier>,
- "properties": <optional properties>
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Some types can be dynamically defined at runtime by calling to the REST API while other extensions are done via Unomi
-plugins. Part of extending Unomi, therefore, is a matter of defining new types and specifying which kind of Unomi
-entity (e.g. profiles) they can be affected to. For example, the following JSON document can be passed to Unomi to
-declare a new property type identified (and named) <code>tweetNb</code>, tagged with the <code>social</code> tag, targeting profiles and
-using the <code>integer</code> value type.</p>
-</div>
<div class="paragraph">
-<p><em>Example JSON type definition:</em></p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code class="language-json" data-lang="json">{
- "itemId": "tweetNb",
- "itemType": "propertyType",
- "metadata": {
- "id": "tweetNb",
- "name": "tweetNb",
- "systemTags": ["social"]
- },
- "target": "profiles",
- "type": "integer"
-}</code></pre>
-</div>
-</div>
-<div class="quoteblock">
-<blockquote>
-<div class="paragraph">
-<p>Unomi defines a built-in scope (called <code>systemscope</code>) that clients can use to share data across scopes.</p>
-</div>
-</blockquote>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_events">2.2. Events</h3>
-<div class="paragraph">
-<p>Users' actions are conveyed from clients to the context server using events. Of course, the required information
-depends on what is collected and users' interactions with the observed systems but events minimally provide a type, a
-scope and source and target items. Additionally, events are timestamped. Conceptually, an event can be seen as a
-sentence, the event’s type being the verb, the source the subject and the target the object.</p>
-</div>
-<div class="paragraph">
-<p><em>Event structure:</em></p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code class="language-json" data-lang="json">{
- "eventType": <type of the event>,
- "scope": <scope of the event>,
- "source": <Item>,
- "target": <Item>,
- "properties": <optional properties>
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Source and target can be any Unomi item but are not limited to them. In particular, as long as they can be described
-using properties and Unomiâs type mechanism and can be processed either natively or via extension plugins, source and
-target can represent just about anything. Events can also be triggered as part of Unomiâs internal processes for example
-when a rule is triggered.</p>
-</div>
-<div class="paragraph">
-<p>Events are sent to Unomi from client applications using the JSON format and a typical page view event from a web site
-could look something like the following:</p>
-</div>
-<div class="paragraph">
-<p><em>Example page view event:</em></p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code class="language-json" data-lang="json">{
- "eventType": "view",
- "scope": "ACMESPACE",
- "source": {
- "itemType": "site",
- "scope": "ACMESPACE",
- "itemId": "c4761bbf-d85d-432b-8a94-37e866410375"
- },
- "target": {
- "itemType": "page",
- "scope": "ACMESPACE",
- "itemId": "b6acc7b3-6b9d-4a9f-af98-54800ec13a71",
- "properties": {
- "pageInfo": {
- "pageID": "b6acc7b3-6b9d-4a9f-af98-54800ec13a71",
- "pageName": "Home",
- "pagePath": "/sites/ACMESPACE/home",
- "destinationURL": "http://localhost:8080/sites/ACMESPACE/home.html",
- "referringURL": "http://localhost:8080/",
- "language": "en"
- },
- "category": {},
- "attributes": {}
- }
- }
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_profiles">2.3. Profiles</h3>
-<div class="paragraph">
-<p>By processing events, Unomi progressively builds a picture of who the user is and how they behave. This knowledge is
-embedded in <code>Profile</code> object. A profile is an <code>Item</code> with any number of properties and optional segments and scores.
-Unomi provides default properties to cover common data (name, last name, age, email, etc.) as well as default segments
-to categorize users. Unomi users are, however, free and even encouraged to create additional properties and segments to
-better suit their needs.</p>
-</div>
-<div class="paragraph">
-<p>Contrary to other Unomi items, profiles are not part of a scope since we want to be able to track the associated user
-across applications. For this reason, data collected for a given profile in a specific scope is still available to any
-scoped item that accesses the profile information.</p>
-</div>
-<div class="paragraph">
-<p>It is interesting to note that there is not necessarily a one to one mapping between users and profiles as users can be
-captured across applications and different observation contexts. As identifying information might not be available in
-all contexts in which data is collected, resolving profiles to a single physical user can become complex because
-physical users are not observed directly. Rather, their portrait is progressively patched together and made clearer as
-Unomi captures more and more traces of their actions. Unomi will merge related profiles as soon as collected data
-permits positive association between distinct profiles, usually as a result of the user performing some identifying
-action in a context where the user hadnât already been positively identified.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_sessions">2.4. Sessions</h3>
-<div class="paragraph">
-<p>A session represents a time-bounded interaction between a user (via their associated profile) and a Unomi-enabled
-application. A session represents the sequence of actions the user performed during its duration. For this reason,
-events are associated with the session during which they occurred. In the context of web applications, sessions are
-usually linked to HTTP sessions.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_segments">2.5. Segments</h3>
-<div class="paragraph">
-<p>Segments are used to group profiles together, and are based on conditions that are executed on profiles to determine if
-they are part of a segment or not. This also means that a profile may enter or leave a segment based on changes in their
-properties, making segments a highly dynamic concept.</p>
-</div>
-<div class="paragraph">
-<p>Here is an example of a simple segment definition registered using the REST API:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code>curl -X POST http://localhost:8181/cxs/segments \
---user karaf:karaf \
--H "Content-Type: application/json" \
--d @- <<'EOF'
-{
- "metadata": {
- "id": "leads",
- "name": "Leads",
- "scope": "systemscope",
- "description": "You can customize the list below by editing the leads segment.",
- "readOnly":true
- },
- "condition": {
- "type": "booleanCondition",
- "parameterValues": {
- "operator" : "and",
- "subConditions": [
- {
- "type": "profilePropertyCondition",
- "parameterValues": {
- "propertyName": "properties.leadAssignedTo",
- "comparisonOperator": "exists"
- }
- }
- ]
- }
- }
-}
-EOF</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>For more details on the conditions and how they are structured using conditions, see the next section.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_conditions">2.6. Conditions</h3>
-<div class="paragraph">
-<p>Conditions are a very useful notion inside of Apache Unomi, as they are used as the basis for multiple other objects.
-Conditions may be used as parts of:</p>
+<p>Next steps:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>Segments</p>
-</li>
-<li>
-<p>Rules</p>
-</li>
-<li>
-<p>Queries</p>
-</li>
-<li>
-<p>Campaigns</p>
-</li>
-<li>
-<p>Goals</p>
-</li>
-<li>
-<p>Profile filters</p>
+<p>Connect to <a href="http://localhost:8181" class="bare">http://localhost:8181</a> to try our some live examples (such as the web tracker)</p>
</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>A condition is composed of two basic elements:</p>
-</div>
-<div class="ulist">
-<ul>
<li>
-<p>a condition type identifier</p>
+<p>Trying our integration <a href="#_samples">samples page</a></p>
</li>
<li>
-<p>a list of parameter values for the condition, that can be of any type, and in some cases may include sub-conditions</p>
+<p>Learning more about the <a href="#_web_tracker">web tracker</a></p>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>A condition type identifier is a string that contains a unique identifier for a condition type. Example condition types
-may include <code>booleanCondition</code>, <code>eventTypeCondition</code>, <code>eventPropertyCondition</code>, and so on. Plugins may implement new
-condition types that may implement any logic that may be needed. The parameter values are simply lists of objects that
-may be used to configure the condition. In the case of a <code>booleanCondition</code> for example one of the parameter values will
-be an <code>operator</code> that will contain values such as <code>and</code> or <code>or</code> and a second parameter value called <code>subConditions</code>
-that contains a list of conditions to evaluate with that operator. The result of a condition is always a boolean
-value of true or false.</p>
-</div>
-<div class="paragraph">
-<p>Apache Unomi provides quite a lot of built-in condition types, including boolean types that make it possible to
-compose conditions using operators such as <code>and</code>, <code>or</code> or <code>not</code>. Composition is an essential element of building more
-complex conditions.</p>
-</div>
-<div class="paragraph">
-<p>Here is an example of a complex condition:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code class="language-json" data-lang="json">{
- "condition": {
- "type": "booleanCondition",
- "parameterValues": {
- "operator":"or",
- "subConditions":[
- {
- "type": "eventTypeCondition",
- "parameterValues": {
- "eventTypeId": "sessionCreated"
- }
- },
- {
- "type": "eventTypeCondition",
- "parameterValues": {
- "eventTypeId": "sessionReassigned"
- }
- }
- ]
- }
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>As we can see in the above example we use the boolean <code>or</code> condition to check if the event type is of type <code>sessionCreated</code>
-or <code>sessionReassigned</code>.</p>
</div>
-<div class="paragraph">
-<p>For a more complete list of available conditions, see the <a href="#_built_in_conditions">Built-in conditions</a> reference section.</p>
</div>
</div>
+<div class="sect1">
+<h2 id="_first_steps_with_apache_unomi">2. First steps with Apache Unomi</h2>
+<div class="sectionbody">
<div class="sect2">
-<h3 id="_rules">2.7. Rules</h3>
-<div class="imageblock">
-<div class="content">
-<img src="images/unomi-rule-engine.png" alt="Unomi Rule Engine">
-</div>
-</div>
-<div class="paragraph">
-<p>Apache Unomi has a built-in rule engine that is one of the most important components of its architecture. Every time
-an event is received by the server, it is evaluated against all the rules and the ones matching the incoming event will
-be executed. You can think of a rule as a structure that looks like this:</p>
-</div>
-<div class="literalblock">
-<div class="content">
-<pre>when
- conditions
-then
- actions</pre>
-</div>
-</div>
+<h3 id="_getting_started_with_unomi">2.1. Getting started with Unomi</h3>
<div class="paragraph">
-<p>Basically when a rule is evaluated, all the conditions in the <code>when</code> part are evaluated and if the result matches
-(meaning it evaluates to <code>true</code>) then the actions will be executed in sequence.</p>
-</div>
-<div class="paragraph">
-<p>The real power of Apache Unomi comes from the fact that <code>conditions</code> and <code>actions</code> are fully pluggeable and that plugins
-may implement new conditions and/or actions to perform any task. You can imagine conditions checking incoming event data
-against third-party systems or even against authentication systesm, and actions actually pulling or pushing data to third-party
-systems.</p>
-</div>
-<div class="paragraph">
-<p>For example the Salesforce CRM connector is simply a set of actions that pull and push data into the CRM. It is then
-just a matter of setting up the proper rules with the proper conditions to determine when and how the data will be
-pulled or pushed into the third-party system.</p>
+<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="_actions">2.7.1. Actions</h4>
-<div class="paragraph">
-<p>Actions are executed by rules in a sequence, and an action is only executed once the previous action has finished
-executing. If an action generates an exception, it will be logged and the execution sequence will continue unless in the
-case of a Runtime exception (such as a NullPointerException).</p>
-</div>
+<h4 id="_prerequisites">2.1.1. Prerequisites</h4>
<div class="paragraph">
-<p>Actions are implemented as Java classes, and as such may perform any kind of tasks that may include calling web hooks,
-setting profile properties, extracting data from the incoming request (such as resolving location from an IP address),
-or even pulling and/or pushing data to third-party systems such as a CRM server.</p>
+<p>This document assumes working knowledge of <a href="https://git-scm.com/">git</a> to be able to retrieve the code for Unomi and the example.
+Additionally, you will require a working Java 8 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 8 or greater.</p>
</div>
+<div class="sect4">
+<h5 id="_jdk_compatibility">JDK compatibility</h5>
<div class="paragraph">
-<p>Apache Unomi also comes with built-in actions. You may find the list of built-in actions in the <a href="#_built_in_actions">Built-in actions</a> section.</p>
-</div>
-</div>
+<p>Starting with Java 9, Oracle made some big changes to the Java platform releases. This is why Apache Unomi is focused on
+supporting the Long Term Supported versions of the JDK, currently versions 8 and 11. We do not test with intermediate
+versions so they may or may not work properly. Currently the most tested version is version 8 and version 11 is also
+supported.</p>
</div>
-<div class="sect2">
-<h3 id="_request_flow">2.8. Request flow</h3>
<div class="paragraph">
-<p>Here is an overview of how Unomi processes incoming requests to the <code>ContextServlet</code>.</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<img src="images/unomi-request.png" alt="Unomi request overview">
-</div>
+<p>Also, as there are new licensing restrictions on JDKs provided by Oracle for production usages, Apache Unomi has also
+added support for OpenJDK builds. Other JDK distributions might also work but are not regularly tested so you should use
+them at your own risks.</p>
</div>
</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_first_steps_with_apache_unomi">3. First steps with Apache Unomi</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_getting_started_with_unomi">3.1. Getting started with Unomi</h3>
+<div class="sect4">
+<h5 id="_elasticsearch_compatibility">ElasticSearch compatibility</h5>
<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>
+<p>Starting with version 1.5.0 Apache Unomi adds compatibility with ElasticSearch 7.4 . It is highly recommended to use the
+ElasticSearch version provided by the documentation when possible. However minor versions (7.4.x) should also work, and
+one version higher (7.5) will usually work. Going higher than that is risky given the way that ElasticSearch is developed
+and breaking changes are introduced quite often. If in doubt, don’t hesitate to check with the Apache Unomi community
+to get the latest information about ElasticSearch version compatibility.</p>
</div>
-<div class="sect3">
-<h4 id="_prerequisites">3.1.1. Prerequisites</h4>
-<div class="paragraph">
-<p>This document assumes that you are already familiar with Unomi’s <a href="#_concepts">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.
-Additionally, 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">3.1.2. Running Unomi</h4>
+<h4 id="_running_unomi">2.1.2. Running Unomi</h4>
<div class="sect4">
<h5 id="_start_unomi">Start Unomi</h5>
<div class="paragraph">
-<p>Start Unomi according to the <a href="#_5-min-quickstart">5 minute quick start</a> or by compiling using the building <a href="building-and-deploying.html#Deploying_the_generated_package">instructions</a>. Once you have Karaf running,
+<p>Start Unomi according to the <a href="#_five_minutes_quickstart">five minutes quick start</a> or by compiling using the
+<a href="#_building">building 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">
@@ -759,23 +516,27 @@ Initializing cluster service endpoint...
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 class="paragraph">
-<p>Now that your service is up and running you can go look at the <a href="#_request-examples">request examples</a> to learn basic
+<p>You can now find an introduction page at the following location: <a href="http://localhost:8181" class="bare">http://localhost:8181</a></p>
+</div>
+<div class="paragraph">
+<p>Also now that your service is up and running you can go look at the
+<a href="#_request_examples">request examples</a> to learn basic
requests you can do once your server is up and running.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
-<h3 id="_recipes">3.2. Recipes</h3>
+<h3 id="_recipes">2.2. Recipes</h3>
<div class="sect3">
-<h4 id="_introduction">3.2.1. Introduction</h4>
+<h4 id="_introduction">2.2.1. Introduction</h4>
<div class="paragraph">
<p>In this section of the documentation we provide quick recipes focused on helping you achieve a specific result with
Apache Unomi.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_read_a_profile">3.2.2. How to read a profile</h4>
+<h4 id="_how_to_read_a_profile">2.2.2. How to read a profile</h4>
<div class="paragraph">
<p>The simplest way to retrieve profile data for the current profile is to simply send a request to the /context.json
endpoint. However you will need to send a body along with that request. Here’s an example:</p>
@@ -814,7 +575,7 @@ and security.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_update_a_profile_from_the_public_internet">3.2.3. How to update a profile from the public internet</h4>
+<h4 id="_how_to_update_a_profile_from_the_public_internet">2.2.3. How to update a profile from the public internet</h4>
<div class="paragraph">
<p>Before we get into how to update a profile directly from a request coming from the public internet, we’ll quickly talk
first about how NOT to do it, because we often see users using the following anti-patterns.</p>
@@ -965,7 +726,7 @@ EOF</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_search_for_profile_events">3.2.4. How to search for profile events</h4>
+<h4 id="_how_to_search_for_profile_events">2.2.4. How to search for profile events</h4>
<div class="paragraph">
<p>Sometimes you want to retrieve events for a known profile. You will need to provide a query in the body of the request
that looks something like this (and <a href="https://unomi.apache.org/rest-api-doc/#1768188821">documentation is available in the REST API</a>) :</p>
@@ -995,7 +756,7 @@ EOF</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_create_a_new_rule">3.2.5. How to create a new rule</h4>
+<h4 id="_how_to_create_a_new_rule">2.2.5. How to create a new rule</h4>
<div class="paragraph">
<p>There are basically two ways to create a new rule :</p>
</div>
@@ -1049,7 +810,7 @@ contained in the event to the current pr
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_search_for_profiles">3.2.6. How to search for profiles</h4>
+<h4 id="_how_to_search_for_profiles">2.2.6. How to search for profiles</h4>
<div class="paragraph">
<p>In order to search for profiles you will have to use the /cxs/profiles/search endpoint that requires a Query JSON
structure. Here’s an example of a profile search with a Query object:</p>
@@ -1103,13 +864,13 @@ on the server and potentially this could
</div>
</div>
<div class="sect3">
-<h4 id="_getting_updating_consents">3.2.7. Getting / updating consents</h4>
+<h4 id="_getting_updating_consents">2.2.7. Getting / updating consents</h4>
<div class="paragraph">
<p>You can find information on how to retrieve or create/update consents in the <a href="#_consent_api">Consent API</a> section.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_send_a_login_event_to_unomi">3.2.8. How to send a login event to Unomi</h4>
+<h4 id="_how_to_send_a_login_event_to_unomi">2.2.8. How to send a login event to Unomi</h4>
<div class="paragraph">
<p>Tracking logins must be done carefully with Unomi. A login event is considered a "privileged" event and therefore for
not be initiated from the public internet. Ideally user authentication should always be validated by a trusted third-
@@ -1175,9 +936,9 @@ security issue since it could be a way t
</div>
</div>
<div class="sect2">
-<h3 id="_request_examples">3.3. Request examples</h3>
+<h3 id="_request_examples">2.3. Request examples</h3>
<div class="sect3">
-<h4 id="_retrieving_your_first_context">3.3.1. Retrieving your first context</h4>
+<h4 id="_retrieving_your_first_context">2.3.1. Retrieving your first context</h4>
<div class="paragraph">
<p>You can retrieve a context using curl like this :</p>
</div>
@@ -1193,7 +954,7 @@ events using the cxs.collectEvents() fun
</div>
</div>
<div class="sect3">
-<h4 id="_retrieving_a_context_as_a_json_object">3.3.2. Retrieving a context as a JSON object.</h4>
+<h4 id="_retrieving_a_context_as_a_json_object">2.3.2. Retrieving a context as a JSON object.</h4>
<div class="paragraph">
<p>If you prefer to retrieve a pure JSON object, you can simply use a request formed like this:</p>
</div>
@@ -1204,7 +965,7 @@ events using the cxs.collectEvents() fun
</div>
</div>
<div class="sect3">
-<h4 id="_accessing_profile_properties_in_a_context">3.3.3. Accessing profile properties in a context</h4>
+<h4 id="_accessing_profile_properties_in_a_context">2.3.3. Accessing profile properties in a context</h4>
<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
@@ -1239,7 +1000,7 @@ Java class.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_sending_events_using_the_context_servlet">3.3.4. Sending events using the context servlet</h4>
+<h4 id="_sending_events_using_the_context_servlet">2.3.4. Sending events using the context servlet</h4>
<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>
@@ -1288,7 +1049,7 @@ to send events in a network optimal way
</div>
</div>
<div class="sect3">
-<h4 id="_sending_events_using_the_eventcollector_servlet">3.3.5. Sending events using the eventcollector servlet</h4>
+<h4 id="_sending_events_using_the_eventcollector_servlet">2.3.5. Sending events using the eventcollector servlet</h4>
<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>
@@ -1331,7 +1092,7 @@ to send additional events.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_where_to_go_from_here">3.3.6. Where to go from here</h4>
+<h4 id="_where_to_go_from_here">2.3.6. Where to go from here</h4>
<div class="ulist">
<ul>
<li>
@@ -1348,13 +1109,13 @@ to send additional events.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_web_tracker">3.4. Web Tracker</h3>
+<h3 id="_web_tracker">2.4. Web Tracker</h3>
<div class="paragraph">
<p>This extension is providing the web tracker to start collecting visitors data on your website.
The tracker is implemented as an integration of <a href="https://github.com/segmentio/analytics.js">analytics.js</a> for Unomi.</p>
</div>
<div class="sect3">
-<h4 id="_getting_started">3.4.1. Getting started</h4>
+<h4 id="_getting_started">2.4.1. Getting started</h4>
<div class="paragraph">
<p>Extension can be tested at : <code><a href="http://localhost:8181/tracker/index.html" class="bare">http://localhost:8181/tracker/index.html</a></code></p>
</div>
@@ -1381,14 +1142,14 @@ All methods can be used on <code>unomiTr
</div>
</div>
<div class="sect3">
-<h4 id="_how_to_contribute">3.4.2. How to contribute</h4>
+<h4 id="_how_to_contribute">2.4.2. How to contribute</h4>
<div class="paragraph">
<p>The source code is in the folder javascript with a package.json, the file to update is <code>analytics.js-integration-apache-unomi.js</code> apply your modification in this file then use the command <code>yarn build</code> to compile a new JS file.
Then you can use the test page to try your changes <code><a href="http://localhost:8181/tracker/index.html" class="bare">http://localhost:8181/tracker/index.html</a></code>.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_tracking_page_views">3.4.3. Tracking page views</h4>
+<h4 id="_tracking_page_views">2.4.3. Tracking page views</h4>
<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
@@ -1475,7 +1236,7 @@ categories).</p>
</div>
</div>
<div class="sect3">
-<h4 id="_tracking_form_submissions">3.4.4. Tracking form submissions</h4>
+<h4 id="_tracking_form_submissions">2.4.4. Tracking form submissions</h4>
<div class="paragraph">
<p>Using the web tracker you can also track form submissions. In order to do this a few steps are required to get a form’s
submission to be tracked and then its form values to be sent as events to Apache Unomi. Finally setting up a rule to
@@ -1747,9 +1508,9 @@ cef09b89-6b99-4e4f-a99c-a4159a66b42b|for
</div>
</div>
<div class="sect2">
-<h3 id="_configuration">3.5. Configuration</h3>
+<h3 id="_configuration">2.5. Configuration</h3>
<div class="sect3">
-<h4 id="_centralized_configuration">3.5.1. Centralized configuration</h4>
+<h4 id="_centralized_configuration">2.5.1. Centralized configuration</h4>
<div class="paragraph">
<p>Apache Unomi uses a centralized configuration file that contains both system properties and configuration properties.
These settings are then fed to the OSGi and other configuration files using placeholder that look something like this:</p>
@@ -1775,7 +1536,7 @@ the values in the <code>$MY_KARAF_HOME/e
</div>
</div>
<div class="sect3">
-<h4 id="_changing_the_default_configuration_using_environment_variables_i_e_docker_configuration">3.5.2. Changing the default configuration using environment variables (i.e. Docker configuration)</h4>
+<h4 id="_changing_the_default_configuration_using_environment_variables_i_e_docker_configuration">2.5.2. Changing the default configuration using environment variables (i.e. Docker configuration)</h4>
<div class="paragraph">
<p>You might want to use environment variables to change the default system configuration, especially if you intend to run
Apache Unomi inside a Docker container. You can find the list of all the environment variable names in the following file:</p>
@@ -1793,7 +1554,7 @@ variables you want to use.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_changing_the_default_configuration_using_property_files">3.5.3. Changing the default configuration using property files</h4>
+<h4 id="_changing_the_default_configuration_using_property_files">2.5.3. Changing the default configuration using property files</h4>
<div class="paragraph">
<p>If you want to change the default configuration using property files instead of environment variables, you can perform
any modification you want in the <code>$MY_KARAF_HOME/etc/unomi.custom.system.properties</code> file.</p>
@@ -1833,14 +1594,14 @@ you have stored previously.</p>
<div class="content">
<pre class="highlight"><code>org.apache.unomi.elasticsearch.cluster.name=contextElasticSearch
# The elasticsearch.adresses may be a comma seperated list of host names and ports such as
-# hostA:9300,hostB:9300
+# hostA:9200,hostB:9200
# Note: the port number must be repeated for each host.
-org.apache.unomi.elasticsearch.addresses=localhost:9300</code></pre>
+org.apache.unomi.elasticsearch.addresses=localhost:9200</code></pre>
</div>
</div>
</div>
<div class="sect3">
-<h4 id="_secured_events_configuration">3.5.4. Secured events configuration</h4>
+<h4 id="_secured_events_configuration">2.5.4. Secured events configuration</h4>
<div class="paragraph">
<p>Apache Unomi secures some events by default. It comes out of the box with a default configuration that you can adjust
by using the centralized configuration file override in <code>$MY_KARAF_HOME/etc/unomi.custom.system.properties</code></p>
@@ -1932,7 +1693,7 @@ thirdparty.provider1.allowedEvents=login
</div>
</div>
<div class="sect3">
-<h4 id="_installing_the_maxmind_geoiplite2_ip_lookup_database">3.5.5. Installing the MaxMind GeoIPLite2 IP lookup database</h4>
+<h4 id="_installing_the_maxmind_geoiplite2_ip_lookup_database">2.5.5. Installing the MaxMind GeoIPLite2 IP lookup database</h4>
<div class="paragraph">
<p>Apache Unomi requires an IP database in order to resolve IP addresses to user location.
The GeoLite2 database can be downloaded from MaxMind here :
@@ -1943,7 +1704,7 @@ The GeoLite2 database can be downloaded
</div>
</div>
<div class="sect3">
-<h4 id="_installing_geonames_database">3.5.6. Installing Geonames database</h4>
+<h4 id="_installing_geonames_database">2.5.6. Installing Geonames database</h4>
<div class="paragraph">
<p>Apache Unomi 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>
@@ -1961,7 +1722,7 @@ At the end, you should have about 4 mill
</div>
</div>
<div class="sect3">
-<h4 id="_rest_api_security">3.5.7. REST API Security</h4>
+<h4 id="_rest_api_security">2.5.7. REST API Security</h4>
<div class="paragraph">
<p>The Apache Unomi 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>
@@ -1994,7 +1755,7 @@ org.ops4j.pax.web.ssl.keypassword=${env:
</div>
</div>
<div class="sect3">
-<h4 id="_automatic_profile_merging">3.5.8. Automatic profile merging</h4>
+<h4 id="_automatic_profile_merging">2.5.8. 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
@@ -2013,7 +1774,7 @@ Upon sending one of the events, all matc
</div>
</div>
<div class="sect3">
-<h4 id="_securing_a_production_environment">3.5.9. Securing a production environment</h4>
+<h4 id="_securing_a_production_environment">2.5.9. 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>
@@ -2123,7 +1884,7 @@ a proxy, and use it to filter any commun
</div>
</div>
<div class="sect3">
-<h4 id="_integrating_with_an_apache_http_web_server">3.5.10. Integrating with an Apache HTTP web server</h4>
+<h4 id="_integrating_with_an_apache_http_web_server">2.5.10. 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>
@@ -2221,7 +1982,7 @@ ProxyPassReverse / http://localhost:8181
</div>
</div>
<div class="sect3">
-<h4 id="_changing_the_default_tracking_location">3.5.11. Changing the default tracking location</h4>
+<h4 id="_changing_the_default_tracking_location">2.5.11. 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
@@ -2249,7 +2010,7 @@ org.apache.unomi.ip.default.longitude=${
</div>
</div>
<div class="sect3">
-<h4 id="_apache_karaf_ssh_console">3.5.12. Apache Karaf SSH Console</h4>
+<h4 id="_apache_karaf_ssh_console">2.5.12. 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>
@@ -2265,102 +2026,75 @@ shell commands in the "Shell commands" s
</div>
</div>
<div class="sect3">
-<h4 id="_elasticsearch_x_pack_support">3.5.13. ElasticSearch X-Pack Support</h4>
+<h4 id="_elasticsearch_authentication_and_security">2.5.13. ElasticSearch authentication and security</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>
+<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>
-<div class="sect4">
-<h5 id="_important">Important !</h5>
<div class="paragraph">
-<p>Do not start Unomi directly with unomi:start, perform the following steps below first !</p>
-</div>
+<p>Depending on your ElasticSearch license you may need to install Kibana and enable xpack security: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-security.html">https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-security.html</a></p>
</div>
<div class="sect4">
-<h5 id="_installation_steps">Installation steps</h5>
-<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>
+<h5 id="_user_authentication">User authentication !</h5>
<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>
+<p>If your ElasticSearch have been configured to be only accessible by authenticated users (<a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.5/setting-up-authentication.html">https://www.elastic.co/guide/en/elasticsearch/reference/7.5/setting-up-authentication.html</a>)</p>
</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>
+<p>Just edit <code>etc/org.apache.unomi.persistence.elasticsearch.cfg</code> to add the following settings:</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>
+<pre class="highlight"><code>username=USER
+password=PASSWORD</code></pre>
+</div>
</div>
</div>
+<div class="sect4">
+<h5 id="_ssl_communication">SSL communication</h5>
<div class="paragraph">
-<p>.</p>
+<p>By default Unomi will communicate with ElasticSearch using <code>http</code>
+but you can configure your ElasticSearch server(s) to allow encrypted request using <code>https</code>.</p>
</div>
<div class="paragraph">
-<p>Launch Karaf and launch unomi using the command from the shell :</p>
+<p>You can follow this documentation to enable SSL on your ElasticSearch server(s):</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code>unomi:start</code></pre>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.5/ssl-tls.html">Full documentation</a></p>
+</li>
+<li>
+<p><a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-tls.html#node-certificates">Configure certificates</a></p>
+</li>
+<li>
+<p><a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.5/configuring-tls.html#tls-http">Encrypt HTTP communications</a></p>
+</li>
+</ul>
</div>
+<div class="paragraph">
+<p>If your ElasticSearch is correctly configure to encrypt communications on <code>https</code>:</p>
</div>
<div class="paragraph">
-<p>Alternatively you could edit the configuration directly from the Karaf shell using the following commands:</p>
+<p>Just edit <code>etc/org.apache.unomi.persistence.elasticsearch.cfg</code> to add the following settings:</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>
+<pre class="highlight"><code>sslEnable=true</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>
+<p>By default, certificates will have to be configured on the Apache Unomi server to be able to trust the identity
+of the ElasticSearch server(s). But if you need to trust all certificates automatically, you can use this setting:</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>
+<pre class="highlight"><code>sslTrustAllCertificates=true</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
-<h3 id="_useful_apache_unomi_urls">3.6. Useful Apache Unomi URLs</h3>
+<h3 id="_useful_apache_unomi_urls">2.6. Useful Apache Unomi URLs</h3>
<div class="paragraph">
<p>In this section we will list some useful URLs that can be used to quickly access parts of Apache Unomi that can help
you understand or diagnose what is going on in the system.</p>
@@ -2458,12 +2192,12 @@ where PROFILE_ID is a profile identifier
</table>
</div>
<div class="sect2">
-<h3 id="_how_profile_tracking_works">3.7. How profile tracking works</h3>
+<h3 id="_how_profile_tracking_works">2.7. How profile tracking works</h3>
<div class="paragraph">
<p>In this section you will learn how Apache Unomi keeps track of visitors.</p>
</div>
<div class="sect3">
-<h4 id="_steps">3.7.1. Steps</h4>
+<h4 id="_steps">2.7.1. Steps</h4>
<div class="olist arabic">
<ol class="arabic">
<li>
@@ -2502,10 +2236,21 @@ forcing.</p>
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_context_request_flow">2.8. Context Request Flow</h3>
+<div class="paragraph">
+<p>Here is an overview of how Unomi processes incoming requests to the <code>ContextServlet</code>.</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/unomi-request.png" alt="Unomi request overview">
+</div>
+</div>
+</div>
</div>
</div>
<div class="sect1">
-<h2 id="_queries_and_aggregations">4. Queries and aggregations</h2>
+<h2 id="_queries_and_aggregations">3. Queries and aggregations</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Apache Unomi contains a <code>query</code> endpoint that is quite powerful. It provides ways to perform queries that can quickly
@@ -2515,7 +2260,7 @@ get result counts, apply metrics such as
<p>In this section we will show examples of requests that may be built using this API.</p>
</div>
<div class="sect2">
-<h3 id="_query_counts">4.1. Query counts</h3>
+<h3 id="_query_counts">3.1. Query counts</h3>
<div class="paragraph">
<p>Query counts are highly optimized queries that will count the number of objects that match a certain condition without
retrieving the results. This can be used for example to quickly figure out how many objects will match a given condition
@@ -2570,7 +2315,7 @@ EOF</code></pre>
</div>
</div>
<div class="sect2">
-<h3 id="_metrics">4.2. Metrics</h3>
+<h3 id="_metrics">3.2. Metrics</h3>
<div class="paragraph">
<p>Metric queries make it possible to apply functions to the resulting property. The supported metrics are:</p>
</div>
@@ -2632,7 +2377,7 @@ EOF</code></pre>
</div>
</div>
<div class="sect2">
-<h3 id="_aggregations">4.3. Aggregations</h3>
+<h3 id="_aggregations">3.3. Aggregations</h3>
<div class="paragraph">
<p>Aggregations are a very powerful way to build queries in Apache Unomi that will collect and aggregate data by filtering
on certain conditions.</p>
@@ -2644,7 +2389,7 @@ on certain conditions.</p>
- a condition (used to filter the data set that will be aggregated)</p>
</div>
<div class="sect3">
-<h4 id="_aggregation_types">4.3.1. Aggregation types</h4>
+<h4 id="_aggregation_types">3.3.1. Aggregation types</h4>
<div class="paragraph">
<p>Aggregations may be of different types. They are listed here below.</p>
</div>
@@ -2882,14 +2627,14 @@ EOF</code></pre>
</div>
</div>
<div class="sect1">
-<h2 id="_profile_import_export">5. Profile import & export</h2>
+<h2 id="_profile_import_export">4. Profile import & export</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The profile import and export feature in Apache Unomi is based on configurations and consumes or produces CSV files that
contain profiles to be imported and exported.</p>
</div>
<div class="sect2">
-<h3 id="_importing_profiles">5.1. Importing profiles</h3>
+<h3 id="_importing_profiles">4.1. Importing profiles</h3>
<div class="paragraph">
<p>Only <code>ftp</code>, <code>sftp</code>, <code>ftps</code> and <code>file</code> are supported in the source path. For example:</p>
</div>
@@ -2949,7 +2694,7 @@ ftps://USER@HOST?password=PASSWORD&f
</ul>
</div>
<div class="sect3">
-<h4 id="_import_api">5.1.1. Import API</h4>
+<h4 id="_import_api">4.1.1. Import API</h4>
<div class="paragraph">
<p>Apache Unomi provides REST endpoints to manage import configurations:</p>
</div>
@@ -3024,7 +2769,7 @@ ftps://USER@HOST?password=PASSWORD&f
</div>
</div>
<div class="sect2">
-<h3 id="_exporting_profiles">5.2. Exporting profiles</h3>
+<h3 id="_exporting_profiles">4.2. Exporting profiles</h3>
<div class="paragraph">
<p>Only <code>ftp</code>, <code>sftp</code>, <code>ftps</code> and `file are supported in the source path. For example:</p>
</div>
@@ -3045,7 +2790,7 @@ per file.</p>
<p>See <a href="http://camel.apache.org/ftp.html and http://camel.apache.org/file2.html to" class="bare">http://camel.apache.org/ftp.html and http://camel.apache.org/file2.html to</a> build more complex destination path.</p>
</div>
<div class="sect3">
-<h4 id="_export_api">5.2.1. Export API</h4>
+<h4 id="_export_api">4.2.1. Export API</h4>
<div class="paragraph">
<p>Apache Unomi provides REST endpoints to manage export configurations:</p>
</div>
@@ -3113,7 +2858,7 @@ per file.</p>
</div>
</div>
<div class="sect2">
-<h3 id="_configuration_in_details">5.3. Configuration in details</h3>
+<h3 id="_configuration_in_details">4.3. Configuration in details</h3>
<div class="paragraph">
<p>First configuration you need to change would be the configuration type of your import / export feature (code name
router) in the <code>etc/unomi.custom.system.properties</code> file (creating it if necessary):</p>
@@ -3207,17 +2952,17 @@ org.apache.unomi.router.config.allowedEn
</div>
</div>
<div class="sect1">
-<h2 id="_consent_management">6. Consent management</h2>
+<h2 id="_consent_management">5. Consent management</h2>
<div class="sectionbody">
<div class="sect2">
-<h3 id="_consent_api">6.1. Consent API</h3>
+<h3 id="_consent_api">5.1. Consent API</h3>
<div class="paragraph">
<p>Starting with Apache Unomi 1.3, 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">6.1.1. Profiles with consents</h4>
+<h4 id="_profiles_with_consents">5.1.1. Profiles with consents</h4>
<div class="paragraph">
<p>Visitor profiles now contain a new Consent object that contains the following information:</p>
</div>
@@ -3292,7 +3037,7 @@ EOF</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_consent_type_definitions">6.1.2. Consent type definitions</h4>
+<h4 id="_consent_type_definitions">5.1.2. 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>
@@ -3303,7 +3048,7 @@ consent type.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_creating_update_a_visitor_consent">6.1.3. Creating / update a visitor consent</h4>
+<h4 id="_creating_update_a_visitor_consent">5.1.3. 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>
@@ -3386,7 +3131,7 @@ EOF</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_how_it_works_internally">6.1.4. How it works (internally)</h4>
+<h4 id="_how_it_works_internally">5.1.4. 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>
@@ -3429,14 +3174,14 @@ EOF</code></pre>
</div>
</div>
<div class="sect1">
-<h2 id="_privacy_management">7. Privacy management</h2>
+<h2 id="_privacy_management">6. Privacy management</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Apache Unomi provides an endpoint to manage visitor privacy. You will find in this section information about what it
includes as well as how to use it.</p>
</div>
-<div class="sect3">
-<h4 id="_setting_up_access_to_the_privacy_endpoint">7.1. Setting up access to the privacy endpoint</h4>
+<div class="sect2">
+<h3 id="_setting_up_access_to_the_privacy_endpoint">6.1. Setting up access to the privacy endpoint</h3>
<div class="paragraph">
<p>The privacy endpoint is a bit special, because despite being protected by basic authentication as the rest of the REST
API is is actually designed to be available to end-users.</p>
@@ -3461,8 +3206,8 @@ geographic location)</p>
</ol>
</div>
</div>
-<div class="sect3">
-<h4 id="_anonymizing_a_profile">7.2. Anonymizing a profile</h4>
+<div class="sect2">
+<h3 id="_anonymizing_a_profile">6.2. Anonymizing a profile</h3>
<div class="paragraph">
<p>It is possible to anonymize a profile, meaning it will remove all "identifying" property values from the profile.
Basically all properties with the tag <code>personalIdentifierProperties</code> will be purged from the profile.</p>
@@ -3480,8 +3225,8 @@ Basically all properties with the tag <c
and <code>ASCOPE</code> must be replaced by a scope identifier.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_downloading_profile_data">7.3. Downloading profile data</h4>
+<div class="sect2">
+<h3 id="_downloading_profile_data">6.3. Downloading profile data</h3>
<div class="paragraph">
<p>It is possible to download the profile data of a user. This will only download the profile for a user using the
specified ID as a cookie value.</p>
@@ -3501,8 +3246,8 @@ IDs.</p>
<p>where <code>PROFILE-ID</code> is the profile identifier for which to download the profile.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_deleting_a_profile">7.4. Deleting a profile</h4>
+<div class="sect2">
+<h3 id="_deleting_a_profile">6.4. Deleting a profile</h3>
<div class="paragraph">
<p>It is possible to delete a profile, but this works a little differently than you might expect. In all cases the data
contained in the profile will be completely erased. If the <code>withData</code> optional flag is set to true, all past event and
@@ -3518,8 +3263,8 @@ session data will also be detached from
and the <code>withData</code> specifies whether the data associated with the profile must be anonymized or not</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_related">7.5. Related</h4>
+<div class="sect2">
+<h3 id="_related">6.5. Related</h3>
<div class="paragraph">
<p>You might also be interested in the <a href="#_consent_api">Consent API</a> section that describe how to manage profile consents.</p>
</div>
@@ -3527,10 +3272,10 @@ and the <code>withData</code> specifies
</div>
</div>
<div class="sect1">
-<h2 id="_cluster_setup">8. Cluster setup</h2>
+<h2 id="_cluster_setup">7. Cluster setup</h2>
<div class="sectionbody">
<div class="sect2">
-<h3 id="_cluster_setup_2">8.1. Cluster setup</h3>
+<h3 id="_cluster_setup_2">7.1. Cluster setup</h3>
<div class="paragraph">
<p>Apache Karaf relies on Apache Karaf Cellar, which in turn uses Hazelcast to discover and configure its cluster.</p>
</div>
@@ -3571,12 +3316,2634 @@ placeholders in the hazelcast.xml file i
</div>
</div>
<div class="sect1">
-<h2 id="_reference">9. Reference</h2>
+<h2 id="_reference">8. Reference</h2>
<div class="sectionbody">
<div class="sect2">
-<h3 id="_built_in_conditions">9.1. Built-in conditions</h3>
+<h3 id="_data_model_overview">8.1. Data Model Overview</h3>
+<div class="paragraph">
+<p>Apache Unomi gathers information about users actions, information that is processed and stored by Unomi services.
+The collected information can then be used to personalize content, derive insights on user behavior, categorize the
+user profiles into segments along user-definable dimensions or acted upon by algorithms.</p>
+</div>
+<div class="paragraph">
+<p>The following data model only contains the classes and properties directly related to the most important objects of Apache Unomi.
+There are other classes that are less central to the functionality but all the major ones are represented in the diagram below:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<img src="images/data-model-overview.png" alt="data model overview">
+</div>
+</div>
+<div class="paragraph">
+<p>We will detail many of these classes in the document below.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_scope">8.2. Scope</h3>
+<div class="paragraph">
+<p>Scopes are not actually an object in the system, but simply unique strings that are used to "classify" objects.
+For example, when using scopes with a web content management system, a scope could be associated with a site identifier or even a host name.</p>
+</div>
+<div class="quoteblock">
+<blockquote>
+<div class="paragraph">
+<p>Unomi defines a built-in scope (called <code>systemscope</code>) that clients can use to share data across scopes.</p>
+</div>
+</blockquote>
+</div>
+<div class="sect3">
+<h4 id="_example">8.2.1. Example</h4>
+<div class="paragraph">
+<p>In the following example, the scope uses the unique identifier of a web site called âdigitallâ.</p>
+</div>
[... 3471 lines stripped ...]