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.

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":

$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

UNIFYBroker supports two different types of Import Changes operations internally. These are the Entity Id and Entity Polling types.

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.

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.

$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.

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.

$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, Extract the relevant data, and Submit that same data to the target system.

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, Extract the relevant data, and Submit that same data to the target system.

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.

Identity Broker will provide the connector with a series of keys in the InputKeys collection denoting 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.

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 UNIFYBroker 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.

Identity Broker 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.

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

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:

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

The following is an example implementation using this method:

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

• PowerShell Connector Entities
• PowerShell Connector Export Changes Operation
• PowerShell Connector Failed Operations
• PowerShell Connector Import All Operation
• PowerShell Connector Import Changes Operation
• PowerShell Connector Logger
• PowerShell Connector Schema
• Usage of Invoke-Command in PowerShell Connector Operations