Custom Connector PowerShell

Introduction

The Custom Connector PowerShell module contains a set of commandlets that facilitate updating to and from the custom connector database. Commandlets communicate with the custom connector database via a secure SQL connection (ports 1433, 1434).

The Custom Connector PowerShell module is built with each release of the Compliance Suite and is available from Support.

Use commandlets to unzip the file to your work directory (remember to unblock the zip file first) and run the file located in the directory:

Import-Module CcsCustomConnector.psd1

The following commandlets are now available in 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 connection database, the Add-CcsCustomConnectorSystemToConfig command line is used to encrypt and store all system connection settings in a configuration file so that the other command loader in the module can simply refer to those settings using the system name assigned to the configuration. This should not be included in the script that is updated to or from the database.

Example (to be performed by an administrator):

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 you connect to Compliance Suite has higher priority than Compliance Suite, ie personal information from the system must always overwrite personal data in Compliance Suite - considering that this system is the highest priority system for the person. Typical systems that have higher priority than Compliance Suite are Human Resource systems. The following example, written in Pseudo PowerShell, reads modified personal data from an external system and updates the Custom Connector database. It is assumed that a PowerShell module exists for the external system. Other implementations are also possible. The example also assumes that the configuration for the system externalhigherprioritysystem has been performed.

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 you are connecting to Compliance Suite has a lower priority than Compliance Suite, ie. that personal data and custom resources from Compliance Suite flow to the external system and overwrite personal and resource data in the external system. Typical systems that have higher priority than Compliance Suite are directory services (such as telephone and email directories), Enterprise Resource Planning (ERP) systems, and the like. The following example, written in Pseudo PowerShell, reads changes to personal and resource data in Compliance Suite Custom Connector database and updates people and resources in the remote system. It is assumed that a PowerShell module exists for the external system. Other implementations are also possible. The example also assumes that a configuration has been performed for the external external priority system.

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
   }
}