Person Matching Reference
An Active Directory synchronization job matches each directory user to an existing Person record in two stages: first by the stored directory identity, then, only when that finds no one, by name, login, and email. See Active Directory Synchronization for the synchronization job itself.
Stage 1: directory identity
Each Person record a synchronization job writes carries the directory
object's identity in a hidden field: the directory GUID in its braced form
({XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}), or, when the directory returns no
GUID, the object's distinguished name. The field holds one or the other,
never both.
The job adds the mapping for this field to both its create action and its update action, unless the action already maps the field, and sets the value to the directory identity for every user. Because of this, editing the mapping cannot switch the field off. An administrator can map the field to something else instead, because an existing mapping is left alone.
For each directory user, the job first compares the incoming GUID and the incoming distinguished name against the stored identity of every Person, ignoring case. As a result, a person imported by GUID still matches after a rename, and a person imported by distinguished name still matches once a GUID becomes available. Only when no stored identity matches does the job go on to stage 2.
Creating a technician account from a directory user in the Settings App also writes the user's GUID, in the same braced form, directly into this field on the new Person record. A person created this way with a GUID is already matched by identity the first time a synchronization job runs.
Stage 2: name, login, and email
The job scores candidates on three checks and takes the highest score, oldest record first.
| Check | Weight when the match is the primary hit | Weight otherwise | Restriction |
|---|---|---|---|
| The Person's full name equals the mapped full name | 1 | 1 | Only Persons with no stored directory identity. This restriction applies to directory synchronization alone. |
| One of the Person's logins matches the login, with the domain equal or empty | 4 | 2 | None |
| One of the Person's email addresses matches the mapped email | 16 | 8 | None |
These rules also apply:
- Inactive persons are excluded from all three checks.
- When the job has a create action, a check runs only if the corresponding field is mapped in that action. With no create action, all three checks run.
- The full-name check is skipped when the full name equals the email.
- The minimum accepted score for this job is 1, so a name match alone is enough.
- When the name, login, and email are all empty, a fourth check looks for a Person whose name, email, and login are all empty.
The full-name restriction means that a person who already carries a directory identity is never matched again by name, so two directory users with the same display name cannot collapse onto one record by name on the second run. The login and email checks have no such restriction and can still match a person who already carries a directory identity.
The same name, login, and email matcher is also used elsewhere in the product, for example by the Mail Connector, the Discovery connector, and the Settings App's account wizard. The full-name restriction is the one part that exists only for directory synchronization.