CheckFieldUniqueness Component

Overview

The CheckFieldUniqueness method can be used to test the uniqueness of a targetEntity's field against the entities in the target entity space.

# field: string of the field
# entitiesToTest: collection of targetEntities
FieldUniquenessResult function CheckFieldUniqueness(field, entitiesToTest, excludeSelf=$False)

Parameters

ParameterTypeDescription
fieldStringName of the field to check uniqueness for.
entitiesToTestEntity Collection
The target entities being submitted for the uniqueness check.
excludeSelfBooleanFrom 5.3.1 onwards. If the uniqueness check should not flag an entity as context non-unique when matched only with itself. Optional. Defaults to $False. See the section below for more details.

FieldUniquenessResult

The CheckFieldUniqueness returns an object called FieldUniquenessResult which contains the results of the uniqueness test. FieldUniquenessResult contains the following attributes:

Attributes Description Access Via
Uniques A collection of target entities that passed the uniqueness check $uniques = $result.Uniques;
LocalNonUniques A collection of target entities that failed the uniqueness check against another entity in the tested collection $localNonUniques = $result.LocalNonUniques;
ContextNonUniques A collection of target entities that failed the uniqueness check against an entity in the target entity space. $contextNonUniques = $result.ContextNonUniques;

Examples

$report = $components.CheckFieldUniqueness("uniqueId", $targetEntities);
# Entities with unique value for 'uniqueId' field
$uniqueEntities = $report.Uniques;
# Entities with a non-unique value for 'uniqueId' field compared against other entities in $targetEntities
$locallyNonUniques = $report.LocalNonUniques;
# Entities with a non-unique value for 'uniqueId' field compared against other entities already in the target entity space
$contextNonUniques = $report.ContextNonUniques;
# It is likely that the $sourceEntities would be tested for uniqueness
function Set-UniqueAccountName($entity, $retry)
{
    $first = $entity['GivenNames'].Value;
    $last = $entity['Surname'].Value -replace '[^A-Za-z]','';
    $id = "$first.$last";
    if ($retry -gt 0) { $id += $retry; }
    $entity['sAMAccountName'] = $id;
}
foreach ($entity in $targetEntities)
{
    Set-UniqueAccountName $entity 0;
}
$retry = 1;
$repeat = $true;
while ($repeat)
{
    $repeat = $false;
    $report = $components.CheckFieldUniqueness('sAMAccountName', $targetEntities);
    foreach ($entity in $report.ContextNonUniques)
    {
        Set-UniqueAccountName $entity $retry;
        $repeat = $true;
    }
    foreach ($entity in $report.LocalNonUniques)
    {
        Set-UniqueAccountName $entity $retry;
        $repeat = $true;
    }
    $retry += 1;
}

Details and Usage of excludeSelf

NOTE: The excludeSelf parameter is only available from v5.3.1 onwards.

The excludeSelf optional parameter instructs the uniqueness check function to not flag an entity as context non-unique when matched only with itself if it has already been provisioned into the target entity space.  

For usage of CheckFieldUniqueness in provisioning tasks, where the entities in $targetEntities do not yet exist in the target entity space, this flag will have no effect and should not be provided. However, when CheckFieldUniqueness is used in a synchronization task, the already provisioned entities will returned in the ContextNonUniques collection, having been compared against themselves. If this behaviour is undesirable, provide $True for excludeSelf and the function will not find an entity as being non-unique when comparing it against itself.

Is this article helpful for you?