---
title: "Create a facet merge handler"
slug: "create-a-facet-merge-handler"
abstract: ""
---
# Create a facet merge handler

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](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-platform/calculated-facets.html "Calculated facets"). 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

```csharp
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.

```csharp
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:

    ```xml
    <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](https://doc.sitecore.com/xp/en/developers/103/sitecore-experience-platform/merge-contacts.html "Merge contacts") to test a merge handler.