Facets
A facet is piece of information that enriches a contact or an interaction. For contacts, this might include their name and address. For interactions, this might include the location of the interaction. You can use Sitecore's default facets or create your own.
A facet is made up of a facet model, and a facet definition. You can reuse a facet model with a different key or define it with the same key for contacts and then interactions.
Facet keys are case sensitive.
Facet models
Facet models are classes that inherit Sitecore.XConnect.Facet:
using Sitecore.XConnect;
using System;
namespace Documentation.Examples
{
[Serializable]
[FacetKey(DefaultFacetKey)]
public class FrequentFlyerInformation : Facet
{
public const string DefaultFacetKey = "FrequentFlyerInformation";
public string FrequentFlyerID { get; set; } // Example: ABC12345
public string PreferredAirport { get; set; } // Example: Kastrup
}
}
Facet definitions
A facet definition associates a facet model with a key and assigns it to an entity (Contact or Interaction). Facets are defined in a collection model, which must be deployed to xConnect before you can use it.
The following model defines a single contact facet named FrequentFlyerInformation:
using Sitecore.XConnect;
using Sitecore.XConnect.Schema;
namespace Documentation.Examples
{
public class CollectionModel
{
public static XdbModel Model { get; } = BuildModel();
private static XdbModel BuildModel()
{
XdbModelBuilder modelBuilder = new XdbModelBuilder("DocumentationModel", new XdbModelVersion(1, 0));
modelBuilder.DefineFacet<Contact, FrequentFlyerInformation>(); // Uses default facet key
return modelBuilder.BuildModel();
}
}
}
Contact and interaction facets
Contact facets should describe the qualities of a contact, not their behavior. For example:
-
Frequent flyer status
-
Supermarket loyalty card number
Interaction facets should describe the entire interaction, not events that occur within an interaction such as a purchase. For example, if a contact visits a particular shoe store, interaction facets might include:
-
Means of transportation to store
-
Active store offers at time of visit
-
Weather during visit
-
ID of manager on duty during visit
Facet types
There are two categories of facets - value facets and calculated facets. The only difference between the two categories of facets is that calculated facets are associated with a handler in the xConnect service layer.
Value facets
Value facets can be applied to contacts or interactions, and can be set by any client using the xConnect Client API. Most contact facets and all interaction facets fall into this category. Sitecore contains a number of built-in facets which you can reference in your own model.
Calculated facets
Calculated facets are exclusive to contacts. A calculated facet represents data that is inferred from a contact’s interaction history - for example, a contact’s average engagement value per visit. Calculated facets are updated by the xConnect service layer each time an interaction with relevant data is submitted, and can be retrieved using the xConnect Client API in the same way as value facets. The key behavior cache and contact behavior profile are examples of built-in calculated facets.
The following topics provide more information about calculated facets:
Facet attributes
You can decorate facets or individual facet properties with the following attributes:
-
[DoNotIndex]- Facets or facet properties decorated with this attribute are not indexed and are therefore not searchable. Use this for data that you are not interested in searching - such as binary data. -
[PIISensitive]- Contact facets or contact facet properties decorated with this attribute are not indexed (and is therefore not searchable). Data marked with this attribute should not be written to disk, sent to an external system, or exposed in any way.
Your model will not pass validation if you try to decorate an interaction facet with the [PIISensitive] attribute. Do not store sensitive data in an interaction.
In addition, it is possible to decorate facets properties with the [ExpandDate] (DateTime) attribute. This is a type-specific attribute and it allows you to search DateTime facet properties by day, month, and year rather than the entire date value (Solr only, Sitecore 10.0 and later).
Indexing custom facets
Custom contact and interaction facets are added automatically to the xDB index. Facets are indexed but not stored. Facet data is excluded from the xDB index in the following scenarios:
-
Contact facets or facet properties marked
[PIISensitive]are not indexed if indexing of facets marked[PIISensitive]is disabled. Indexing of[PIISensitive]facets is disabled by default. -
Contact and interaction facets or facet properties marked
[DoNotIndex]are not indexed.