jExperience architecture overview

March 6, 2023
Note: Marketing Factory is renamed to jExperience in version 1.11 and Apache Unomi is renamed to jCustomer. The 1.10 documentation has been updated to reflect the product name change.

Personalizing the customer experience is in every marketer’s mind and has a strong impact on customer data integration, across channels and applications. This architecture overview helps developers and architects understand how they can use and extend jExperience and jCustomer to integrate customer data.

High-level architecture overview

This section provides a high-level architecture view of jExperience and describes Jahia, jExperience, jCustomer, and Elasticsearch.

concept.png

  • Jahia
    A customer digital experience platform that contains CMS, WCM, and portal features and the built-in Jahia Studio developer environment. Jahia is extensible by adding or developing OSGi modules that may range from simple content components to full-blown single-page applications.
  • jExperience
    An A/B testing and personalization solution that leverages the Jahia platform and integrates with jCustomer.
  • jCustomer
    The core Customer Data Platform (CDP) engine. jCustomer stores and indexes customer data and events generated by visitors.
  • Elasticsearch
    The backend storage, indexation and query server system that stores data in jCustomer. It is also highly scalable and offers high-availability mechanisms.

jExperience and components

This section describes jExperience and jExperience components. jExperience includes web tracking and personalization modules, a management UI and a proxy servlet that communicates with jCustomer. Components include personalized banners and a carousel, and the privacy manager.

details.png

jExperience

jExperience is a Jahia module that interfaces with both Jahia and jCustomer to provide functionality.

The module is composed of:

  • Web tracking
    JavaScript code that tracks visitors and collects and sends events to jCustomer. jExperience automatically inserts the JavaScript into the pages that are generated by Jahia. 
  • Personalization modules
    Modules that are strongly integrated with Jahia’s Edit mode to offer A/B testing and personalization features on any Jahia component.
  • Management UI
    The interface for marketers to access visitors data, profiling, analytics and data integration features.
  • Proxy Servlet
    Ensures that only Jahia users with the proper credentials have access to the CXS Private Admin REST API implemented by jCustomer. The servlet acts as an authorization bridge between the two systems.

jExperience components

jExperience components are elements designed for Jahia that integrate with the A/B testing and personalization features of jExperience to build experiences that contain personalized banners and carousels, and a privacy manager. New components may be developed by third parties.

The Oasis Context Server (CXS) specification

The interface between jExperience and jCustomer is defined by the OASIS Context Server specification. The specification is a work in progress at the OASIS foundation and defines an open standard to deliver personalized user experiences. The goal is to assist organizations that currently struggle to create and deliver consistent personalized experiences across channels, markets and systems. The specification defines a standardized API contract to talk to context server implementations.

The following image shows the two APIs that are described in the CXS specification. The CXS Public API is used to collect data and the CXS Internal API is used for Customer Data management, analytics, and configuration.

interface.png

jCustomer

jCustomer is the Jahia distribution of Apache Unomi. jCustomer processes customer-generated events and executes rules based on events to update customer profiles. jCustomer stores and delivers the profile in a context object. The object also contains augmented information such as the profile’s resolved segments or properties aggregated from different systems connected to jCustomer, for example, from CRM and WCM applications.

jCustomer is an API-first server and is used by jExperience to track customers and deliver A/B testing and personalization. It can also be used to deliver ads or even to build personalized native mobile applications.

Functional architecture

unomi.png

Events

Events are the main inputs into the jCustomer server. Events can range from a single page view event to a native mobile application action such as a button press or application start. New applications may define new event types and simply send them through the CXS Public REST API using HTTP POST calls to be processed and recorded by jCustomer.

Context

A context is a collection of the current customer profile and contextual information about the current interaction with jCustomer, for example the customer’s segments and session information (resolved geographic location from the IP).

Profiles

Profiles represent information collected about a customer. Profiles can contain extensible properties that may contain personal or anonymous data. By default, a cookie keeps track of a profile on the browser side. Also, no personal data is required by the tracking mechanism as a profile ID is automatically generated when a new visitor is detected by jCustomer.

Rules

Rules are composed of conditions and actions. If a rule’s conditions are satisfied, the actions defined in the rule are executed. You can define and modify rules at any time and rules will react to new events in the system. As conditions and actions can be extended using plugins, rules are a powerful way to add real-time functionality to jCustomer. The rule engine behaves as follows:

  1. An internal or external event is received by jExperience.
  2. The rule engine is triggered.
  3. Rules are evaluated in order of priority. For each rule, the rule engine evaluates rule conditions. If conditions meet the rule criteria, rule actions are executed in the order in which they are defined.

Conditions

Conditions are matched against events or profiles and are used to build segments or rules. For example, profiles with an age property above 21 or a profile that has viewed a page or a group of pages are both conditions. You can use AND and OR operators to build more complex conditions.

Actions

Actions are sections of logic that execute when a certain set of conditions is met. Actions only execute when the conditions of a rule are satisfied.

jExperience contains the following predefined actions:

  • Update profile properties
  • Add to list
  • Send an email
  • Push or pull data to Salesforce CRM
  • Enrich customer session with weather data

Segments (Dynamic)

Segments group the profiles that are stored in jCustomer. A segment defines that conditions that a profile must match to be included in the segment. As segments are dynamic groups, a customer profile can move segments when customer information changes or when profile conditions are modified.

Static Lists

Profiles can be added to static lists either manually or using rule actions. Once a profile is added to a static list, you can only remove the profile by manually editing the list.

Scoring Plans

Scoring plans are a digital marketing tool that increment a score on a profile when certain conditions are met. You can also create advanced conditions to increment scores on profiles.

Custom plugins

Developers can implement custom plugins to provide new conditions or actions, and deploy predefined rules, property types, or any other functionality that may be implemented using OSGi bundles. jCustomer is also an OSGi application.

Technical architecture

jCustomer is a Apache Karaf (OSGi) application. jCustomer runs as a server-based Java service that is accessible through a REST API defined as part of the OASIS Context Server specification. As jCustomer uses an OSGi engine at its core, it is extensible and very flexible in terms of deployment scenarios. It is also designed to scale out since it uses cluster-tested technologies such as Elasticsearch, Apache Karaf Cellar (based on Hazelcast) and REST-API level-load distribution.

technical.png

 

The REST API is built using Apache CXF based on Java Beans that are automatically mapped as REST endpoints. Custom plugins may define new REST APIs to extend the built-in API functionality.

Extending jExperience and jCustomer

extending.png

Client side

Javascript

jCustomer context.js/context.json
The endpoint can retrieve the visitor’s profile, directly inject events and evaluate conditions to check if the current visitor matches certain personalization conditions. For example, you can use the endpoint to only display text if the visitor belongs to a specified segment.

jExperience wem.js
The function can be used to send data to jCustomer, catch events generated when a variant displays and to send events to your analytics platform. Note that this event is used by Jahia's AT-Internet and Google Analytics modules.

Cookies

context-profile-id
The identifier of the cookie that keeps track of the jCustomer profile. The ID value rarely changes. For example, when profile merges the cookie is assigned a new value from the resolved master profile.

wem-session-id
The identifier used by jExperience to keep track of visitor sessions. The cookie is short-lived and represents an actual group of interactions that is grouped together for session-based analysis in the various management UIs.

Server side

jCustomer plugins

Developers can implement custom plugins to provide new conditions or actions, and deploy predefined rules, property types, or any other functionality that can be implemented using OSGi bundles. jCustomer is also an OSGi application. Custom plugins can send data to other third-party systems such as big data technologies, CRMs, DMPs, marketing automation systems, or any system that can process customer-generated events and profile information.

Conditions

Custom plugins can define new conditions, for example, conditions that integrate with external systems to provide more ways to filter visitors. Conditions can either be implemented in Java or as JSON definition files that extend existing conditions. You can use conditions in segment definitions or rules.

Rule actions

Actions are implemented in Java and new actions (that can push or pull data from external systems) can be implemented as part of a custom jCustomer plugin. For example, Jahia's Salesforce CRM integration uses actions that may push or pull lead data to and from jCustomer profiles.

Other plugin contents

Plugins may contain additional property type definitions, predefined rules, custom REST endpoints or anything that is acceptable in an OSGi bundle, such as activators, listeners, and services.