Link Tasks
Overview
Tasks are customisable actions that run at defined points during provisioning, deprovisioning, and synchronisation. A task can run during either incoming or outgoing synchronisation.
Run Point
Tasks can be created to run at one of five run points. The five points are described below.
| Name | Description |
|---|---|
| PreProvisioning | Runs after a new target entity is created and mapped, but before it is committed to the target entity space or connected system. Can modify the entity and control whether it is synchronised. |
| PostProvisioning | Runs after the new target entity is committed to the target entity space or connected system. Cannot modify the provisioned entity. |
| PreDeprovisioning | Runs before the target entity to be deleted is removed from the target entity space or connected system. |
| PostDeprovisioning | Runs after the target entity to be deleted is removed from the target entity space or connected system. |
| Synchronization | Runs after changes are calculated but before they are committed. It also runs during provisioning after pre-provisioning tasks. Can modify the entity and control whether it is synchronised. |
For more information about the steps of the synchronization process, see the documentation page on Synchronization Execution.
Entity Components
PreProvisioning
- SourceEntities: Entities that need to be provisioned from the source context.
- TargetEntities: Entities to be provisioned after mapping. They can be modified or denied synchronisation. For synchronous tasks, changes are maintained between tasks and are reflected in UNIFYConnect when the entity is committed to the target entity space.
PostProvisioning
- SourceEntities: Entities that were provisioned from the source context.
- TargetEntities: Entities for which provisioning was attempted after mapping, including entities delayed or denied during provisioning. For synchronous tasks, changes made during PreProvisioning or Synchronization tasks remain accessible. Changes made during PostProvisioning are not reflected in the target entity space.
To determine whether a target entity skipped provisioning because synchronisation was denied, use:
$targetEntity.IsDenied();PreDeprovisioning
- SourceEntities: Empty because the source entities have been deleted.
- TargetEntities: Entities in the target context that need to be deprovisioned. If deprovisioning fails, changes are not reflected in the target entity space, but synchronous tasks maintain them between tasks.
PostDeprovisioning
- SourceEntities: Empty because the source entities have been deleted.
- TargetEntities: Entities in the target context that need to be deprovisioned, including entities whose deprovisioning failed. Changes made after an unsuccessful deprovision are not reflected in the target entity space.
To find if a target entity has skipped deprovisioning due to denying the sync, the following method can be used
$targetEntity.IsDenied();Synchronization
- SourceEntities: Entities that need to be synchronised from the source context, including entities that need to be provisioned.
- TargetEntities: Entities to be synchronised after mapping, including entities to be provisioned. They can be modified or denied synchronisation. For synchronous tasks, changes are maintained between tasks and reflected in the target entity space.
In any of these tasks, access source and target entities together through the joined entity collection:
foreach ($joinedEntity in $joinedEntities) {
# $joinedEntity.SourceEntity contains the source entity
# $joinedEntity.TargetEntity contains the target entity
}Joined entities only contain the collection of entities to be synchronized for this run.
Run Type
Every task has a run type that determines whether it executes when Test Mode is enabled. For details, see Test Mode.
Asynchronous Execution
Tasks can also be run asynchronously. An asynchronous task executes without preventing subsequent tasks or provisioning/synchronization process from progressing. Running a task asynchronously should be used when the task is expected to have a long duration, i.e., making account creation calls to external services.
Asynchronous tasks cannot have any effect on the outcome of provisioning or syncing processes, no matter at what point they are run. This includes task features such as manipulating entity data, delaying an entity sync, or denying an entity sync.
Configuration
To create a new task click the appropriate Add Task button for the desired direction and run point and select the type of task required. See the appropriate task page listed below for task-specific configuration instructions.
Task Types
Mapping Values in Tasks
While pre-provisioning and synchronisation tasks are capable of performing value mapping, it is strongly recommended to utilise the links inbuilt mapping configuration to perform any value mapping. The reasoning behind this is that the synchronisation and provisioning processes use the link's configured mapping to filter out inconsequential changes, optimising link operations to ensure only changes with meaningful outcomes need to be processed (unless the link is configured to Process Unmapped Changes). If tasks contain any manual mapping not defined in the link configuration, there will likely be scenarios where otherwise meaningful changes are not synchronised.
To ensure that tasks do not impede link operation, ensure that all relevant source schema fields are mapped in the link configuration. If a task is to perform some transformative operation on entity values, opt to have mapping configuration for all relevant fields, then perform the value manipulation on the mapped target entities that are provided to the task. Note, however, that this can result in surplus changes as the incoming value isn't ending up on the target entity.