API 2.0 PowerShell Commandlet

Introduction

The Custom Connector PowerShell module contains a set of commandlets that makes updating to and from the custom connector database easier. The commandlets communicate with the custom connector database using a secure SQL connection (port 1433, 1434).

The Custom Connector PowerShell module are build with each release of Compliance Suite and can be obtained from Support.

To use the commandlets unzip the file to your working directory (remember to unblock the zip file before) and run the following PowerShell command in that directory:

Import-Module CcsCustomConnector.psd1

The following commandlets are now be available on the PowerShell command line:

Cmdlet name Scenario Description

Add-CcsCustomConnectorSystemToConfig

Configuration

Adds a connection string to the configuration file encrypted, that allows the other cmdlets to connect to the database without knowing the connection string.

Set-CcsCustomConnectorPerson

Scenario 1: Higher priority system

Upserts one or more persons and custom keys to the database.

Get-CcsCustomConnectorPersonChange

Scenario 2: Lower priority system

Gets changed persons from the database i.e. those with Handled = 1.

Set-CcsCustomConnectorPersonChange

Scenario 2: Lower priority system

Set the value of the Handled column for a person

Get-CcsCustomConnectorResourceChange

Scenario 2: Lower priority system

Gets changed resources from the database i.e. those with Handled = 1.

Set-CcsCustomConnectorResourceChange

Scenario 2: Lower priority system

Set the value of the Handled column for a resource

Configuration

To avoid hardcoding the connection string to the Custom Connector the database the commandlet Add-CcsCustomConnectorSystemToConfig is used to encrypt and store all connection settings for a system in a configuration file, allowing the other commandlets in the module to simply reference these settings by using the system name assigned to the configuration.

This should not be included in the script that updates to or from the database.

Example (should be done by an adminstrator):

PS > Import-Module CcsCustomConnector.psd1
PS > Add-CcsCustomConnectorSystemToConfig `
  -ConnectionString 'connection-string-goes-here' `
  -TableName 'name-of-persontable-in-database' `
  -SystemName 'the-system-name'

Scenario 1: Higher priority system

Use this scenario if the system that you are connecting to Compliance Suite has higher priority than Compliance Suite, i.e. that person data from the system should always overwrite person data in Compliance Suite - given that this system is the highest priority system for the person.

Typical systems that are higher priority than Compliance Suite are Human Resource systems.

The following example, written in Pseudo PowerShell, reads changed person data from an external system and updates the Custom Connector database. It assumes that a PowerShell module for the external system exists. Other implementations are possible as well. The example also assumes that configuration has been done for the system externalhigherprioritysystem

Import-Module CcsCustomConnector.psd1
Import-Module "the-module-definition-for-your-external-system.psd1"

#Using time for state
$currentTimestamp = [System.DateTime]::UtcNow
$lastRunTimestamp = $null
if(Test-Path '.\lastrun.txt') {
  $lastRunTimestampString = Get-Content '.\lastrun.txt'
  $lastRunTimestamp = [System.DateTime]::Parse($lastRunTimestampString)
}

#Assume that these commands exists and gives us all persons from the external
#system that was modified since the date given in the ChangesSince parameter
Connect-ExternalSystem
$externalSystemPersons = Get-ExternalSystemPersons -ChangesSince $lastRunTimestamp

#Convert persons from external system to Custom Connector Database format
$customConnectorPersons = [System.Collections.ArrayList]@()
foreach($externalSystemPerson in $externalSystemPersons){
  $customConnectorPerson = @{
      Id = $externalSystemPerson.UniqueId;
      FirstName = $externalSystemPerson.ExternalFirstName;
      LastName = $externalSystemPerson.ExternalLastName;
      Initials = $externalSystemPerson.SomeInitialsProperty;
      ...
      Handled = 1;
      ModifiedOn = [System.DateTime]::UtcNow;
  }
  $result = $customConnectorPersons.Add($customConnectorPerson)
}

#Update persons in database
Set-CcsCustomConnectorPerson -SystemName "externalhigherprioritysystem" -Persons $customConnectorPersons

# Update timestamp used for state.
$currentTimestamp | Out-File '.\lastrun.txt'

Scenario 2: Lower priority system

Use this scenario if the system that you are connecting to Compliance Suite has lower priority than Compliance Suite, i.e. that person data and custom resources from Compliance Suite flow to the external system and overwrite person and resource data in external system.

Typical systems that are higher priority than Compliance Suite are directory services (like phone and email directories), Enterprise Resource Planning (ERP) systems and similar.

The following example, written in Pseudo PowerShell, reads changes of person and resource data in the Compliance Suite Custom Connector database and updates the persons and resources in the external system. It assumes that a PowerShell module for the external system exists. Other implementations are possible as well. The example also assumes that configuration has been done for the system externallowerprioritysystem.

Import-Module CcsCustomConnector.psd1
Import-Module "the-module-definition-for-your-external-system.psd1"

#Assume this cmdlet exists and that it opens a connection to the external system
Connect-ExternalSystem

#Get changed persons in the custom connector database
$customConnectorPersons = Get-CcsCustomConnectorPersonChange -SystemName "externallowerprioritysystem"

#Update persons in external system from Custom Connector Database
foreach($customConnectorPerson in $customConnectorPersons){
   try {
      #Assume an upsert function exists that creates or updates the person in the external system
      Set-ExternalSystemUser `
        -Id $customConnectorPerson.Initials `
        -ExternalFirstName $customConnectorPerson.FirstName  `
        -ExternalLastName $customConnectorPerson.LastName

     #Update the Compliance Suite Custom Connector Database that the change was handled successfully.
     Set-CcsCustomConnectorPersonChange `
        -SystemName "externallowerprioritysystem" `
        -ChangeId $customConnectorPerson.Id `
        -Handled Handled
   }
   catch {
     #Update the Compliance Suite Custom Connector Database
     #that the change failed and write exception message to log message.
     Set-CcsCustomConnectorPersonChange `
        -SystemName "externallowerprioritysystem" `
        -ChangeId $customConnectorPerson.Id `
        -HandledName Error `
        -HandledError $_.Message
   }
}

#Get changed resources in the custom connector database. Always update resources after persons
$customConnectorResources = Get-Get-CcsCustomConnectorResourceChange -SystemName "externallowerprioritysystem"

#Update persons in external system from Custom Connector Database
foreach($customConnectorResource in $customConnectorResources){
   try {
     if($customConnectorResource.ResourceTypeName -eq 'ExternalSystemPrivilege') {
        #Assume a function exists that adds a privilege to a person
        Add-ExternalSystemUserRole `
          -Id $customConnectorResource.PersonInitials `
          -PrivilegeName $customConnectorResource.ResourceName
     }

     if($customConnectorResource.ResourceTypeName -eq 'ExternalSystemRole') {
        #Assume a function exists that sets a default role on a person
        Set-ExternalSystemUserDefaultRole `
          -Id $customConnectorResource.PersonInitials `
          -RoleId $customConnectorResource.ResourceCustomId
     }

     #Update the Compliance Suite Custom Connector Database that the change was handled successfully.
     Set-CcsCustomConnectorPersonChange `
        -SystemName "externallowerprioritysystem" `
        -ChangeId $customConnectorResource.Id `
        -Handled Handled
   }
   catch {
     #Update the Compliance Suite Custom Connector Database
     #that the change failed and write exception message to log message.
     Set-CcsCustomConnectorPersonChange `
        -SystemName "externallowerprioritysystem" `
        -ChangeId $customConnectorResource.Id `
        -HandledName Error `
        -HandledError $_.Message
   }
}