How GALsync Matches Contacts, and What Happens When the Match Breaks

Purpose

Most GALsync problems that present as "contacts disappeared", "the address never updated" or "mail to that contact bounces" are the same problem seen from different angles: GALsync could not match a contact it had previously created. This article explains the matching mechanism, what GALsync does when a match fails, and how to read the evidence. The specific scenarios each have their own article; this is the one that explains why they behave the way they do.

The matching key

GALsync matches objects by primary SMTP address. During an import, each object in the data file is compared against the objects already in the target environment, and the primary SMTP address is what identifies them as the same object.

The default match is the primary SMTP address of the data file object against the primary SMTP address of the existing object in the target. Other combinations are possible and are handled — the data file object's primary SMTP address may match a secondary SMTP address on the target object, among others — but the default is primary to primary. The full set of criteria also includes an old primary SMTP address, the original SMTP address held in the source domain value, and the targetAddress.

Everything below follows from that one design decision. GALsync has no separate identifier to fall back on: if the address it matches on is not there, the contact it created is, from its point of view, a contact it does not recognise.

What happens when a match fails

When GALsync cannot match a data file object to an existing target object, it creates a new contact. When it cannot find a previously synchronized contact in the incoming data file, it deletes that contact. Both are correct behaviour — they are how a new user appears and a departed user disappears in the partner's address list.

The damage comes from what a delete-and-recreate does to the legacyExchangeDN. The recreated contact gets a new one. Outlook clients hold the old legacyExchangeDN in their nickname cache and autocomplete list, so mail sent to a cached entry is addressed to an object that no longer exists, and Exchange returns a non-delivery report.

This is why a problem that is invisible on the GALsync server — the sync reports success, the contacts are all present and correct — shows up as bouncing mail on the partner's desks. The contacts are fine. The clients are pointing at the previous generation of them.

The ways the match breaks

1. The primary SMTP address changed at the source. The most common cause, and entirely preventable. There is a documented way to change an address without triggering the delete-and-recreate: record the old address in a custom attribute with the galsync: prefix before the change synchronizes. See How to Sync Primary SMTP Address Changes from Source to Target in GALsync.

2. The data file was incomplete. If an export ends early or writes objects without their primary SMTP address, the import cannot match contacts that genuinely still exist at the source, and deletes them. Two export-policy settings exist to hold such a file back. See How to Prevent GALsync Contact Deletion During Export Errors.

3. Two policies are competing for the same objects. More than one import policy writing to the same organizational unit, or more than one export policy targeting the same Exchange Online organization, will each delete what the other created. This is configuration, not failure — no export setting prevents it, and the symptom is deletions on a regular cycle rather than after a visible error.

4. The object left the export's scope. A filter change, a group membership change, or a search result cap can silently remove objects from the export — which the import cannot distinguish from deletion at the source. See Why Objects Are Missing from a GALsync Export.

5. One source object matched two target objects. Because several criteria can match, a source object can match both the correct contact and something else — an Entra guest user, typically. Without arbitration the result is non-deterministic and attributes land on the wrong object. See GALsync Writes a Contact's Attributes onto the Wrong Object.

6. The contact's stored source domain no longer matches. A contact whose source domain is no longer part of the synchronization is not modified at all — silently, with no error, and reported as up to date. See Synced Contacts Report Up to Date but Never Change: the Source Domain Problem.

Reading the evidence

GALsync logs the matching itself, which makes this diagnosable rather than guesswork.

Match counters. Each match combination that occurs during an import is counted, and the counts appear in the detailed summary in the log file and in the status notification email. Because the default is primary-to-primary, a significant count against any other combination is the signal: it means objects are being matched on something other than the expected address, and it is worth checking those objects at the source before accepting the result.

Object counts between runs. Compare the number of objects in successive export files rather than only whether the job succeeded. A sudden drop precedes every mass deletion and is the earliest warning available.

Both sides of the sync. Use Action → Export Status and Action → Export Configuration on the exporting and importing servers. A matching failure is a conversation between two files, and one side rarely explains it.

Recovering from NDRs after a recreate

If contacts have already been deleted and recreated and users are receiving NDRs, there are two documented remedies.

Restore the old address as an X500 proxy address. The NDR itself contains the legacyExchangeDN Outlook tried to use, in IMCEAEX- form. Reconstruct it as an X500 address and add it to the contact's proxyAddresses. For an NDR containing:

IMCEAEX-_O=TEST_OU=First+20administrative+20Group_cn=Recipients_cn=Ron.Smith
#550 5.1.1 RESOLVER.ADR.ExRecipNotFound; not found ##

the X500 address to add is:

X500:/O=TEST/OU=First administrative Group/cn=Recipients/cn=Ron.Smith

The legacyExchangeDN must be unambiguous within an Exchange forest, so check existing legacyExchangeDN values and X500 addresses before adding one.

Clear the nickname cache. The alternative is resetting the nickname and automatic completion caches, which has to be done on every affected client — practical for a handful of users, not for an organisation.

The X500 approach fixes the problem centrally and is the better option at any scale.

Where to go next

By symptom:

Contacts deleted in bulk → How to Prevent GALsync Contact Deletion During Export Errors
Address change not reflected, or NDRs after one → How to Sync Primary SMTP Address Changes from Source to Target in GALsync
Contacts never update, no errors → Synced Contacts Report Up to Date but Never Change: the Source Domain Problem
Wrong person's details on a contact → GALsync Writes a Contact's Attributes onto the Wrong Object
Objects missing from the export → Why Objects Are Missing from a GALsync Export
Policy cancels or completes with errors → GALsync Policies Cancel or Fail: Working Through the Causes in Order
Export finishes but exports nothing → Troubleshooting GALsync Export Policies That Finish but Export No Data
Import runs for hours or hangs → GALsync Imports That Hang or Run for Days on Large Contact Sets
Hex suffix or wrong display name on contacts → GALsync Imported Contacts Show a Hex Suffix or the Wrong Display Name
Stale contact after someone leaves → Handling Terminated Users and Alias Transfers in GALsync

By task:

References

GALsync 8.7 Manual p.302 — How to analyze object matches in the log file which GALsync uses during the import to update existing objects; the default match and the match counters.
GALsync 8.7 Manual p.231 — the primary SMTP address as GALsync's matching criterion, and the NDR consequence of a changed address.
GALsync 8.7 Manual p.305 — How do I resolve NDR (Non-Delivery Report) problems?; X500 reconstruction and nickname cache reset.
GALsync 8.7 Manual p.12 — one import policy per organizational unit; one export policy per Exchange Online target.
The current GALsync manual is published by NETsec at netsec.de.

Articles in this section