Skip to main content

Historical data

Uniform adds the ability to expose the data collected in Sitecore Xdb for a specific contact. Since the data has already been collected, it is called "historical" data.

Data in Sitecore Xdb is stored in contacts and interactions. To use Uniform's terminology, a contact is a visitor and an interaction is a visit. Loading historical data involves loading interaction data from Sitecore Xdb.

Endpoint#

Historical data is retrieved using an endpoint called the "historical data endpoint". This endpoint exposes the service HistoricalDataNodeService. This service is responsible for retrieving the data from Sitecore Xdb and converting it into a format that is compatible with the Uniform tracker.

The service is defined in the Sitecore config file Uniform.Tracking.SitecoreXdb.config. In this file you can see that the service's settings are defined in an object located in Sitecore config under uniform > xdb > activity. The service uses these settings to determine exactly what data to retrieve from Sitecore Xdb. These settings are called "filters".

The path to the endpoint on a Sitecore CD instance is:

/uniform/api/content/[SITECORE SITE NAME]/xdb/history/[UNIFORM VISITOR ID]
note

You can get the Uniform visitor id from the global JavaScript object uniform.visitor.id.

Filters#

The historical data endpoint uses settings from Sitecore config to determine what data from Sitecore Xdb to expose. Filters are used to identify the data that is exposed.

Structure#

A filter is configured using XML. The following is an example of a fully configured filter:

<default>    <sites>        <site name="*" />    </sites>    <campaigns>        <campaigns2020 start="2020" startFormat="yyyy" end="2021" endFormat="yyyy">            <email2020>{6EE47820-3747-4BA8-88BE-4E9BDA8F22EC}</email2020>        </campaigns2020>    </campaigns>    <events>        <goals2020 start="2020" startFormat="yyyy" end="2021" endFormat="yyyy">            <brochuresRequest>{968897F1-328A-489D-88E8-BE78F4370958}</brochuresRequest>            <register>{8FFB183B-DA1A-4C74-8F3A-9729E9FCFF6A}</register>        </goals2020>        <pageEvents>            <putInBasket>{5E31CCE2-78F7-4C16-83E2-E701B7B14AD5}</putInBasket>        </pageEvents>    </events>    <pageViews>        <year2019 start="2019" startFormat="yyyy" end="2020" endFormat="yyyy" />    </pageViews></default>

Filters are added to Sitecore config under the section uniform > xdb > activity > filters.

<configuration xmlns:set="http://www.sitecore.net/xmlconfig/set/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">  <!--    This file enables a service that uses the xConnect client dlls.    These dlls are not available on XM CD instances. As a result,    this file should only be enabled on XP CD instances.  -->  <sitecore role:require="ContentDelivery or Standalone">    <uniform>      <xdb>        <activity type="Uniform.Optimize.Filters.HistoricalDataSettings, Uniform.Optimize.Tracking.SitecoreXdb" singleInstance="true">          <filters hint="raw:AddFilter">            <!--                 Filters go here.            -->          </filters>        </activity>      </xdb>    </uniform>  </sitecore></configuration>

Multiple filters#

Multiple filters are supported. When multiple filters are configured, data that matches any one of the filters is returned.

Site selectors#

A filter can read Sitecore Xdb data collected for one or more Sitecore sites. Regular expressions are used to specify the site (or sites) a filter applies to.

Include all sites#

<sites>    <site name="*" /></sites>

Include sites by name#

<sites>    <site name="prod-site" />    <site name="staging-site" /></sites>

Include sites using wildcards#

<sites>    <site name="prod*" />    <site name="staging*" /></sites>

Activity selectors#

Each filter has the ability to include visit activity. The following visit activities are supported:

  • Campaigns - Configured under the campaigns section.
  • Goals - Configured under the events section.
  • Page events - Configured under the events section.
  • Page views - Configured under the pageViews section.

You can control the activities that are included using the following settings:

  • Start date - The interaction that triggered the activity must have started on or after the specified date. If no start date is specified, the interaction
    is included provided the other criteria is satisfied.
  • End date - The interaction that triggered the activity must have ended on or before the specified date. If no end date is specified, the interaction is included provided the other criteria is satisfied.
  • Definition ids - The interaction is included if the interaction is associated with one of the definition ids specified in the filter. (Since all page view events use the same definition id, this setting is not required for page views.)
note

For date settings, the date and date format must be specified. The date format must be a supported .NET date and time format specifier.

Mulitple campaigns with no start or end date#

The configuration below will result in interactions that meet the following conditions being retrieved:

  • Triggered the campaign {6EE47820-3747-4BA8-88BE-4E9BDA8F22EC}
<campaigns>    <successfulCampaigns>        <email2020>{6EE47820-3747-4BA8-88BE-4E9BDA8F22EC}</email2020>        <kiosk2021>{78D544F9-87D5-4EC1-88E5-FCBDF9AB053F}</kiosk2021>    </successfulCampaigns></campaigns>

Single campaign with start date#

The configuration below will result in interactions that meet the following conditions being retrieved:

  • Triggered the campaign {6EE47820-3747-4BA8-88BE-4E9BDA8F22EC}
  • Started in the year 2020 or later
<campaigns>    <before2021 start="2020" startFormat="yyyy">        <email2020>{6EE47820-3747-4BA8-88BE-4E9BDA8F22EC}</email2020>    </before2021></campaigns>

Single goal with end date#

The configuration below will result in goals that meet the following conditions being retrieved:

  • Triggered the goal {E3439ACE-EC08-48BC-B0A4-ADF2C8FDE071}
  • Ended in the year 2021 or earlier
<events>    <before2022 end="2021" endFormat="yyyy">        <registered>{E3439ACE-EC08-48BC-B0A4-ADF2C8FDE071}</registered>    </before2022></events>

Single page events with start and end date#

The configuration below will result in page events that meet the following conditions being retrieved:

  • Triggered the page event {9775F496-295D-4D9D-B2E2-C6742FE8EC09}
  • Started in the year 2020 or later
  • Ended in the year 2021 or earlier
<events>    <suspect2020 start="2020" startFormat="yyyy" end="2021" endFormat="yyyy">        <invalidCoupon>{9775F496-295D-4D9D-B2E2-C6742FE8EC09}</invalidCoupon>    </suspect2020></events>

Page views with no start or end date#

The configuration below will result in all page views from all interactions being retrieved because all interactions include at least one page view event.

<pageViews>    <pages /></pageViews>

Page views for a specific item#

The configuration below will result in all page views for a specific page being retrieved.

<pageViews>    <pages>        <promo1 type="item">{C7A0E9A5-F64E-4614-AAD1-9B1B87C1EFC0}</promo1>    </pages></pageViews>

Page views for a specific template#

The configuration below will result in all page views for a pages based on a specific template being retrieved.

<pageViews>    <pages>        <promo1 type="template">{D890A329-E3FE-4A0B-998B-4040E39386A1}</promo1>    </pages></pageViews>

Page views for a specific template#

The configuration below will result in page views that meet the following conditions being retrieved:

  • Page is the item {C7A0E9A5-F64E-4614-AAD1-9B1B87C1EFC0} or the item viewed is based on the template {D890A329-E3FE-4A0B-998B-4040E39386A1}
  • Started in the year 2020 or later
<pageViews>    <pages start="2020" startFormat="yyyy">        <promo1 type="item">{C7A0E9A5-F64E-4614-AAD1-9B1B87C1EFC0}</promo1>        <promo1 type="template">{C7A0E9A5-F64E-4614-AAD1-9B1B87C1EFC0}</promo1>    </pages></pageViews>

Data#

Filters determine the entities to read from Sitecore Xdb. This section describes the properties for those entities that the historical data endpoint exposes.

note

Currently, these properties cannot be changed (i.e. you cannot include additional properties or exclude any of the default properties). This may change in future versions of Uniform for Sitecore.

Interactions#

Each interaction is exposed as a visit with the following properties:

PropertyValue
idInteraction id
visitorIdUniform visitor id
startInteraction start date
endInteraction end date
updatedInteraction end date
dataObject that contains additional tracking data (i.e. campaign, goals, page events)

The following is an example of how the historical data service exposes a Sitecore interaction as a Uniform visit:

{    "id": "2f840848-3287-43e8-9f03-49aec64822ee",    "visitorId": "4f59ebcc-f921-4c8d-a296-85565c1db8e0",    "start": "2020-01-02T08:00:00.000Z",    "end": "2020-01-02T8:15:00.000Z",    "updated": "2020-01-02T8:15:00.000Z",    "data": {}}

Campaigns#

Each interaction may have 0 or 1 campaign assigned. If the campaign that is assigned is a campaign that was included in the filter used to read data from Sitecore Xdb, campaign details will be included in the visit.

PropertyValue
dateDate when the campaign was triggered on the Sitecore interaction
data.idSitecore campaign id
data.nameSitecore campaign name

Campaign details are included in the data property on the Uniform visit. The following is an example of how the Sitecore campaign is exposed on a Uniform visit:

{    ...,    "data": {        "campaign": {            "date": "2020-01-02T08:00:00.000Z",            "data": {                "id": "63a010c1-c283-4fa7-8e65-b16422aedc29",                "name": "New Year 2020 Campaign"            }        }    }}

Activities#

Each interaction may have 0 or many events assigned. If the event that is assigned is a type that was included in the filter used to read data from Sitecore Xdb, event details will be included in the visit as activities.

The historical data service converts events into Uniform activities.

All Uniform activities have the following properties:

PropertyValue
typeSitecore event type (goal, page event, page view)
dateDate when the Sitecore event was triggered on the Sitecore interaction

Activities that represent goals and page events have the following properties:

PropertyValue
data.idSitecore event id
data.nameSitecore event name
data.pointsPoints assigned to the Sitecore event

Activities that represent page views have the following properties:

PropertyValue
data.item.idSitecore item id
data.item.nameSitecore item name
data.urlUrl that the visitor used to view the page

Activities are included in the data property on the Uniform visit. The following is an example of how Sitecore events are exposed on a Uniform visit:

{    ...,    "data": {        "activities": [            {                "type": "goal",                "date": "2020-01-02T08:01:00.000Z",                "data": {                    "id": "dc9ad12a-8523-44ea-bd55-cfb6509c89bc",                    "name": "Whitepaper Downloaded",                    "points": 3                }            },            {                "type": "page event",                "date": "2020-01-02T08:02:00.000Z",                "data": {                    "id": "77af35df-96e8-4ad9-ac9c-089887e4df07",                    "name": "Video Started",                    "points": 0                }            },            {                "type": "page view",                "date": "2020-01-02T08:03:00.000Z",                "data": {                    "item": {                        "id": "2846feb9-66a1-4966-8322-d6b789a50cd2",                        "name": "Our Locations",                    },                    "url": "https://www.my-site.com/locations"                }            }        ]    }}

Pipelines#

Get historical data#

The historical data service uses this pipeline to retrieve the data it exposes. In most cases, filters are the best way to identify the historical data to retrieve. For cases where filters are insufficient, custom processors can be added to the pipeline.

Pipeline#

  • Name: getHistoricalData
  • Base type for custom processors: Uniform.Optimize.Pipelines.GetHistoricalData.GetHistoricalDataPipelineProcessor, Uniform.Optimize.Tracking.SitecoreXdb

Pipeline args#

The pipeline args are defined in the following type:

  • Type: Uniform.Optimize.Pipelines.GetHistoricalData.GetHistoricalDataPipelineArgs, Uniform.Optimize.Tracking.SitecoreXdb

This type has the following properties:

  • Client - Xconnect client that can be used to read contact and interaction data from Sitecore Xdb.
  • ContactIdentifier - Identifier for the Sitecore contact.
  • HistoricalDataNode - Represents the data that the historical data service will return. If your custom processor needs to add additional events, this is the object you should add those events to.
  • Site - The Sitecore site whose historical data is being requested.
  • UniformContactId - Value that identifies the contact for the Uniform tracker.

Get contact data#

To retrieve contact data patch the GetContact processor in the getHistoricalData processor with your facets list.

<configuration xmlns:set="http://www.sitecore.net/xmlconfig/set/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">  <sitecore role:require="ContentDelivery or Standalone">    <pipelines>      <group name="uniform">        <pipelines>          <getHistoricalData>            <processor type="Uniform.Optimize.Pipelines.GetHistoricalData.GetContact, Uniform.Optimize.Tracking.SitecoreXdb">              <facets hint="list">                <facet>Emails</facet>                <facet>Personal</facet>              </facets>            </processor>          </getHistoricalData>        </pipelines>      </group>    </pipelines>  </sitecore></configuration>