When the xDB contains more than one contact record describing the same person, you can merge contact records. All the information stored in these contact records merge into one record. The old contact record is removed and replaced with a reference to the updated contact record, so that all future operations can access the updated and consolidated information.
If you create custom contact facets using the ContactEntity API or have implemented any other customizations on the contact then you need to overwrite the merging logic to ensure that the data for any custom facets is merged correctly. Custom contact facets may include data that you want to merge which is specific to your organization or solution.
To customize the merging logic, you need to add a new processor to the
When you merge contacts
Sitecore invokes the merge pipeline when:
- An unidentified contact is identified as a contact already known in the system. The contact records are merged, as part of the contact identification process.
- The system has been operating without an xDB connection. For example, due to network or configuration problems. In this situation Sitecore will attempt to merge collected behavior and personal information into the primary contact record in xDB. Merging is used as a way of recovering from database or network issues.
How contacts are merged
The merge operation is performed on two contact records: source record and target record. After the merge operation has completed, the target record is updated in xDB with the new information, and the source record is obsoleted removing all information related to it from the xDB.
MergeContactArgs provides you with the following two properties to implement this:
A reference to the contact record that will be removed after the merge. This is the source of the contact information to be merged.
A reference to the contact record that will be kept in the xDB after the merge. This is the target of the contact information to be merged.
The merge pipeline contains a predefined set of processors that implement the default merge contact rules.
Merge custom contact facets using a custom processor
If you have created custom contact facets, you can also create custom processors using the
MergeContact pipeline to merge your custom contact facets.
To create a custom merge:
- Create a class that is derived from the
MergeContactProcessorclass in the
Sitecore.Analytics.Pipelines.MergeContactsnamespace and override the
void Process(MergeContactArgs args)method.
public class CustomMergeLogic : MergeContactProcessor
public override void Process(MergeContactArgs args)
// TODO: Use args.DyingContact and args.SurvivingContact
// TODO: write into args.SurvivingContact
- In the
void Process(MergeContactArgs args)method use the properties
args.SurvivingContactto access the contact records that you want to merge.
- Assign the merged values to
args.SurvivingContact. All the information in
args.DyingContactwill be lost after the merge.
- Add your custom processor to the
mergeContactspipeline. The processor in this example is called
<processor type="CustomCode.CustomMergeLogic" />
The merge pipeline is invoked synchronously as part of each HTTP request. Therefore, any customizations that you add to the pipeline should avoid long running operations and requests to databases and third-party systems.