UNIFYConnect v8.1

Appearance

PowerShell Connector ​

Overview ​

The PowerShell connector allows you to define the interaction with the target system entirely through Microsoft PowerShell scripts. The definition of this target system will need to be defined by the implementer.

CHECK

This connector requires a foundational understanding of PowerShell and basic programming concepts.

NOTE

View PowerShell in UNIFYConnect for more information on the version of PowerShell used by UNIFYConnect.

Implementation ​

The PowerShell connector can be configured to perform the standard connector Create, Read, Update and Delete operations.

Each operation should be configured to describe a target system or domain of identity for the connector being configured

In the following example scripts, the demonstration connector will have a schema with the five fields:

  • An ID field of the integer type which is the key of the schema.
  • A FirstName field of the string type.
  • An Age field of the integer type.
  • An isActive field of the boolean type.
  • A PhoneNumbers field of the multivalued string type.

Import All ​

The Import All operation retrieves all entities from the target system.

The PowerShell script for this operation will need to Create the entities representative of those in the target system, Populate them with the respective data corresponding to the connector schema, and Commit them.

In the following example script, the Import All operation will return one entity, which in this case will be the employee "Henry":

Powershell
$entity = $entities.Create();
$entity['ID'] = 10002;
$entity['FirstName'] = 'Henry';
$entity['Age'] = 64;
$entity['isActive'] = $true;
$entity['PhoneNumbers'] = @('0400 000 000', '3000 0000');
$entity.Commit();

Import Changes ​

UNIFYConnect supports two different types of Import Changes operations internally: Entity ID and Entity Polling.

Import Changes - Entity ID ​

The Entity Id method takes a two-step approach in which one operation returns the key values of the entities that have changed, and another returns the entities of those changed keys.

CHECK

Entities that maintain keys that are returned in the first script - but not in the second - will be considered as deleted.

Firstly, a script will need to be provided which will return all of the key-values of changed and deleted entities in the target system. If it is possible at this stage to determine if the key corresponds to a deleted entity, you should call the Delete method on the key. If the key corresponds to an added or updated entity, or if you cannot determine if it the key corresponds to a deletion, then you should call the Commit method on the key.

PowerShell
$changedKey = $keys.Create();
$changedKey['ID'] = 10002;
$changedKey.Commit(); # entity has been changed (added, updated or deleted) $deletedKey = $keys.Create();

$deletedKey['ID'] = 10003;
$deletedKey.Delete();# entity has been deleted

In the above script, a single key corresponding to the entity with the ID 10002 would be saved to represent a changed entity, and a single key corresponding to the entity with the ID 10003 would be saved to represent a deleted entity. Existing connector entities with keys that match the deleted keys will be deleted. The changed keys will then be passed to the second script, which will need to interpret any given keys and retrieve the entities for those keys. For keys corresponding to deleted entities, no entity should be committed, and then the existing connector entity with a key matching that key will also be deleted.

PowerShell
foreach ($changedKey in $components.InputKeys)
{
    $changedEntity = $entities.Create();
    $changedEntity['ID'] = $changedKey['ID'];
    #$changedEntity['... etc.
    $changedEntity.Commit(); # don't commit if the entity should be deleted
}

In this example, the Import Changes operation would receive only the key with the ID 10002, since the key with the ID 10003 corresponded to a deletion, and would register a change for the entity corresponding to the 10002 identifier. The entity with the ID 10003 would be deleted.

Import Changes - Entity ​

This method should be used In the cases where it may only be possible to return the entities themselves that have changed without first polling for their ids.

This method should be implemented in the same manner as the Import All operation, but only returning entities that have changed in the target system. If the entity has been added or updated, the Commit method should be called, or if the entity has been deleted, the Delete method should be called. In the case of a deletion, only the key fields need to be set.

PowerShell
$changedEntity = $entities.Create();
$changedEntity['ID'] = 10002;
$changedEntity['...'] #etc.
$changedEntity.Commit(); # add or update this entity

$changedEntity = $entities.Create();
$changedEntity['ID'] = 10003; # only need to set key fields
$changedEntity.Delete(); # delete this entity

Add Entities ​

The Add Entities operation, as its name would suggest, adds a series of provided entities to the target system.

The PowerShell script for this operation will need to Take an entity from the collection of InputEntities provided, Extractthe relevant data, and Submit that same data to the target system.

CHECK

The way that the entity will be added will be completely up to how the target system expects data.

PowerShell
foreach ($entity in $components.InputEntities)
{
    $id = $entity['ID'];
    $firstName = $entity['FirstName'];
    $age = $entity['Age'];
    $isActive = $entity['isActive'];
    $phoneNumbers = $entity['PhoneNumbers'];
    #Add the entity with the extracted data - this will be up to how the target system expects data.
    #...
}

Update Entities ​

The Update Entities operation, as its name would suggest, updates a series of provided entities to the target system.

The PowerShell script for this operation will need to Take an entity from the collection of InputEntities provided, Extractthe relevant data, and Submit that same data to the target system.

CHECK

The way that the data will be submitted will be completely up to how the target system expects data.

PowerShell
foreach ($entity in $components.InputEntities)
{
    $id = $entity['ID'];
    $firstName = $entity['FirstName'];
    $age = $entity['Age'];
    $isActive = $entity['isActive'];
    $phoneNumbers = $entity['PhoneNumbers'];
    #Update the entity with the extracted data - this will be up to how the target system expects data.
    #...
}

Delete Entities ​

The Delete Entities operation, as its name would suggest, deletes a series of entities in the target system.

UNIFYConnect will provide the connector with a series of keys in the InputKeys collectiondenoting the entities to be deleted.

These values correspond to the key of the connector schema.

The PowerShell script for this operation will need to Take a key from those provided in the InputKeys collection, Extract the relevant key-values, and Submit the entity for deletion.

CHECK

The way that the key-values will be submitted will be completely up to how the target system expects data.

PowerShell
foreach ($keys in $components.InputKeys)
{
    # Extract the key from the keys, in this example the schema only has the one ID key, but connectors can be configured with many.
    $id = $keys['ID'];
    # Delete the entity corresponding to the $id to be deleted - this will be up to how the target system expects data.
}

Delete All Entities ​

The Delete All Entities operation, as its name would suggest, sends a request to delete all entities in the target system.

There is no additional information provided by UNIFYConnect to this operation, instead the script will have to manually delete all entities in the target.

Change Password ​

The change password operation changes or sets the password of an entity in the target system.

UNIFYConnect provides the connector with a key, a new password and optionally an old password, indicating a set password or modify password operations, respectively.

The PowerShell script will need to extract the needed information from the key and update the target system with the new password value.

PowerShell
$key = $components.InputKey;
$username = $key['username'];
$oldPass = $components.OldPassword;
$newPass = $components.NewPassword;
# Perform target system password change operation.

Modify Anchor Key ​

This script is executed for entities during an export operation when values for the schema fields set as key change.

The script is run once for each entity which changed key values, and UNIFYConnect provides the script with both the old and new keys via the OldKey and NewKey properties on the $component object.

The key field names and key values can be accessed in a number of ways, depending on the situation.

PowerShell
$oldKey = $components.OldKey;
$newKey = $components.NewKey;

# Iterate though the keys, get values
foreach ($keyFieldName in $newKey.Keys) {
  $keyValue = $newKey.Value[$keyFieldName];
}

# Access key values by known field names
$oldUsernameValue = $oldKey.Value["username"];

# Access field name and values by index
$firstFieldName = $newKey.Keys[0];
$secondValue = $newKey.KeyValues[1];

Schema Provider ​

The schema provider is used to request the schema of the entities in the target system.

This allows for connector schemas to be created dynamically (based on the target system) or statically (preconfigured based on the expected data).

Schema fields can be created using the New-Field function.

This function has the following signature:

PowerShell
function New-Field([string]$fieldName, [string]$type, [bool]$key, [bool]$readOnly = $false, [bool]$required = $false)

The following is an example implementation using this method:

PowerShell
New-Field "ID" "int" $true $false $true;
New-Field "FirstName" "string" $false $true $false;
New-Field "Age" "int" $false $false $false;
New-Field "isActive" "bool" $false $false $false;
New-Field "PhoneNumbers" "string.multi" $false $false $false;

For details of specific PowerShell Connector components, see the following pages

Operation Timeout ​

All script type supported by the PowerShell connector provide the option to set an operation timeout. If enabled, UNIFYConnect will forcibly terminate the execution of a PowerShell script once the configured duration has passed.

WARNING

The termination of an executing PowerShell script from an exceeded operation timeout may result in an undesired state, depending on the script and its behaviour. In these cases, it is recommended to handle the termination gracefully from within the script where this is possible, and rely on the operation timeout for cases where it is not.

©2026 UNIFY Solutions Pty. Ltd.