The contact data model
The contact, or contact entity, contains all the information that you collect about an individual from their interactions across channels, devices, and websites.
The contact data model describes the data structures, such as contact facets, that are used to store information about the contact. You can use the Entity Model API to extend these data structures programmatically.
By default, the contact entity stores information, such as personal name, e-mail addresses, interaction history, outcomes achieved, and automation states. The contact data model enables you to add your own contact facets, and it is flexible to store almost any type of additional data specific to your organization.
Facets can be grouped into the following categories:
-
System – used by the system. These cannot be removed or disabled.
-
Standard – commonly used facets that come as standard with Sitecore.
-
Custom – created specifically for your organization.
Contacts are created automatically when an individual interacts with your website or when you import an interaction that cannot be associated with a contact already in the system. They can be imported, or created programmatically using the API, and they can also be created automatically when you upgrade from an earlier version of Sitecore.
Contact facets
Contact facets are hierarchical data structures that group related attributes together into a single unit stored on the contact. The contact entity consists of a unique identifier, internal system data structures, and a set of facets.
The data stored in facets can be organized as follows:
-
Attributes – stores most of the basic .NET data types, for example, strings, integers, floating point numbers, GUIDs, date-time values, and enumerations.
-
Elements – stores compound attributes that can contain multiple attributes, nested elements, and dictionaries of elements.
-
Dictionaries – stores named elements in a random order.
These data structures allow you to build custom facets that can store information about the contact relevant to your organization.
You can change your Sitecore configuration to either enable or disable standard and custom facets.
System facets
System facets store information required by the Sitecore Experience Platform. They are permanently part of the contact entity and cannot be disabled or customized. However, some contact facet attributes can be set through the API, for example, the external contact identifier, engagement value points, and integration identifiers.
-
System – holds information such as the total amount of engagement value points accumulated by the contact or attributes related to contact classification and integration.
-
Identifiers – holds the external identifier of the contact and some other related attributes.
-
Tags – implements a dictionary that can store named sets of time-stamped values.
-
Extensions – stores custom values on the contact.
-
Behavior profiles – stores data that is based on the contact’s observed behavior and is used to initialize the profile of new web interactions.
The following code demonstrates how you access the engagement value points and the external user name attributes stored on the contact.
namespace Examples
{
using System.IO;
using Sitecore.Analytics;
using Sitecore.Analytics.Tracking;
internal class Sample
{
internal void GetBasicInfo(TextWriter writer)
{
if ((Tracker.Current != null) && (Tracker.Current.Contact != null))
{
Contact contact = Tracker.Current.Contact;
writer.WriteLine("Identifier: {0}", contact.Identifiers.Identifier);
writer.WriteLine("Total engagement value points: {0}", contact.System.Value);
}
}
}
}
Standard facets
Standard facets come with Sitecore by default and implement structures with commonly used attributes such as personal name, shipping addresses, email addresses, and phone numbers. You can use these facets as they are, remove them, replace them with your own facet implementations, or you can extend them with the following additional attributes.
-
Addresses – implements a dictionary of named postal addresses associated with the contact. The postal address consists of the country, state, or province, city, postal code, and the street. It also supports storing geographic coordinates.
-
Communication profile – stores the communication preferences of the contact, including whether the contact has revoked their consent to be contacted.
-
Email addresses – implements a dictionary of named email addresses associated with the contact. The facets supports storing a bounce count with each email address.
-
Personal info – stores the personal name, nickname, age, gender, and the job title of the contact.
-
Phone number – implements a dictionary of named phone numbers associated with the contact. Each phone number includes a country code, phone number, and extension (if relevant).
-
Picture – stores a binary stream that contains the profile picture associated with the contact.
-
Preferences – stores preferences such as the contact’s preferred language.
You can disable standard facets by editing the Sitecore.Analytics.Model.config file.
For example, you can use the following sample code to remove the Picture facet, the content of the elements node, and the values of the contract attributes.
<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<sitecore>
<model>
<elements />
<entities>
<contact>
<factory />
<facets>
<facet name="Personal" contract="..." />
<facet name="Addresses" contract="..." />
<facet name="Emails" contract="..." />
<facet name="Phone Numbers" contract="..." />
<facet name="Picture" contract="..." />
<facet name="Communication Profile" contract="..." />
<facet name="Preferences" contract="..." />
</facets>
</contact>
</entities>
</model>
</sitecore>
</configuration>
In this sample, you are removing the facet definition from the facets node to ensure that the facet is not loaded from xDB even if it appears on the persisted contact. When you save the contact, the facets on the persisted contact are still preserved even if they are not specified in the configuration file. If necessary, you can restore the facet definition to access the content as it was before the facet was removed.
The following code demonstrates how you can access and update the standard facets:
namespace Examples
{
using System;
using Sitecore.Diagnostics;
using Sitecore.Analytics;
using Sitecore.Analytics.Model.Entities;
using Sitecore.Analytics.Model.Framework;
using Sitecore.Analytics.Tracking;
internal class Sample
{
internal void UpdatePersonalInfo(string firstName, string surename, DateTime birthDate)
{
if ((Tracker.Current != null) && (Tracker.Current.Contact != null))
{
try
{
Contact contact = Tracker.Current.Contact;
IContactPersonalInfo personal = contact.GetFacet<IContactPersonalInfo>("Personal");
personal.FirstName = firstName;
personal.Surname = surename;
personal.BirthDate = birthDate;
}
catch (FacetNotAvailableException ex)
{
Log.Warn("The 'Personal' facet is not available.", ex);
}
}
}
}
}
Custom facets
You can create your own custom contact facets to store data specific to your organization. These facets are treated by the system in the same way as standard facets. They are fully integrated into the contact and can be accessed from anywhere in the system.