In this blog series, we introduce the wide range of extensions, modules, and other tools SYSTOPIA has developed for CiviCRM users over the years. Today’s about our “matchmaker” XCM – a crucial gear in almost all setups that connect Civi with external sources.
What is this extension about?
The Extended Contact Matcher (XCM) helps identifying existing CiviCRM contacts using data like first name, last name, and email address. This prevents unwanted duplicates when importing or updating contacts. XCM allows you to define rules that determine which contacts are considered duplicates and which fields can be updated.
Who is it for?
Defining rules for contact matching and merging is a problem that occurs in many situations. For instance, when offering self-service forms to update contact information, you would want to check if a contact is already in your system, apply a suitable matching logic and precisely update all relevant information without cluttering your database with duplicates.
The configuration options XCM adds to contact matching makes it a dependency for many other extensions, such as Remote Event, Twingle API, Advanced Newsletter Management or the Self-Service extension. It can be helpful in conjunction with the Form Processor as well.
How do you use it?
You can configure different rule sets for different circumstances by defining multiple XCM profiles. You might for example want to allow a Form Processor to overwrite more fields than the Twingle API.
The profiles can be accessed at Administer > Automation > Extended Contact Matcher (XCM). Editing a profile leads to the main configuration page.
Matching Rules determine which contacts are considered duplicates. You can enter multiple predefined matching rules or define your own at Contacts > Find and Merge Duplicate Contacts. XCM will always start with the first rule and go on to the next one if there was no result. The matching will stop when at least one contact was found.
For example, if your matching rules contain Email only (any email), then contacts with different names will be matched, as long as they have the same (primary or secondary) email address.
One principle of XCM is that it will always return exactly one contact for further processing by other extensions. If multiple contacts are found by the matching rules, you have to configure which contact should be returned (the oldest or the newest or a new one). If no contact is found, XCM will create a new contact.
It’s a match – what now?
If XCM matches an already existing contact but the field data differs, you have full control to decide what should happen: In the profile settings, you can list all fields that should be filled or overridden. Fill refers to fields of a contact that were previously empty, whereas override refers to fields that already contain data. Note that XCM does not automatically add newly created custom fields.
Another case are Details, such as email, telephone or address. CiviCRM allows to have multiple instances of those data types and you can decide if details should be overridden or added and made primary or not. Be aware that creating a new primary detail (e.g. email address) changes the primary means of communication to a new value which could either be incorrect or not have enough permissions in other use cases (e.g. permission to send a newsletter).
You can configure if activities should be created in the following situations:
- XCM finds multiple matching contacts (the activity is created for both contacts)
- XCM creates a new contact
- XCM matches a contact
- XCM overwrites non empty fields of a contact, e.g. address, email or name. In this case you can record the old data in the activity.
XCM provides it's own import tool which can be accessed at Contacts > Import contacts (XCM). The importer expects csv files with predefined column names, such as first_name, last_name, display_name and/or email.
How does it integrate with core functionalities?
The core import functionality that can be found at Contacts > Import contacts does not use XCM's matching rules. This applies also to Contact Add/Edit forms. If you want to use a XCM profile for the import of contacts, go to Contacts > Import contacts (XCM).
XCM tries to prevent the creation of duplicates but does not help with solving existing duplicates. Those can be accessed at Contacts > Find and Merge Duplicate Contacts.
Anything else?
The data that is processed by XCM to match existing contacts usually comes from external sources, such as public event registration or contribution forms or APIs from third-party systems. It can be helpful to validate the data first. This can be done with SYSTOPIA's Contact Update Queue extension, formerly known as I3Val Input Validation.
