Create a facet merge handler

Current version: 9.2

A facet merge handler determines what should happen to a particular facet when two contacts are merged. Facet merge handlers are configured on the xConnect Collection service and are executed when a merge operation is submitted.

Important

All value facets are merged automatically - you do not have to create your own handler for every custom facet unless you want to override default behavior.

You should create your own merge handler when:

  • You have created a calculated facet. Calculated facets are not merged automatically.

  • You want to merge a particular facet in a way that differs from the default - for example, you may want the source value to always overwrite the target value.

Create a value facet

RequestResponse
using Sitecore.XConnect;

namespace Documentation
{
    public class CyclistProfile : Facet
    {
        public string BikeBrand { get; set; }
        public string StravaID { get; set; }
        public string NumberOfBikeRides { get; set; }
    }
}

Implement a merge handler

Implement a MergingCalculatedFacetHandler as shown.

Note

Return false from the UpdateFacet() method. This method is only used for calculated facet calculations.

RequestResponse
using Sitecore.ContentTesting.Collection.Model.Plugins.Utils;
using Sitecore.ContentTesting.Model.xConnect;
using Sitecore.XConnect;
using Sitecore.XConnect.Service;

namespace Sitecore.Documentation.Plugins
{
    /// <summary>
    /// A processor to merge custom facet handler
    /// </summary>
    public class MergeCustomFacetHandler : MergingCalculatedFacetHandler<CyclistProfile>
    {
        public MergeCustomFacetHandler() : base("CyclistProfile", null)
        {
        }

        protected override bool UpdateFacet(CyclistProfile currentFacet, Interaction interaction)
        {
            // For calculated facets only
            // Return false as contact not changed by this method
            return false;
        }

        protected override bool Merge(CyclistProfile source, CyclistProfile target)
        {
            if (source == null || target == null)
            {
                // No contacts changed - return false
                return false;
            }

            // Add source and target values together
            target.NumberOfBikeRides += source.NumberOfBikeRides;

            // Return true if contact was changed
            return true;
        }
    }
}

Configure facet merge handler

  1. Create a file named sc.CustomPlugins.xml in c:\path_to_xconnect\root\App_data\config\sitecore\Collection\.

  2. Paste the following configuration, substituting the highlighted lines with your own handler:

    RequestResponse
    <Settings>
    <Sitecore>
        <XConnect>
            <Collection>
                <Services>
                    <IContactMergeHandler.MergeTestCombinationsHandler>
                        <Type>Sitecore.Documentation.Plugins.MergeCustomFacetHandler, Sitecore.Documentation</Type>
                        <As>Sitecore.XConnect.Service.IContactMergeHandler, Sitecore.XConnect.Service</As>
                        <LifeTime>Singleton</LifeTime>
                    </IContactMergeHandler.MergeTestCombinationsHandler>
                </Services>
            </Collection>
        </XConnect>
    </Sitecore>
</Settings>

  3. Copy the sc.CustomPlugins.xml file to all xConnect Collection and Search instances.

    Note

    Default merge facet handlers are configured in the c:\path\toxconnect\root\App_data\config\sitecore\Collection\sc.XConnect.Collection.Model.Plugins.xml file.

Contact merge and the tracker

Contact merge is owned by xConnect and called by the tracker when an anonymous contact identifes themselves as a contat that already exists. You can use the xConnect Client API to test a merge handler.

Do you have some feedback for us?

If you have suggestions for improving this article,