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

Parameter	Type	Description
field	String	Name of the field to check uniqueness for.
entitiesToTest	Entity Collection	The target entities being submitted for the uniqueness check.
excludeSelf	Boolean	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;

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 optional excludeSelf parameter prevents an already-provisioned entity from being reported as context non-unique when it matches only itself. It has no effect in provisioning tasks, because entities in $targetEntities do not yet exist in the target entity space, and should be omitted there. In a synchronization task, already-provisioned entities can otherwise appear in ContextNonUniques after being compared with themselves. Set excludeSelf to $True to exclude those self-matches.

CheckFieldSetUniqueness Component

The CheckFieldSetUniqueness method can be used to test the uniqueness of a targetEntity's set of fields against the entities in the target entity space

# fields: string array of the fields
# entitiesToTest: collection of targetEntities FieldUniquenessResult 
function CheckFieldSetUniqueness(fields, entitiesToTest, excludeSelf=$False)

Parameters

Parameter	Type	Description
fields	String[]	An array of field names to check uniqueness for.
entitiesToTest	Entity Collection	The target entities being submitted for the uniqueness check.
excludeSelf	Boolean	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.

Example

$fields = @("uniqueId", "uniqueName");
$report = $components.CheckFieldSetUniqueness($fields, $targetEntities);

# Entities with unique value for 'uniqueId' and 'uniqueName' fields
$uniqueEntities = $report.Uniques;

# Entities with a non-unique value for 'uniqueId' and 'uniqueName' fields compared against other entities in $targetEntities 
$locallyNonUniques = $report.LocalNonUniques;
 
# Entities with a non-unique value for 'uniqueId' and 'uniqueName' fields compared against other entities already in the target entity space
$contextNonUniques = $report.ContextNonUniques;