Deduplication rules

A deduplication rule tells xMatix which records count as likely duplicates of each other for one entity — for example, "two accounts with the same email or the same phone number". The rules feed the Duplicates panel on a record page: when a user opens an account, a case or a lead, the panel lists the other records the rules match, and the user can compare and merge them. Rules only find candidates. They never stop a record from being saved or imported, and they never merge anything on their own.

Overview

You keep the rules on one screen, Setup → Feature Hub → Platform → Deduplication rules. Each rule belongs to one entity, has a name, and holds one or more conditions. A condition names a field of that entity and a way of comparing it: exact match, case-insensitive, first or last N characters, starts with, or contains. The rule's Match when setting decides whether one condition is enough (Any condition matches (OR)) or whether every condition must hold (All conditions match (AND)).

An entity can have several active rules. xMatix runs each one and lists the records any of them found, with each record shown once.

When to use it

• Your users see too many records in the Duplicates panel that are only related, not the same — for example, every case of the same customer. A rule lets you match on the fields that really identify a duplicate.
• Your users miss real duplicates, because your duplicates share a field the built-in matching does not look at, such as a GST number, a registration number or a customer code.
• You want near-matches — names with the same first characters, or phone numbers with the same last digits.

How xMatix handles it

• Rules replace the built-in matching. As long as an entity has at least one active rule, the panel uses only the rules. Without an active rule, xMatix uses its built-in matching for that entity:
  • Case — open cases (status other than Closed, not merged away) with the same contact, the same account or the same contact number.
  • Lead — leads that are not Lost or Converted, with the same email (ignoring capitals), the same phone number or the same contact.
  • Asset — assets with the same serial (chassis) number or the same registration number, ignoring spaces, dashes, slashes, dots and capitals. Assets do not show the Duplicates panel out of the box; see Turn on duplicate detection for another entity.
  • Every other entity, Account included — records that share any identity field the entity has: external ID, code, reference number, registration number, tax ID, email or phone number.
• Matching runs when the panel searches. The Duplicates panel searches when the record opens and when the user clicks Refresh in the panel. Nothing is checked when a record is saved, imported or created through the API.
• What is never offered. The record itself, deleted records and records already merged into another record never appear. Rules also respect the entity's own end states: closed cases, and leads that are Lost, Converted or already have an opportunity, are left out even when a rule matches them.
• At most 25 candidates. One search returns no more than 25 records in total, shared across all active rules of the entity. Each rule lists its matches newest first.
• The panel says why. With one rule, the panel's subtitle shows the rule's name and the values it searched with, such as Same email or phone a.rao@example.com · 98450 12345. With several rules, it counts the matches per rule, and each listed record carries the name of the rule that found it.
• Only active rules count. Turning a rule off takes it out of matching straight away. When the last active rule of an entity is turned off, the built-in matching comes back.

Prerequisites

• Permission to create and edit Duplicate Rule and Duplicate Rule Condition records on your security profile. See Permissions.
• The entity's record page must show the Duplicates panel, otherwise nobody sees what your rules find. The shipped record pages for Account, Case and Lead have it. For any other entity, see Turn on duplicate detection for another entity.
• The names of the fields your duplicates share. Open a few known duplicate records and compare them before you write the rule.

Procedure

Step 1 — Open the rules for an entity

1. Go to Setup → Feature Hub → Platform → Deduplication rules.
2. In the Entity picker above the table, choose the entity — for example Account. The screen opens on Case.

The table title changes to Account rules and lists the rules for that entity with their Rule name, Match logic, Description and an Active switch. Use the search box to filter by name or description.

Step 2 — Create a rule

1. Click New rule in the page header. The New duplicate rule dialog opens.
2. Enter a Rule name. Users see this name in the Duplicates panel, so make it say what matched — for example Same email or phone.
3. Optionally enter a Description.
4. Under Match when, choose Any condition matches (OR) or All conditions match (AND).
5. Add the conditions (step 3).
6. Leave Active on, or turn it off to save the rule without using it yet.
7. Click Save.

You see Rule created, and the rule appears in the table. The next time a user opens a record of that entity, the Duplicates panel uses it.

Step 3 — Add the conditions

The dialog starts with one condition row. For each row:

1. Pick the Field. The list shows the entity's fields by label. Fields that link to another record carry a Lookup tag.
2. Pick the match method (see Match methods).
3. For First N characters or Last N characters, set the number of characters (1 to 20). For Starts with or Contains, you can type a value — read what that does under Match methods first.

Click Add for another row. Use the delete button at the end of a row to remove it; the last row cannot be removed.

If the rule is likely to list records that are not duplicates, a warning appears under the conditions: This rule will probably return records that are not duplicates. It explains which condition is the problem. You can still save — see Business rules for when the warning matters.

Step 4 — Test the rule

1. Open a record of the entity that you know has a duplicate.
2. Look at the Duplicates panel (the Duplicates tab on the shipped Account and Case pages). Click Refresh in the panel if the record was already open.
3. Check that the known duplicate is listed and that the subtitle names your rule.

If the panel lists unrelated records, tighten the rule — usually by switching to All conditions match (AND) or adding an identifying field. If it lists nothing, see Common problems.

Step 5 — Change a rule

1. Click the rule's name, or the Edit rule button in its row. The Edit duplicate rule dialog opens with the rule's current conditions.
2. Change what you need and click Save.

You see Rule updated. xMatix saves the conditions as you left them in the dialog, replacing the previous set.

Step 6 — Turn a rule off or delete it

• To stop using a rule but keep it, turn off its Active switch in the table. The change is saved at once.
• To remove a rule, click Delete rule in its row and confirm Delete this rule? with Delete. You see Rule deleted.

When no active rule is left for the entity, the Duplicates panel goes back to the built-in matching.

Turn on duplicate detection for another entity

The duplicate search and merge are not limited to accounts, cases and leads, but every other entity has to be switched on by an administrator:

1. Add three server actions to the entity, each with the same value in its name and its server action name: FindDuplicates, Merge and FindMerged. See Entity behaviour — Actions.
2. Give the security profiles that should use them permission to run the three actions. See Security profiles.
3. Add the DeDuplicate Widget (palette group Generic Components) to the entity's record page layout. See Design a form layout.
4. Write a rule for the entity as above. Without one, the entity uses its built-in matching — for most entities the generic matching on identity fields, which finds nothing if the entity has none of them.

A merge on such an entity moves the duplicate's activities, attachments, collaborators, followers and side conversations to the surviving record and records the merge. The duplicate itself keeps its status and stays in list views: only cases (closed with the reason Duplicate) and leads (marked Lost with the reason Duplicate) are given an end state when merged. A merged account keeps its status too.

Fields

The rule

A condition

Match methods

In each description, this record is the record the user has open and the other record is a possible duplicate.

The five text methods apply only to text fields. On a lookup, number, date or yes/no field, every method works as Exact match.

Business rules

• A blank value on the open record. In an Any rule, a condition whose field is empty on the open record is skipped, and the other conditions still run. In an All rule, one empty field means the rule finds nothing for that record.
• Never match on a lookup alone. A lookup — the account, the contact, the customer — says two records are related, not that they are the same. A rule whose only condition, or one of whose Any conditions, is a lookup lists every record linked to the same account or contact: the customer's whole history. The dialog warns about this. A lookup condition is fine in an All rule together with an identifying field such as email, phone or code.
• A typed value turns Starts with and Contains into a filter. With a value typed, the condition no longer compares the two records: it lists every record whose field starts with, or contains, that value, as long as the open record's own field is not empty. Use it only to narrow an All rule — for example, matching names only among records whose code starts with DL. Without a typed value, Contains lists every record whose field contains the open record's whole value, which can still be broad for short values. The dialog warns when Starts with or Contains has no value.
• Rules replace, they do not add. Writing the first active rule for Case or Lead switches off their built-in matching, including its restriction to open records on contact, account or phone. Closed cases and lost or converted leads stay excluded, but everything else the built-in matching did is now up to your rule. Make the rule at least as selective as what it replaces.
• Several rules are combined. Each active rule runs on its own; a record found by two rules is listed once, under the first rule that found it. Rules have no set order, so do not rely on which rule's name a record shows.
• 25 in total. The panel never lists more than 25 candidates for one record, however many rules there are.
• Merging is not undone by a rule change. Records already merged away stay out of the panel even when you change or delete the rule that found them.

Example

An organization sells to retailers and imports its account list from several regional spreadsheets. The same shop often appears twice, once with the phone number written as +91 98450 12345 and once as 98450 12345, and sometimes with a different email.

The administrator opens Setup → Feature Hub → Platform → Deduplication rules, chooses Account and clicks New rule:

• Rule name: Same email
• Match when: Any condition matches (OR)
• Condition: Email, Case-insensitive

A second rule catches the phone-number variants:

• Rule name: Same phone and similar name
• Match when: All conditions match (AND)
• Conditions: Phone, Last N characters, 10; Name, First N characters, 5

When a sales manager opens the account Sharma General Stores, the Duplicates tab lists Sharma General Store (found by Same phone and similar name) and Sharma Genl Stores Pvt (found by Same email). The subtitle reads Same email 1 · Same phone and similar name 1. The manager compares each one, copies the better address to the surviving account, and merges both into it.

Training

Practice exercise

In a sandbox:

1. Create two leads with the same Email — meera@example.com — and different Phone Number values.
2. Open the first lead. With no rule for Lead, the Duplicates panel lists the second one, because the built-in lead matching compares email.
3. In Deduplication rules, choose Lead and create the rule Same phone with one condition: Phone Number, Exact match. Open the first lead again and click Refresh in the panel.
4. Edit the rule, add a second condition — Email, Case-insensitive — keep Any condition matches (OR), save, and refresh the panel again.

Expected result: at step 2 the second lead is listed. At step 3 it disappears, because the rule replaced the built-in matching and the phone numbers differ. At step 4 it is listed again, with Same phone and the searched values in the panel's subtitle. Finally, turn the rule off: the built-in matching comes back.

Quick reference

• Rules live at Setup → Feature Hub → Platform → Deduplication rules, one entity at a time.
• Rules find candidates for the Duplicates panel; they never block a save, an import or an API call.
• One active rule switches off the entity's built-in matching.
• Any = one condition is enough; All = every condition must match.
• Never let a lookup alone decide a match; pair it with an identifying field under All.
• A typed value in Starts with / Contains filters on that value instead of comparing the two records.
• At most 25 candidates per record, across all rules.
• Only Account, Case and Lead show the panel out of the box.

Permissions

• Rules. What you can do on the Deduplication rules screen follows your security profile's permissions on the Duplicate Rule and Duplicate Rule Condition entities: create, edit and delete. The screen has no setup capability of its own. The shipped System Admin, Standard User, Sales Manager and Sales Executive profiles have full access to both entities, so a user on one of these profiles who can reach the screen can change matching for everyone. Remove the access from profiles that should not author rules.
• Using the panel. The Duplicates panel needs permission to run the entity's Find Duplicates action, and merging needs the Merge action. In the shipped profiles, Find Duplicates is granted on Case and Lead to System Admin, Standard User, Sales Manager and Sales Executive, and on Account to System Admin, Standard User and Sales Manager. See Security profiles.

Configuration

Common problems

The Duplicates panel is empty since I added a rule

An active rule replaces the built-in matching, even when it finds nothing. Check that:

• the open record has a value in the rule's fields — under All conditions match (AND), one empty field makes the rule find nothing;
• the duplicates really share those values in the way the match method compares them — open a known duplicate and compare the fields side by side;
• the rule's fields are standard fields of the entity. A field you added to a standard entity yourself is skipped, so a rule built only on such fields finds nothing.

Turn the rule off to confirm: the built-in matching comes back.

The panel lists every record of the same customer

A condition compares a lookup — the account, the contact, the customer — under Any condition matches (OR). Records linked to the same customer are related, not duplicates. Remove that condition, or switch to All conditions match (AND) and add an identifying field such as email, phone or code.

The panel lists records that only share a word

A Contains or Starts with condition matches broadly — either it has a typed value, which lists every record whose field contains or starts with that value, or the open record's value is short. Use Exact match, Case-insensitive or First N characters, or combine the condition with an identifying field under All.

"Give the rule a name" or "Add at least one field condition"

The dialog does not save a rule without a Rule name, or without at least one condition that has a Field picked. Fill them in and click Save again.

A rule does not stop users from saving a duplicate

That is expected. Rules only list candidates in the Duplicates panel. Nothing in xMatix blocks a save or an import because of a duplicate rule.

I cannot find the Duplicates panel on my entity

Only the shipped Account, Case and Lead record pages have it. Follow Turn on duplicate detection for another entity.

Common questions

Do rules check records when they are imported?

No. Rules are used only when the Duplicates panel searches on an open record. The import wizard creates or updates records on its own keys — the record's ID or its external ID — and never consults the rules. To clean up after an import, open the imported records and merge the duplicates the panel lists. See Import data.

Can a rule merge duplicates automatically?

No. A rule only decides which records are offered. A user always chooses which records to merge, from the Duplicates panel, and confirms the merge. Merging moves the duplicate's activities, attachments, collaborators, followers and side conversations to the surviving record; it does not copy field values, so copy anything you want to keep before you merge. A merge cannot be undone.

What happens to my rules if I relabel a field?

Nothing. A condition stores the field's name, not its label, so changing the label a user sees does not affect matching. The rule dialog simply shows the new label the next time you open it.

Can I have rules for the same entity that use different logic?

Yes. Each rule has its own Match when setting, and all active rules of the entity run. A common pattern is one strict Any rule on strong identifiers — tax ID, registration number, code — and a second All rule that pairs a near-match on the name with an exact or last-digits match on the phone.

Related topics

• Collaborate on cases — finding and merging duplicate cases.
• Leads and Accounts — the record pages with the Duplicates panel.
• Support configuration reference
• Import data
• Security profiles
• Duplicate Rule — entity reference