Contact Merge


The contact merge utility makes it possible for you to easily merge duplicate contacts into one contact record. In this article, we will describe how the utility works, and we will also look at several use case scenarios for how you can take advantage of the contact merge utility in practice.

Granting Privileges

To grant contact merge utility privileges to a user follow these steps:

  • Locate "System" from the top menu and select "Maintain Users Accounts"
  • Select the user's name for editing.
  • Select the CRM module
  • Grant the user the "MergeContacts" privilege.


After you have completed the steps above, be sure to save your changes and restart the application.

Note: Re-scanning privileges will not be sufficient. You must restart the application.

Selecting Contacts to Merge

In order to merge contacts we must learn how to use the "Contact Merge Utility." To open this window, follow these steps:

  • Navigate to "CRM" from the top menu
  • Select "Utilities" from the submenu and choose "Merge Contacts"
  • Click "Query" to produce a list of all contacts in your xTuple system.
  • This list can be narrowed down by entering search criteria in the "Search for" box.

Note: The search text box supports xTuple advanced Pattern Matching capabilities.

  • Right-click on any contact
  • Select "Set as Target" to select the contact you want all other selected contacts to be merged into 


Selecting a target contact should turn the selected contact green. It should also populate the "Target Contact" cluster on the "Selections" tab, as shown in the next screenshot:


Once the target contact has been identified and marked, return to the Return to the "Contacts" box and follow these steps:

  • Right-click on another contact
  • Select "Set as Source" to select a contact to be merged into the target contact

Selecting the source contact should cause the contact to turn blue on the "Contacts" tab. It should also appear on the "Contact Sources" list on the "Selections" tab, as demonstrated in the following screenshot:


When you are finally ready to process the merge, all references to the source contacts will be re-pointed to the target contact including but not limited to the following:

  • Contact Comments
  • Incidents
  • Customer Billing and Correspondence
  • Customer Ship-to Addresses
  • Quotes
  • Sales Orders
  • Vendor
  • Site

Note: Quotes and sales orders are special cases where an entire copy of a contact detail is retained on the order header. The merge will replace the internal reference pointer to that of the new target contact, but it will leave the original contact data elements such as name, phone numbers and e-mail on the order as they were at the time that order was entered.

As a convenience you can jump to the contact editing screen by double-clicking on any contact, or right-clicking and selecting "to edit" or "view":


In addition to contact references described above, specific data elements of a source contact may also be carried over to the merged contact, including the notes, phone numbers, or e-mail addresses associated with the contact. To select these elements, follow these steps:

  • Click on the "Selections" tab
  • Right click on any of the cells on the source contact's list
  • Choose to merge that cell to the source
  • Notice that the cell's contents will turn blue once selected.


Info: The "Contact Merge Utility" completely refreshes its results lists every time a contact or cell selection is made. If your database contains many thousands of contacts it may take a few seconds for the screen to regenerate after each selection. In this case, it may be a good idea to use the search to limit your selection results. For example, you might want to start with a search for all contacts whose last names begin with "A"  (pattern match would be: ^A).

Processing Selections

After you have made your selections, click the "Merge" button to merge the source contacts to the target contact. The source contacts will turn orange, indicating they have been successfully merged. Observe that merged contacts are also automatically deactivated. After merging you may right-click on any of the merged contacts and choose to either "Purge" (which completely deletes the contact) or "Restore" (which reverts source contact's relationships and target contact's data elements back to their previous state).

Note: If new references are added to a merged contact, such as a new comment or link to an incident record, the merged contact will turn red to indicate that it has been merged but may not be purged until it is subsequently re-merged with another contact.


Alternate Modes

Multiple modes are available to expedite processing that operate as follows:

  • Merge: Allows user to query contacts using specified search criteria. Merges all source contact selections when "Merge" is clicked.
  • Purge: Displays all merged contacts. Purges all merged contacts at once when "Purge" is clicked.
  • Merge and Purge: Allows user to query contacts using specified search criteria. Merges and purges source contacts in one step when "Merge and Purge" is clicked.
  • Restore: Displays all merged contacts. Restores all merged contacts at once when "Restore" is clicked.


Duplicate Filtering

To help expedite the process of merging contacts, you can check the "Find duplicates with matching criteria" check box. This will filter out contacts that have non-blank and exactly matching data according to criteria selections checked in that group. Duplicates found will be presented in an indented hierarchy with the duplicated element displayed in upper case on the parent row and matching child contact records indented beneath. The example below shows the results of a search for contacts with duplicate e-mail addresses:


Additional Columns Available

Several other contact columns are available for additional flexibility when making selection decisions. Simply right-click on the column headings and check the column or columns you wish to make visible. Also note that these same columns are available on the "Selections" tab, most of which may be selected for merging into the target contact.