Facets

Current version: 9.2

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. Each facet is made up of:

  • A facet model, which is a class that inherits Sitecore.XConnect.Facet.

  • A facet definition, which associates a facet model with a key and assigns it to an entity (either contacts or interactions). Facets are defined in code, in a collection model.

A facet model can be re-used with a different key, or defined with the same key for contacts and then interactions.

Important

Facet keys are case sensitive.

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.

Important

Your model will not pass validation if you try to decorate an interaction facet with the [PIISensitive] attribute. You should not be saving PII sensitive information into an interaction facet.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,