Uniqueness (AD 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 uniqueness, you must do the following:

Choose which mapped fields should be checked for uniqueness, using the Unique Fields dropdown on the Account tab. Each selected field will be checked for uniqueness during each lifecycle stage for which it has a mapping configuration on the Fields tab. The maximum number of fields you can select is 10.

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 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 (AD target systems)

When Synchronize Unique Fields is enabled, all Complex mappings in this system that you've selected in the Unique Fields dropdown 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].

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 (AD target systems)

Use the External Uniqueness Validation feature to check the uniqueness of target mappings against user accounts in external system(s) other than the current AD target system.

Note

This feature is independent of the Unique Fields dropdown, which only checks uniqueness against the current target system. However, the external uniqueness check only runs if all internal fields have passed their uniqueness check(s).

To configure external uniqueness, you must do the following:

Choose which lifecycle stages the external uniqueness script should be run for, by clicking Settings under Configure External 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.
For each field you want to check, fetch its current value from $account, 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 $result.NonUniqueFields.
The external data can be (but does not have to be) data shared from other HelloID target systems via the Share account fields between target systems feature (i.e., mappings that have been written into the $person object, which you can access here). Since you can write arbitrary PowerShell code, you aren't limited to those systems. You can query an external API, a flat CSV file, or anything else you can script in PowerShell.
Optionally, you can write conditional logic using the current provisioning lifecycle stage from $operation to further segment your uniqueness checks.
Your script then reports the result:
- If the value is unique, it should return nothing in the NonUniqueFields property of $result
- If the value is non-unique (i.e., a duplicate), it should return the name of the attribute in the NonUniqueFields property of $result
- You have the option to return a modified iteration number in the result of the script
- Your script should return $true for Success when the script succeeds (returning either an empty array of attributes, or conflicting attributes). It should return $false when the script fails.

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 and its complex mapping script is re-run.

Use the following script as a template.

# Initialize default properties
$a = $account | ConvertFrom-Json;

# The entitlementContext contains the configuration
# - configuration: The configuration that is set in the Custom PowerShell configuration
$eRef = $entitlementContext | ConvertFrom-Json

# Operation is a script parameter which contains the action HelloID wants to perform for this entitlement
# It has one of the following values: "create", "enable", "update", "disable", "delete"
$o = $operation | ConvertFrom-Json

if($dryRun -eq $True) {
    Write-Verbose -Verbose "Dry run for uniqueness check on external systems"
}

$success = $True;

# Build up result
$result = [PSCustomObject]@{
    Success = $success;
    # Add field name as string when field is not unique
    NonUniqueFields = @()
};

Write-Warning "$person"

# Send result back
Write-Output $result | ConvertTo-Json -Depth 2

In this section: