DuplicateRule

Represents a rule that specifies how duplicate records in an object are detected.

This type extends Metadata and inherits its fields.

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.

DuplicateRule components are available in API version 68.0 and later.

• Type: DupeActionType (enumeration of type string)

• Required: Yes

• Description: 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.

• Type: DupeActionType (enumeration of type string)

• Required: Yes

• Description: 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.

• Type: string

• Required: Yes

• Description: 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.

• Type: string
• Required: Yes
• Description: Required. Text that describes the duplicate rule. The value is customer-supplied, but isn’t visible in the UI.

• Type: DuplicateRuleFilter
• Required: Yes
• Description: 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.

• Type: DuplicateRuleMatchRule[]
• Required: No
• Description: Required. One or more MatchingRule components for the DuplicateRule. A MatchingRule controls what constitutes a match between records.

• Type: boolean
• Required: Yes
• Description: Required. If true, the DuplicateRule detects duplicate records. Otherwise, the rule has no effect.

• Type: string
• Required: Yes
• Description: Required. Label for this DuplicateRule. This value is the internal label for the rule.

• Type: string[]

• Required: No

• Description: 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.

• Type: string[]

• Required: No

• Description: 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.

• Type: DupeSecurityOptionType (enumeration of type string)

• Required: Yes

• Description: 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.

• Type: int
• Required: Yes
• Description: Required. Determines the order in which duplicate rules are applied.

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

• Type: string
• Required: Yes
• Description: Required. A string of boolean operators that establishes the filter logic for the filter items specified in duplicateRuleFilterItems.

• Type: DuplicateRuleFilterItem[]
• Required: No
• Description: Required. A list of DuplicateRuleFilterItem components.

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

This type extends FilterItem and inherits its fields.

• Type: int
• Required: Yes
• Description: Required. The order of this item in the duplicate rule filter.

• Type: string
• Required: Yes
• Description: Required. The object that has the field specified in the field field of DuplicateRuleFilterItem. See the documentation for FilterItem for the definition of field.

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

• Type: string
• Required: Yes
• Description: Required. Value that corresponds to the value of developerName in the MatchingRule for this duplicate rule.

• Type: string
• Required: Yes
• Description: 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.

• Type: ObjectMapping
• Required: Yes
• Description: Required. Foreign key to an ObjectMapping that maps fields from the duplicate rule’s object to fields in the target object specified by matchRuleSObjectType.

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.

• Type: string
• Required: Yes
• Description: 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.

• Type: ObjectMappingField[]
• Required: No
• Description: Required. The mapping of source object fields to target object fields for the duplicate rule.

• Type: string
• Required: Yes
• Description: 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.

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

• Type: string
• Required: Yes
• Description: 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.

• Type: string
• Required: Yes
• Description: 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.

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>

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.