Uniqueness (PowerShell v2 target systems)
Use the uniqueness feature to prevent HelloID from mapping already-existing values into target account attributes during enforcement. This is useful to avoid collisions on fields like sAMAccountName and cn. Collisions are then resolved by suffixing the pending mapped value (e.g., connie.van.den.winth → connie.van.den.winth1).
To configure the uniqueness script, you must do the following:
Choose which lifecycle stages the uniqueness script should be run for, by clicking
Settings under Uniqueness Validation on the Account tab. The script will then apply to all mapped fields which have a configuration for those stage(s) on the Fields tab.
In the script, specify which mapped fields should be checked for uniqueness in
$fieldsToCheck. For example:$fieldsToCheck = "UserName","ExternalId".For each field you specified in
$fieldsToCheck, fetch its current value from $actionContext.Data, and write custom logic to check that value against all existing values in the target system. For example, check a pending username against all existing usernames. If a collision is found, add the field's name to $outputContext.NonUniqueFields. For example:$outputContext.NonUniqueFields.Add("UserName").Caution
Be sure to fetch the current account reference from $actionContext.References.Account and exclude it from your logic, to avoid a false positive.
Optionally, you can write conditional logic using the current provisioning lifecycle stage from $actionContext.Operation to further segment your uniqueness checks.
What happens when the script runs during enforcement depends on the mapping type:
For fields with Fixed, Field, or None mappings, enforcement terminates with an error.
For fields with Complex mappings, the mapping's Iteration variable is incremented (or set to the custom value you wrote to $outputContext.Iteration) and its complex mapping script is re-run.
The script timeout is 30 seconds.
Tip
To detect and link together duplicate accounts instead of merely preventing mapping collisions, use the Correlation feature.
Synchronize Unique Fields (PowerShell v2 target systems)
If you want to synchronize the Iteration value across multiple mapped fields, add all the field names to be synchronized to $outputContext.NonUniqueFields in the Uniqueness script. HelloID will automatically find and use the lowest iteration value that results in collision-free mappings across all the fields you've marked non-unique.
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].
Tip
If needed, you can add fields that are unique to $outputContext.NonUniqueFields. This will keep them all synchronized with one another, even if a collision only occurs on a single field.
Caution
Use caution with this feature if any of your complex mappings on the Fields tab have configurations for lifecycle stage(s) other than Create. The iteration variable counts from zero each time a mapped field is calculated or recalculated. It does not retain the iterator value from the original account entitlement grant. This can cause the iterator value to become desynchronized in subsequent enforcements, resulting in mismatched user attributes.
Uniqueness check on external systems (PowerShell v2 target systems)
To check uniqueness against systems other than the current target system, simply add the necessary logic to your uniqueness script.