Entity Components

Source Entities

Access the synchronisation's source entities with:

$sourceEntities

This variable is a collection of Entities. This collection contains the entities being processed in the current batch of synchronization processing.

Changes made to the entities within this collection will not be maintained between tasks or reflected into UNIFYConnect.

If entities in the source context that don't exist in the current batch need to be queried, the following can be used:

$components.SourceContextEntities($skip, $take);

The contents of $sourceEntities depend on the task run point:

• PreProvisioning: Consists of entities that need to be provisioned from the source context.
• PostProvisioning: Consists of entities that are provisioned from the source context.
• PreDeprovisioning: Empty because the source entities have been deleted.
• PostDeprovisioning: Empty because the source entities have been deleted.
• Synchronization: Consists of entities that need to be synchronised from the source context, including entities that need to be provisioned.

Target Entities

Access the synchronisation's target entities with:

$targetEntities

This variable is a collection of Entities. This collection contains the entities being processed in the current batch of synchronization processing.

If the provisioning task is a type of synchronously executed Pre-Provisioning task, changes made to the entities within this collection will be maintained between tasks and reflected in UNIFYConnect when the modified entity is committed to the target entity space.

Asynchronously executed tasks or tasks of other types will not have changes maintained.

If entities in the target context that don't exist in the current batch need to be queried, the following can be used:

$components.TargetContextEntities($skip, $take);

$targetEntities

The contents of $targetEntities depend on the task run point.

PreProvisioning

Consists of entities to be provisioned after the mapping. Changes can be made to entities in this collection, and they can also be denied synchronization. If the task is configured to run synchronously, changes made will be reflected in UNIFYConnect when the modified entity is committed to the target entity space, and they will be maintained between tasks.

PostProvisioning

Consists of entities for which provisioning was attempted after mapping. If tasks run synchronously, this collection can include changes made during PreProvisioning or Synchronization tasks. Changes made during this task are not reflected in the target entity space.

To determine whether a target entity skipped provisioning because synchronisation was denied, use:

$targetEntity.IsDenied();

PreDeprovisioning

Consists of entities in the target context that need to be deprovisioned. If deprovisioning fails, changes made to this collection are not reflected in the target entity space. They are, however, maintained between tasks when the tasks run synchronously.

PostDeprovisioning

Consists of entities in the target context that need to be deprovisioned, including entities whose deprovisioning failed. If deprovisioning is unsuccessful, changes made to this collection are not reflected in the target entity space.

To determine whether a target entity skipped deprovisioning because synchronisation was denied, use:

$targetEntity.IsDenied();

Synchronization

Consists of entities to be synchronized from the source context after the mapping. Changes can be made to the entities in this collection, and they can also be denied synchronization. If the task is configured to run synchronously, changes made to entities in this collection will be reflected in the target entity space, and they will be maintained between tasks.

Joined Entities

The synchronization source and target entities can be accessed together with the following:

$joinedEntities

$joinedEntities only contains the collection of entities to be synchronized for this run.

This variable is a collection of entity pairs. Each pair exposes the source entity through SourceEntity and the target entity through TargetEntity.

If the provisioning task is a type of synchronously executed Pre-Provisioning task, changes made to the target entities within this collection will be maintained between tasks and reflected in UNIFYConnect when the modified entity is committed to the target entity space.

Examples

foreach ($sourceEntity in $sourceEntities) { ... } 

foreach ($targetEntity in $targetEntities) { ... } 

foreach ($joinedEntity in $joinedEntities) {
  # $joinedEntity.SourceEntity contains the source entity 
  # $joinedEntity.TargetEntity contains the target entity
}

[bool]$hasMore = $true
[int]$pageNumber = 0
[int]$take = 100 

while ($hasMore) {
  $skip = ($pageNumber * $take)
  $output = $components.TargetContextEntities($skip, $take)
  
  foreach($Entity in $output.Entities) { 
    # do something with the entity
  } 
  
  $hasMore = $output.HasMore
  $pageNumber++
}

Update Tracking

During a synchronisation, mapped entity changes are tracked so that entities without meaningful changes do not need to be processed. Making changes to a target entity in a PowerShell task automatically flags the entity to track the change in the same way.

Additionally, the ForceUpdate() method on target entities can be called to make an entity get processed even if no meaningful changes have been made to it.