Attribute Mapping for the Active Directory Data Provider

+ More

Table of Contents

Overview Computer Matching Attributes Account & Person Account Matching Attributes Person Matching Attributes Key Differences between Account and Person

Overview

This reference documents the field mapping and object-matching logic of the standard AD/Entra ID import definitions (source: exported GDIE import configuration package). It is split by CI type, since the underlying object types are technically related but do not behave identically. Differences between Account and Person are called out explicitly.

Note on "Data Definition": labels shown are functional groupings (e.g., Account, Person, Address, Common / Import Tracking) derived from how attributes are used together in the export. They describe where an attribute conceptually lives, not verified internal Matrix42 schema class names. Please cross-check in the SolutionBuilder if an exact class reference is required.

 

Please note that during the setup/implementation phase, the AD provider's matching criteria are often adjusted to meet the customer's specific requirements. You can review the current configuration under Administration → Integration → Import → Import Definition. All AD/Entra-related import definitions are prefixed with "AD: ", including:

  • AD: Import Accounts
  • AD: Import Computers [Insert Only]
  • AD: Import Computers [Obsolete]
  • AD: Import Computers [Update Only]
  • AD: Import Groups
  • AD: Import Persons [Insert Only]
  • AD: Import Persons [Update Only]
  • AD: Membership
  • AD: Update Deleted Accounts
  • AD: Update Deleted Computers
  • AD: Update Deleted Groups
  • AD: Update Deleted Persons

Please refer to these definitions to confirm the actual setup in place.

If more than one record matches the incoming value, the data provider updates a randomly selected record and logs a warning. Resolve duplicate records before running the import to avoid unintended data changes.

 

Computer

Applies to: AD: Import Computers [Insert Only], [Update Only], [Obsolete], and AD: Update Deleted Computers. All four share the same field mapping; differences are limited to which fields are written and the matching pre-conditions (see below).

Matching

The import tries the following criteria in order until one produces a unique match. All fallback steps additionally require the domain to match and (except Priority 1) that no Sid is already assigned to the candidate record:

  1. Sid: objectSid equals the Sid of an existing Computer.

    Obsolete / Update Deleted Computers: The Obsolete definition adds ManagementType = 2 ("not actively managed") as an extra condition on every match step, so it only ever matches computers already flagged as obsolete/unmanaged. Update Deleted Computers matches purely on Sid.

     
  2. sAMAccountName: matches NBName + "$" of an existing Computer (only if that record has no Sid yet).
  3. Name: matches the Name of an existing Computer (only if that record has no Sid yet, lowest-priority fallback).

Attributes

LDAP / Source Attribute Data Definition Attribute Note
objectSid Computer (AD-specific) Sid Primary matching key (see Matching Logic, Priority 1).
sAMAccountName Computer (AD-specific) NBName Transformed: strips trailing "$" and truncates to 15 chars. Also used for matching (Priority 2).
name Computer (base) Name Also used for matching (Priority 3, fallback only).
distinguishedName Computer (AD-specific) ADPath  
dNSHostName Computer (AD-specific) DNSName  
objectGUID Common / Import Tracking ObjectGuid  
uSNChanged Common / Import Tracking uSNChanged Internal AD change-counter, used for delta detection.
description Computer (base) Description  
userAccountControl Computer (AD-specific) UserAccountControl Also drives derived fields AccountStatus, TrustForDelegation and (Obsolete definition) State via bitmask checks.
ManagementType Computer (base / Asset) ManagementType Insert/Obsolete only: distinguishes managed vs. obsolete/unmanaged devices.
(system) Common / Import Tracking LastSyncDate, Synchronizable, Deleted Set from import context, not from an LDAP attribute directly.

Account & Person

Account and Person are documented together because they originate from the same AD/Entra object and share many attribute names, but they are technically distinct target objects with different matching mechanics. Treat the two sub-sections independently; do not assume a Person behaves like an Account with a different label.

Account

Applies to: AD: Import Accounts (and AD: Update Deleted Accounts for the Sid-only deletion flag).

Matching

Accounts run their own independent fallback cascade, most specific first:

  1. Sid: objectSid (or Azure Object ID) equals the Sid of an existing Account in the same domain.
  2. NBAccountName: sAMAccountName equals NBAccountName of an existing, not-yet-matched Account in the same domain.
  3. UPN prefix: userPrincipalName matches AccountName + "@%" of an existing, not-yet-matched Account in the same domain.
  4. AccountName (LIKE): sAMAccountName matches the AccountName of an existing, not-yet-matched Account in the same domain (last-resort fallback).

Attributes

LDAP / Source Attribute Data Definition Attribute Note
objectSid Account (AD-specific) UserSid, Sid Sid is derived: AzureAD source → UserId, else UserSid. Primary matching key (Priority 1).
sAMAccountName Account (AD-specific / base) NBAccountName, AccountName AccountName additionally falls back to the UPN prefix if no sAMAccountName is present. Used for matching (Priority 2 / 4).
userPrincipalName Account (AD-specific) UserPrincipalName UPN prefix (before "@") used for matching (Priority 3, fallback only).
objectGUID Common / Import Tracking UserId, ObjectGuid  
distinguishedName Account (AD-specific) ADCn  
cn / displayName Account (base) cn, displayName, DisplayName DisplayName has a 4-step fallback: displayName → cn → given+sn → UPN-prefix/sAMAccountName.
givenName / sn Account (base) FirstName, LastName Account keeps its own name fields, independent of any linked Person.
description Account (base) Description  
company / department / title Address / Contact Company, Department, Position  
mail Address / Contact MailAddress, eMail Also used as fallback matching-relevant contact data (not a match key itself).
telephonenumber / mobile / homePhone / pager / ipPhone / facsimileTelephoneNumber Address / Contact Phone, MobilePhone, PrivatePhone, Pager, IPPhone, Facsimile  
st / streetAddress / postOfficeBox / postalCode / l / co / wWWHomePage Address / Contact FederalState, Street, POBox, ZIP, City, Country, WebSite  
homeDrive / homeDirectory / profilePath / scriptPath / TerminalServices* Account (AD-specific) HomeDrive*, ProfilePath, LogonScript, TS* Windows profile/roaming/terminal-services paths: technical, rarely customized.
userAccountControl / pwdLastSet / lockoutTime / userCannotChangePassword Account (AD-specific) State, Locked, PwdChangeNextLogon, PwdLifetimeUnlimited, PwdDenyChange All derived via bitmask/NULL checks on the raw AD flags.
objectSid Account (base, relation) Owner Separate match-expression: links the account to an existing User record by comparing Sid.

Person

Applies to: AD: Import Persons [Insert Only], [Update Only], and AD: Update Deleted Persons.

Matching

Persons do not have an independent multi-step fallback cascade the way Accounts and Computers do. Instead, matching is relation-based:

Key mechanism: The import resolves the AD object's Sid against an existing Account (SPSAccountClassAD), then attaches/updates the Person that owns that Account (via the PrimaryAccount relation). There is no separate Sid/UPN/name cascade at the Person level.

Practical implication: a Person can only be reliably matched if a matching Account already exists (or is created in the same run), since the Account import is the effective anchor for Person identity, not the Person import itself.

The Manager relation is matched separately and independently, via the manager's DistinguishedName, compared against the existing Persons' DistinguishedName.

 

Attributes

LDAP / Source Attribute Data Definition Attribute Note
displayName Person DisplayName  
givenName Person FirstName  
sn Person LastName Fallback: sAMAccountName if sn is empty.
company / department / title Person Company, Department, Position  
telephonenumber / mobile / homePhone / pager / ipPhone / facsimileTelephoneNumber Person BusinessPhone, MobilePhone, PrivatePhone, Pager, IPPhone, Fax Note different attribute name vs. Account: Phone → BusinessPhone, Facsimile → Fax.
mail Address / Contact MailAddress, eMail  
st / streetAddress / postOfficeBox / postalCode / l / co / wWWHomePage Address / Contact FederalState, Street, POBox, ZIP / POBoxZIP, City, Country, WebSite  
description / info / initials / physicalDeliveryOfficeName Person Description, Notes, Initials, Office  
manager Person (relation) Manager, ManagerDN Resolved by matching the manager's AD DistinguishedName against an existing Person; this is an independent lookup, not a direct ID copy.
distinguishedName Person (AD-specific) DistinguishedName  
objectGUID Common / Import Tracking UserId, ObjectGuid  
objectSid Person (relation) PrimaryAccount, Accounts Not a direct field copy: resolves the existing Account whose Sid matches, then links it as the Person's (Primary)Account. See Matching Logic below.
userAccountControl Person State Uses Person-specific status values (2023/2024), a different value set than Account's State (2001/2002).

 

Key Differences between Account and Person

  • Matching mechanism: Account has its own 4-step fallback cascade (Sid → NBAccountName → UPN → Name-LIKE). Person has no such cascade of its own; it is matched indirectly through the linked Account's Sid.
  • Practical dependency: if Account import fails or runs after Person import, Person matching can silently fail to find the right existing record, even though the underlying AD object matched fine for the Account import.
  • Status values differ: Account State uses 2001 (Active) / 2002 (Disabled); Person State uses 2023 (Active) / 2024 (Disabled). Both use the same bitmask source (userAccountControl), but different target value sets.
  • Naming/contact fields are stored independently on each object: Account keeps its own FirstName/LastName/Phone/etc. (relevant, e.g., for service accounts without a linked Person), separate from the Person's own copies of the same-looking fields, since they are not automatically the same record.
  • Attribute naming is not always symmetric: e.g. Account's Phone / Facsimile corresponds to Person's BusinessPhone / Fax for the same source attributes.

Related Articles