Written by The Jahia Team
   Estimated reading time:

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 Marketing Factory and Apache Unomi to integrate customer data.

High-level architecture overview

This section provides a high-level architecture view of Marketing Factory and describes Digital Experience Manager, Marketing Factory, Apache Unomi, and Elasticsearch.

concept.png

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

Marketing Factory core and components

This section describes the Marketing Factory core and Marketing Factory components. The core includes web tracking and personalization modules, a management UI and a proxy servlet that communicates with Apache Unomi. Components include personalized banners and a carousel, and the privacy manager.

details.png

Marketing Factory core

The Marketing Factory core is a DX module that interfaces with both DX and Apache Unomi to provide functionality.

The core is composed of:

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

Marketing Factory components

Marketing Factory components are elements designed for Jahia DX that integrate with the A/B testing and personalization features of Marketing Factory 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 Marketing Factory and Apache Unomi 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

Apache Unomi

Apache Unomi is the Open Source Customer Data Platform and an implementation of the OASIS Context Server specification. Unomi processes customer-generated events and executes rules based on events to update customer profiles. Unomi 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 Unomi, for example, from CRM and WCM applications.

Unomi is an API-first server and is used by Marketing Factory 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 Apache Unomi 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 Apache Unomi.

Context

A context is a collection of the current customer profile and contextual information about the current interaction with Apache Unomi, 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 Apache Unomi.

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 Apache Unomi. The rule engine behaves as follows:

  1. An internal or external event is received by Marketing Factory.
  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.

Market Factory 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 Apache Unomi. 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. Apache Unomi is also an OSGi application.

Technical architecture

Apache Unomi is a Apache Karaf (OSGi) application. Unomi runs as a server-based Java service that is accessible through a REST API defined as part of the OASIS Context Server specification. As Unomi 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 Marketing Factory and Apache Unomi

extending.png

Client side

Javascript

Apache Unomi 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.

Marketing Factory wem.js
The function can be used to send data to Apache Unomi, 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 Context Server/Apache Unomi 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 Marketing Factory 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

Apache Unomi 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. Apache Unomi 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 Unomi plugin. For example, Jahia's Salesforce CRM integration uses actions that may push or pull lead data to and from Apache Unomi 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.