DuplicateRule | Metadata API Developer Guide

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

File Suffix and Directory Location

DuplicateRule components have the .duplicateRule suffix and are stored in the duplicateRules/ directory. The name of the component file is based on the name of the object associated with the rule. For example, the component file name duplicateRules/Account.Standard_Account_Duplicate_Rule.duplicateRule describes a duplicate rule component associated with the Account object.

Version

DuplicateRule components are available in API version 66.0 and later.

Fields

Field Name	Field Type	Description
actionOnInsert	DupeActionType (enumeration of type string)	Required. Determines what the duplicate rule does when users or the DuplicateRule API try to insert a record that is a duplicate. Valid values are: `Allow` For users, if operationsOnInsert is set to `alert`, the UI displays the value of alertText in a dialog. The dialog prompts users to continue or cancel. If the user chooses to continue, the insertion proceeds. If the user chooses to cancel, the record isn’t inserted. The DuplicateRule API returns an error code and a message. To complete the insertion, the code must set the allowSave field in DuplicateRuleHeader to `true` and reissue the request. If operationsOnInsertisn’t set to `alert`, the UI inserts the record without issuing an alert. The API inserts the record and doesn’t return an error code. `Block` For users, the UI displays an error message and prevents them from inserting the new record. The DuplicateRule API returns an error and doesn’t insert the record.
actionOnUpdate	DupeActionType (enumeration of type string)	Required. Determines what the duplicate rule does when users or the DuplicateRule API try to update a record, and the result is a duplicate. Valid values are: `Allow` For users, if operationsOnUpdate is set to `alert`, the UI displays the value of alertText in a dialog. The dialog prompts users to continue or cancel. If the user chooses to continue, the update proceeds. If the user chooses to cancel, the record isn’t updated. The DuplicateRule API returns a message. To complete the update, the code must set the allowSave field in DuplicateRuleHeader to `true` and reissue the request. If operationsOnUpdateisn’t set to `alert`, the UI updates the record without issuing an alert. The API updates the record and doesn’t return an error code. `Block` For users, the UI displays an error message and prevents them from continuing. The DuplicateRule API returns an error.
alertText	string	Text that’s sent when the duplicate rule is triggered. The text is only sent if isActive is `true`. In the UI, the text displays as a message. The DuplicateRule API returns the message in its response. You can set a value for alertText only when you have actionOnInsert or actionOnUpdate (or both) set to `Allow`. Otherwise, you receive a validation error when you add or update this component.
description	string	Required. Text that describes the duplicate rule. The value is customer-supplied, but isn’t visible in the UI.
duplicateRuleFilter	DuplicateRuleFilter	Required. Criteria that define how to find records to consider when looking for duplicates. For example, use duplicateRuleFilter to exclude records from the match when looking for duplicates.
duplicateRuleMatchRules	DuplicateRuleMatchRule[]	Required. One or more MatchingRule components for the DuplicateRule. A `MatchingRule` controls what constitutes a match between records.
isActive	boolean	Required. If `true`, the DuplicateRule detects duplicate records. Otherwise, the rule has no effect.
masterLabel	string	Required. Label for this DuplicateRule. This value is the internal label for the rule.
operationsOnInsert	string[]	Required. Controls the action to take when actionOnInsert is set to `Allow` and the duplicate rule is triggered. Either one or both of these values can be set in the array: `alert` If set, the action specified in actionOnInsert occurs; otherwise, the insert proceeds. `report` If set, the insert operation is added to the report of duplicates.
operationsOnUpdate	string[]	Required. Controls the action to take when actionOnUpdate is set to `Allow` and the duplicate rule is triggered. Either one or both of these values can be set in the array: `alert` If set, the action specified in actionOnUpdate occurs; otherwise, the update proceeds. `report` If set, the update operation is added to the report of duplicates.
securityOption	DupeSecurityOptionType (enumeration of type string)	Required. Determines how record sharing rules affect duplicate management. Valid values are: `EnforceSharingRules` Sharing rules affect duplicate management. If a duplicate rule is triggered because an insert or update duplicates an existing record, but the running user doesn’t have sharing access to that record, the insert or update proceeds. The sharing rule doesn’t prevent the user from creating or updating the record because the record is hidden from the user. No message is issued. `BypassSharingRules` Sharing rules don’t affect duplicate management. If a duplicate rule is triggered because an insert or update duplicates an existing record, sharing rules are ignored, but other access restrictions apply.
sortOrder	int	Required. Determines the order in which duplicate rules are applied.

DuplicateRuleMatchRule

Describes the MatchingRule associated with the DuplicateRule. The MatchingRule identifies duplicate records.

Field Name	Field Type	Description
matchRuleSObjectType	string	Required. The name of the target object of the matching rule. For example, if you define a duplicate rule for Contact records, and you want to match with Lead records, the value of matchRuleSObjectType is Lead.
matchingRule	string	Required. Value that corresponds to the value of developerName in the MatchingRule for this duplicate rule.
objectMapping	ObjectMapping	Required. Foreign key to an ObjectMapping that maps fields from the duplicate rule’s object to fields in the target object specified by matchRuleSObjectType.

DuplicateRuleFilter

Specifies filter criteria for a DuplicateRule. Salesforce only applies the DuplicateRule if the record matches the criteria.

Field Name	Field Type	Description
booleanFilter	string	Required. A string of boolean operators that establishes the filter logic for the filter items specified in duplicateRuleFilterItems.
duplicateRuleFilterItems	DuplicateRuleFilterItem[]	Required. A list of DuplicateRuleFilterItem components.

DuplicateRuleFilterItem

This type extends the FilterItem type and inherits all its fields.

Field Name	Field Type	Description
sortOrder	int	Required. The order of this item in the duplicate rule filter.
table	string	Required. The object that has the field specified in the field field of DuplicateRuleFilterItem. See the documentation for FilterItem for the definition of field.

ObjectMapping

Represents a map of fields in the input object of the DuplicateRule to fields in the output object of DuplicateRule. The input object is the object associated with the DuplicateRule. The output object can be the same object or a different object with similar fields.

For example, you can have a DuplicateRule that looks for duplicates between the Contact object and the Lead object. In this case, the input object is Contact, and the output object is Lead.

Field Name	Field Type	Description
inputObject	string	Required. The input object for the duplicate rule. The DuplicateRule is associated with this object. For example, if you define a duplicate rule for Contact records, and you want to match with Lead records, the value of inputObject is Contact.
mappingFields	ObjectMappingField[]	Required. The mapping of source object fields to target object fields for the duplicate rule.
outputObject	string	Required. The output object for the duplicate rule. This value is the same as the value of the matchRuleSObjectType field in DuplicateRuleMatchRule. Any duplicate rules that this object has are ignored when the DuplicateRule API uses the ObjectMapping.

ObjectMappingField

A field name in the input object of the DuplicateRule, and the corresponding field name in the output object.

Field Name	Field Type	Description
inputField	string	Required. Field in the object specified by the inputObject field in ObjectMapping. This field is mapped to the field in outputField, which is assumed to be a field in the object specified by the outputObject field in ObjectMapping.
outputField	string	Required. Field in the object specified by the outputObject field in ObjectMapping. The field is mapped to the field name in inputField, which is assumed to be a field in the object specified by the inputObject in ObjectMapping.

Declarative Metadata Sample Definition

The following is an example of a DuplicateRule component.

1<?xml version="1.0" encoding="UTF-8"?>
2<DuplicateRule xmlns="http://soap.sforce.com/2006/04/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3    <actionOnInsert>Allow</actionOnInsert>
4    <actionOnUpdate>Allow</actionOnUpdate>
5    <alertText>You are creating a duplicate record. Use an existing record instead.</alertText>
6    <description>Detects a contact that duplicates a Lead</description>
7    <duplicateRuleFilter>
8        <booleanFilter xsi:nil="true"/>
9        <duplicateRuleFilterItems>
10            <field>Username</field>
11            <operation>equals</operation>
12            <value>user@example.com</value>
13            <sortOrder>1</sortOrder>
14            <table>User</table>
15        </duplicateRuleFilterItems>
16    </duplicateRuleFilter>
17    <duplicateRuleMatchRules>
18        <matchRuleSObjectType>Lead</matchRuleSObjectType>
19        <matchingRule>ContactToLeadDuplicate_matching_rule</matchingRule>
20        <objectMapping>
21            <inputObject>Contact</inputObject>
22            <mappingFields>
23                <inputField>FirstName</inputField>
24                <outputField>FirstName</outputField>
25            </mappingFields>
26            <mappingFields>
27                <inputField>LastName</inputField>
28                <outputField>LastName</outputField>
29            </mappingFields>
30            <outputObject>Lead</outputObject>
31        </objectMapping>
32    </duplicateRuleMatchRules>
33    <isActive>true</isActive>
34    <masterLabel>ContactToLeadDuplicate</masterLabel>
35    <operationsOnInsert>Alert</operationsOnInsert>
36    <operationsOnInsert>Report</operationsOnInsert>
37    <operationsOnUpdate>Alert</operationsOnUpdate>
38    <operationsOnUpdate>Report</operationsOnUpdate>
39    <securityOption>EnforceSharingRules</securityOption>
40    <sortOrder>1</sortOrder>
41</DuplicateRule>

The following is an example package.xml that references the previous definition.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>ContactToLeadDuplicate</members>
5        <name>DuplicateRule</name>
6    </types>
7    <version>38.0</version>
8</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.