Create a contact processor

Version: 10.4

This topic demonstrates how to create and register your own contact processor.

Inherit ContactProcessingProcessor

All contact processors inherit from Sitecore.Analytics.Aggregation.Pipeline.ContactProcessingProcessor:

RequestResponse
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
    }
}

Specify contact facets to retrieve

The processing pipeline uses the xConnect Client API to retrieve contacts. You must specify which contact facets to retrieve by decorating your processor with UsesContactFacets.

Example of usage:

RequestResponse
[UsesContactFacets("Personal", "Classification")]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
    }
}

It is recommended that you do not hard-code facet keys - Sitecore’s built-in facet names are located on the facet object itself - such as PersonalInformation.DefaultFacetKey.

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
}
Important

If you do not explicitly request a particular facet, it will not be available during processing. To understand why, read more about the role of expand options when getting contacts.

Using ContactProcessingArgs

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
    }
}

Accessing the contact

The contact is available directly on the args:

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
        var contact = args.Contact;
    }
}

If you requested any contact facets, they can be accessed via the .GetFacet<T> extension method:

RequestResponse
var personalFacet = args.Contact.GetFacet<PersonalInformation>(PersonalInformation.DefaultFacetKey);

Alternatively, use the extension methods found in Sitecore.XConnect.Collection.Model:

RequestResponse
var personalFacet = args.Contact.Personal();

Access processing reason

The args.ProcessingReason property returns an enum of type Sitecore.Analytics.Processing.ProcessingReason, which tells you why the contact is being processed in the first place.

  • Created: The contact is new

  • Updated: The contact was updated

  • Obsoleted: The contact identifier has been obsoleted

  • Unknown: Reason for processing is unknown

Accessing other APIs

Every processor has access to the following APIs via args.Sources:

  • xConnect Client API

  • Reference Data Service

  • Defintion managers

  • Taxonomy managers

Important

In the context of a contact processor, all service end points - xConnect, definitions, taxonomy, and the reference data service - should be treated as read-only.

Accessing xConnect

A read-only instance of the xConnect Client API is accessed via args.Sources.Collection. You can search or get contact data:

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
        // Searching
        var contacts = args.Sources.Collection.Contacts.Where(x => x.Identifiers.Any(c => c.IdentifierType == ContactIdentifierType.Known));
    }
}
Note

Remember that the contact is available via args.Contact.

Accessing definition managers

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
        var goalManager = args.Sources.Definitions.GetDefinitionManager<IGoalDefinition>();
    }
}

Accessing taxonomy managers

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
        var assetTaxonomyManager = args.Sources.Taxonomies.GetManager<AssetTaxonomyManager>();
    }
}

Accessing the reference data service

RequestResponse
[UsesContactFacets(PersonalInformation.DefaultFacetKey, Classification.DefaultFacetKey)]
public class SampleProcessor : ContactProcessingProcessor
{
    protected override void OnProcess(ContactProcessingArgs args)
    {
        var definitionType = args.Sources.Reference.EnsureDefinitionType("alpha");
        var criteria = new DefinitionCriteria("enterprise", definitionType)
        {
            Culture = new CultureInfo("da")
        };

        Definition<string, string> definition = args.Sources.Reference.GetDefinition<string, string>(criteria, true);
    }
}
Note

The contact processing pipeline uses a read only version of the reference data service API - it does not use the client API.

Configuring a contact processor

Add your processor to the contact processing pipeline as shown:

RequestResponse
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <sitecore>
<pipelines>
  <group groupName="analytics.aggregation">
    <pipelines>
      <contacts>
        <processor type="Sitecore.Analytics.Aggregation.Tests.Processors.FakeContactProcessingProcessor, Sitecore.Analytics.Aggregation.Tests" />
      </contacts>
    </pipelines>
  </group>
</pipelines>
    </sitecore>
</configuration>

Do you have some feedback for us?

If you have suggestions for improving this article,