Custom Connector PowerShell

Introduktion

Custom Connector PowerShell modulet indeholder et sæt af commandlets, der gør opdatering til og fra custom connector databasen lettere. Commandlets kommunikerer med custom connector databasen via en sikker SQL connection (port 1433, 1434).

Custom Connector PowerShell modulet bygges med hver release af Compliance Suiteog kan fås fra Support.

Brug commandlets til at unzippe filen til dit arbejdsdir (husk at unblocke zip filen først) og kør filen der ligger i dir:

Import-Module CcsCustomConnector.psd1

De følgende commandlets er nu tilgængelige i PowerShell command linjen:

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

Konfiguration

For at undgå hardkodning af forbindelsestrengen til den brugerdefinerede forbindelse, databasen, bruges kommandoletten Add-CcsCustomConnectorSystemToConfig til at kryptere og gemme alle forbindelsesindstillinger for et system i en konfigurationsfil, så de andre kommandolader i modulet blot kan henvise til disse indstillinger ved hjælp af systemet navn tildelt til konfigurationen. Dette bør ikke inkluderes i scriptet, der opdateres til eller fra databasen.

Eksempel (skal udføres af en administrator):

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

Scenarie 1: Højere prioritet system

Brug dette scenarie, hvis det system, du forbinder til Compliance Suite, har højere prioritet end Compliance Suite, dvs. personoplysninger fra systemet skal altid overskrive persondata i Compliance Suite - i betragtning af at dette system er det højeste prioritetssystem for personen. Typiske systemer, der er højere prioriteret end Compliance Suite, er Human Resource-systemer. Følgende eksempel, skrevet i Pseudo PowerShell, læser ændrede persondata fra et eksternt system og opdaterer databasen Custom Connector. Det antages, at der findes et PowerShell-modul til det eksterne system. Andre implementeringer er også mulige. Eksemplet antager også, at der er udført konfiguration for systemet 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'

Scenarie 2: Lavere priority system

Brug dette scenarie, hvis det system, du forbinder til Compliance Suite, har lavere prioritet end Compliance Suite, dvs. at persondata og brugerdefinerede ressourcer fra Compliance Suite flyder til det eksterne system og overskriver person- og ressourcedata i det eksterne system. Typiske systemer, der er højere prioriteret end Compliance Suite, er katalogtjenester (som telefon- og e-mail-mapper), Enterprise Resource Planning (ERP) -systemer og lignende. Følgende eksempel, skrevet i Pseudo PowerShell, læser ændringer af person- og ressourcedata i databasen Compliance Suite Custom Connector og opdaterer personer og ressourcer i det eksterne system. Det antages, at der findes et PowerShell-modul til det eksterne system. Andre implementeringer er også mulige. Eksemplet antager også, at der er udført konfiguration for systemet 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
   }
}