Skip to main content


Target mappings

Mappings in Active Directory target systems & Azure AD target systems connect fields in your Persons to fields in target user accounts, such as the sAMAccountName, userPrincipalName, and cn. Target mappings are applied during Enforcement.


To get started, Map fields.

On an AD/Azure AD target system's Account tab, the dropdown menus represent fields available in the target system's user account schema.


The inner panes (nested under each dropdown) represent the value that will be mapped onto the target field. See ???.

For example, here the Person.Name.NickName, Person.Name.FamilyNamePrefix, and Person.Name.FamilyName are concatenated and mapped onto the sAMAccountName field in a Complex mapping:


To map a custom field that you've created in the AD/Azure AD target system's user schema, Add a custom field.

To clone an AD/Azure AD target system's mappings to another system, Clone mappings.

Target mapping field types

Each mapped field can be:


A constant string value (specified by you).


A direct mapping of a person or contract field, without any further transformations applied.


A string built in JavaScript. See Complex mappings.

Target mapping options

Options for each mapped field include:

Ensure This Field Is Unique

During enforcement, HelloID will check if the value of this mapping is duplicated in any other user accounts that already exist in this target system. This is particularly useful to avoid collisions on identifying fields like sAMAccountName and cn.

If a duplicate value is found for a unique Fixed or Field mapping, the relevant enforcement action will terminate with an error. However, if a duplicate value is found for a Complex mapping, that mapping's Iteration variable is incremented and the mapping is re-run.

This feature is entirely independent of the Check On External Systems feature, which checks uniqueness against systems other than the current target system.

To detect and link together duplicate accounts instead of merely preventing mapping collisions, use the Correlation feature.

Update This Field

When enabled, HelloID will update this field in target user accounts during the Update stage of enforcement, if the underlying snapshot and/or target mapping has changed.

When disabled, HelloID will never update this field in target user accounts. Instead, the initial value written into target user accounts is retained indefinitely, regardless of any changes in the underlying snapshot or target mapping.

Store This Field In Person Account Data

See Share account fields between target systems.

Uniqueness (target mappings)

System-wide uniqueness validation features include:


Both of these features use the Iteration variable.

Synchronize Unique Fields

When Synchronize Unique Fields is enabled, all Complex mappings in this system with Ensure This Field Is Unique enabled will have their Iteration variables synchronized. HelloID automatically finds and uses the lowest Iteration value that results in collision-free mappings across all unique complex mappings.

This ensures that fields within the same target user account (e.g., username and email address) are appended with the same value. For example: username jdoe2 + email address [email protected], instead of a mismatch like jdoe2 + [email protected].


Use caution with Synchronize Unique Fields if any of your complex mappings have Update This Field enabled. Iteration counts from zero during the Update step of enforcement. It does not retain the iterator value from the original account entitlement grant. This can cause the iterator value in updated mappings to desynchronize from non-updated mappings, resulting in mismatched user attributes.

Check On External Systems

The Check On External Systems feature lets you check target mapping values for uniqueness against user accounts in system(s) other than the current target system. See Uniqueness check on external systems.

This feature is entirely independent of the Ensure This Field Is Unique toggle, which only checks uniqueness against the current target system.

Supported for Active Directory target systems only.

Notes (target mappings)
  • When mapping users' mailbox names, always use the mailNickname attribute. Do not attempt to use the mail attribute. (Azure AD target systems only)

  • If a user's proxy address changes, the new proxy address becomes the primary address (SMTP) and the existing proxy address becomes an alias (smtp).