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

FieldUniquenessResult

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

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

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.