Create a facet merge handler

Current version: 9.0

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.


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

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.


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

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:

                            <Type>Sitecore.Documentation.Plugins.MergeCustomFacetHandler, Sitecore.Documentation</Type>
                            <As>Sitecore.XConnect.Service.IContactMergeHandler, Sitecore.XConnect.Service</As>
  3. Copy the sc.CustomPlugins.xml file to all xConnect Collection and Search instances.


    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,