Uniqueness (Azure AD target systems)

During enforcement, HelloID will check if the values of mappings whose Ensure This Field Is Unique toggles are enabled already exist in any other user accounts in this 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 External uniqueness check feature, which checks uniqueness against systems other than the current target system.

Tip

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

Additional system-wide uniqueness validation features include:

Synchronize Unique Fields (Azure AD target systems)

When Synchronize Unique Fields is enabled, all Complex mappings in this system with their Ensure This Field Is Unique toggle enabled will have their Iteration variables synchronized by the Uniqueness feature. 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 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.

Uniqueness check on external systems (Azure AD target systems)

Use the Check On External Systems feature to check the uniqueness of Target mappings against user accounts in external system(s) other than the current Azure AD target system.

Note

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

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.

The properties of the $account object are the outputs of the system's current target mappings. These are the values to check for uniqueness in your script.

This script is run during both the Grant and Update steps of Enforcement for each person receiving an Account entitlement. Suppose that John Doe's person object is being mapped to a target Azure AD account with the sAMAccountName john.doe. HelloID runs your custom logic, which must check if a john.doe user already exists in the external system(s) of your choice. 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

When the script runs, 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 process is repeated until a unique value is found, which is then used for the target attribute mapping. (Additionally, an enforcement action will terminate with an error if an unused attribute name is returned in NonUniqueFields.)

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.

Use the following script as a template.

# Initialize default properties
$a = $account | 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 = @()
};

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

In this section: