Sitecore Experience Platform

Calculated facets

A calculated facet is updated by the xConnect service layer each time a new interaction is submitted. The purpose of a calculated facet is to make inferred data about a contact’s interaction history accessible in a performant way. Usages of calculated facets include:

  • Increment or decrement a number, such as a contact’s average spend per interaction

  • Store a minimum / maximum value

  • Store a list of recent events

  • Store a histogram (for instance, a list of interaction locations and total number of visits from that location)

  • Store a heat map

Every calculated facet consists of:

  • A facet class. There is nothing within the facet class that distinguishes a calculated facet from a value facet.

  • A calculated facet handler, which is configured in the xConnect service layer.

Calculated facets will retry automatically

If a conflict occurs when xConnect attempts to save a calculated facet value, the operation will retry automatically.

Calculated facet handlers cannot access contact data

Calculated facet handlers do not have access to the contact object or contact facets. If a calculation relies on a contact facet and that facet changes, rebuilding the calculated facet will produce inconsistent results. Store any data that is required by a calculation as an event or as an interaction facet.

Note

It is currently not possible to rebuild calculated facets.

Recommended practices

Keep the following recommended practices in mind when implementing a calculated facet.

Use calculated facets sparingly

Calculated facet plugins execute every time an interaction is submitted to xConnect. If the functionality is overused, it can have a detrimental effect on the performance of the entire system. Keep the following in mind when implementing a calculated facet:

  • Use calculated facet functionality sparingly.

  • If a calculation cannot occur if another facet is not available, ensure that you set the Required property on the Sitecore.XConnect.Service.InteractionFacetDependency object to true.

  • Exit the calculation as quickly as possible - if an interaction must meet certain conditions in order to affect the facet value, check those first. If the interaction does not qualify, return false.

Do not set calculated facet properties manually

Do not update calculated facets manually using the xConnect Client API. When calculated facets are rebuilt from the contact’s history, manual changes will be lost.

A facet should either be calculated or not calculated

Do not mix calculated properties and value properties within the same facet. For example, the AverageSpend facet should only be updated by the AverageSpendHandler.