Chat now with support
Chat with Support

Active Roles Sync Service 8.2 - Administration Guide

Synchronization Service overview Deploying Synchronization Service Deploying Synchronization Service for use with AWS Managed Microsoft AD Getting started Connections to external data systems
External data systems supported with built-in connectors
Working with Active Directory Working with an AD LDS (ADAM) instance Working with Skype for Business Server Working with Oracle Database Working with Oracle Database user accounts Working with Exchange Server Working with Active Roles Working with One Identity Manager Working with a delimited text file Working with Microsoft SQL Server Working with Micro Focus NetIQ Directory Working with Salesforce Working with ServiceNow Working with Oracle Unified Directory Working with an LDAP directory service Working with an OpenLDAP directory service Working with IBM DB2 Working with IBM AS/400 Working with IBM RACF Working with MySQL database Working with an OLE DB-compliant relational database Working with SharePoint Working with Microsoft 365 Working with Microsoft Azure Active Directory Configuring data synchronization with the SCIM Connector Configuring data synchronization with the Generic SCIM Connector
Using connectors installed remotely Creating a connection Renaming a connection Deleting a connection Modifying synchronization scope for a connection Using connection handlers Specifying password synchronization settings for a connection
Synchronizing identity data Mapping objects Automated password synchronization Synchronization history Scenarios of use Developing PowerShell scripts for attribute synchronization rules Using PowerShell script to transform passwords

Creating a sync workflow for synchronizing data from a SCIM-based Starling Connect connector

Once you configured a connection with the Generic SCIM Connector as described in Configuring the Generic SCIM Connector for Starling Connect connections, you can configure import-based data synchronization tasks to import data from the SCIM-based SuccessFactors HR and ServiceNow connectors of Starling Connect to another target system supported by Active Roles Synchronization Service.

The second step of creating this synchronization task is setting up a sync workflow based on the object mapping configured in Creating object mapping between a SCIM connection and an SQL connection. By configuring a workflow, you can automate creating, removing or deprovisioning specific data entries between the connected systems.

The following example procedure shows how to create a workflow that creates and updates data synchronization between:

  • A SuccessFactors HR database connected to Active Roles Synchronization Service with the Generic SCIM Connector. The SuccessFactors HR database will be the source system from which Active Roles Synchronization Service imports the data.

  • An SQL database connected to Active Roles Synchronization Service with the Microsoft SQL Server Connector. The SQL database will act as the target system to which Active Roles Synchronization Service will synchronize the SuccessFactors HR data.

Prerequisites

Before performing the procedure, make sure that the following conditions are met:

To configure a data sync workflow between a SuccessFactors HR database and an SQL database

  1. In Active Roles Synchronization Service, click Sync Workflows > Add sync workflow.

    Figure 17: Active Roles Active Roles Synchronization Service – Adding a new sync workflow

  2. In the Sync workflow name step, name the workflow (for example, SuccessFactors HR to SQL Server), then click OK.

    The new workflow then appears in the Sync Workflows tab.

  3. Configure a data synchronization creation step for the workflow. To do so, in Sync Workflows, click the name of the workflow (in this example, SuccessFactors HR to SQL Server), then click Add synchronization step.

    Figure 18: Active Roles Synchronization Service – Adding a new synchronization step

  4. In the Select an action step, select Creation, then click Next.

    The Creation step of the workflow will be used to create the synchronized data entries of the SuccessFactors HR database in the target SQL database. The Creation step performs data synchronization only for data entries that do not exist in the target system. Because of this, you typically run this step only once.

  5. In the Specify source and criteria step, configure the following settings:

    • Source connected system: Specify the SuccessFactors HR database connection here, created with the Generic SCIM Connector. To do so, click Specify > Select existing connected system, then select the SCIM-based connection (in this example, SCIM Connection to SuccessFactors HR).

    • Source object type: Specify the source object type here (in this example, the Employees object type). To do so, click Select, then in the Select Object Type window, select Employees, and click OK.

      TIP: If the data entry is hard to find due to the length of the list, use the Filter by name field to find it quicker.

    • (Optional) Creation Criteria: Specify additional conditions that the specified source object(s) must meet for synchronization in this workflow step. This setting is not used in this example.

  6. In the Specify target step, configure the following settings:

    • Target connected system: Specify the SQL Server connection here, created with the Microsoft SQL Server Connector. To do so, click Specify > Select existing connected system, then select the SQL Server connection (in this example, SQL Connection).

    • Target object type: Specify the target object type here. By default, when selecting an SQL Server connection in Target connected system, Active Roles Synchronization Service sets this setting to sql-Object, the object type used in this example.

  7. In the Specify creation rules step, configure the logic (called forward synchronization rules) that Active Roles Synchronization Service will use to perform first-time synchronization and copy data entries from the SuccessFactors HR database over to the target SQL database.

    To do so, specify one or more unique attributes that Active Roles Synchronization Service can use to link the corresponding data entries in the connected SuccessFactors HR and SQL data systems. In this example, four such SuccessFactors HR attributes are specified: userName, userId, emails.value and name.familyName.

    To specify these creation rules:

    1. Click Forward Sync Rule.

    2. Click Source item > Attribute, and in the Select Object Attribute window, search for the user name attribute in the SuccessFactors HR database (for example, userName), then click OK.

      TIP: If the data entry is hard to find due to the length of the list, use the Filter by name field to find it quicker.

    3. Click Target item > Attribute, and search for the applicable user name attribute pair in the SQL database (for example, userName), then click OK.

      TIP: If the data entry is hard to find due to the length of the list, use the Filter by name field to find it quicker.

      Figure 19: Active Roles Synchronization Service – Mapping attributes for a forward synchronization rule

    4. To apply the forward synchronization rule created for the specified user name attributes, click OK.

    5. To configure synchronization rules for the userId, emails.value and name.familyName SuccessFactors HR data entries too, click Forward Sync Rule again, and repeat the previous sub-steps by selecting the source and target attributes applicable to these data entries.

  8. Once all forward synchronization rules are configured, to finish configuring the Creation step, click Finish.

    Figure 20: Active Roles Synchronization Service – Finalizing all forward synchronization rules

    This creates the Creation step as the first step of the sync workflow.

    Figure 21: Active Roles Synchronization Service – Step 1 created for the SuccessFactors HR / SQL server workflow

  9. Now that the Creation step of the workflow is configured, configure the Update step. To do so, click Add synchronization step again.

    The Update step of the workflow will be used to update existing data entries mapped between the SuccessFactors HR database and the target SQL database. The Update step performs data synchronization only for existing data entries: it does not create new ones. Because of this, you typically run this step after running the Creation step, and run only the Update step later once the data entries have been created with the Creation step.

  10. In the Select an action step, select Update, then click Next.

  11. In the Specify source and criteria step, configure the following settings:

    • Source connected system: Specify the SuccessFactors HR database connection here, created with the Generic SCIM Connector. To do so, click Specify > Select existing connected system, then select the SCIM-based connection (in this example, SCIM Connection to SuccessFactors HR).

    • Source object type: Specify the source object type here (in this example, the Employees object type). To do so, click Select, then in the Select Object Type window, select Employees, and click OK.

      TIP: If the data entry is hard to find due to the length of the list, use the Filter by name field to find it quicker.

    • (Optional) Creation Criteria: Specify additional conditions that the specified source object(s) must meet for synchronization in this workflow step. This setting is not used in this example.

  12. In the Specify target step, configure the following settings:

    • Target connected system: Specify the SQL Server connection here, created with the Microsoft SQL Server Connector. To do so, click Specify > Select existing connected system, then select the SQL Server connection (in this example, SQL Connection).

    • Target object type: Specify the target object type here. By default, when selecting an SQL Server connection in Target connected system, Active Roles Synchronization Service sets this setting to sql-Object, the object type used in this example.

  13. In the Specify update rules step, configure the forward synchronization rules that Active Roles Synchronization Service will use to update existing data entries in the target SQL database from the SuccessFactors HR database. In this example, four such attributes are specified: userName, userId, SuccessFactors HR ID (displayed as sfid) and metadata information (displayed as meta).

    To specify these creation rules:

    1. Click Forward Sync Rule.

    2. Click Source item > Attribute, and in the Select Object Attribute window, search for the user name attribute in the SuccessFactors HR database (for example, userName), then click OK.

      TIP: If the data entry is hard to find due to the length of the list, use the Filter by name field to find it quicker.

    3. Click Target item > Attribute, and search for the applicable user name attribute pair in the SQL database (for example, userName), then click OK.

      TIP: If the data entry is hard to find due to the length of the list, use the Filter by name field to find it quicker.

    4. To apply the forward synchronization rule created for the specified user name attributes, click OK.

    5. To configure synchronization rules for the user ID, sfid and meta data entries too, click Forward Sync Rule again, and repeat the previous sub-steps by selecting the source and target attributes applicable to these data entries.

  14. Once all forward synchronization rules are configured, to finish configuring the Update step, click Finish. The configured workflow will appear, containing both steps.

  15. Start the workflow by clicking Run workflow. For the first-time run, select only Step 1 (Creation from SCIM Connection to SuccessFactors HR to SQL Connection), then select the running method:

    • Full Run fetches all data entries specified in the workflow steps directly from the source system. As such, One Identity recommends using this method when running the workflow the first time, even if the process takes longer than a Quick Run.

    • Quick Run uses cached data whenever possible, and is normally faster.

    The run may take several minutes to complete.

    Figure 22: Active Roles Synchronization Service – Running a configured sync workflow for the first time

  16. Once Active Roles Synchronization Service found all mapped objects, apply the synchronization changes by clicking Commit.

    Alternatively, to check detailed information about the processed objects, click the Processed objects number. The Objects processed in window then opens, listing all new data objects that Active Roles Synchronization Service will synchronize to the target SQL database.

Synchronizing complex multi-value objects from a SCIM source system

Data sync workflows that import data with a connection based on the Generic SCIM Connector can import all three types of SCIM 2.0-based data entries:

  • Simple attributes, that is, data entries with a single simple value. For example, a user ID specified in a single string is a simple attribute.

  • Complex single-value attributes, that is, data entries specified with several sub-attributes. For example, the following name attribute is a complex single-value attribute, specifying the name of an employee with three simple sub-attributes:

    "name": {
	"givenName": "Sam",
	"familyName": "Smith",
	"formatted": "Sam Smith"
	 },

    The value of complex single-value attributes is the sum of the sub-attribute values.

  • Complex multi-value attributes, that is, data entries with multiple complex values, each of them specified with several simple sub-attributes. For example, the following addresses attribute is a complex multi-value attribute, specifying several addresses, each of them being a complex value containing several simple sub-attributes:

    "addresses": [
	{
		"type": "work",
		"streetAddress": "22 Example Street",
		"region": "Springfield",
		"postalCode": "51487",
		"country": "United States",
		"primary": true
	},
	{
		"type": "home",
		"streetAddress": "12 Rue Exemple",
		"region": "Montreal",
		"postalCode": "46179",
		"country": "Canada"
	}
],

However, even though sync workflows using connections set with the Generic SCIM Connector can import all three of these value types, Active Roles Synchronization Service does not recognize complex single-value attributes and complex multi-value attributes, as they contain more values than what Active Roles Synchronization Service can identify for a single data entry by default.

To import complex single-value and multi-value attributes successfully, you can use the following methods:

  • For complex single-value attributes, you can map each individual sub-attribute of the complex single-value attribute to separate attributes in the target system. For example, in case of the name complex single-value attribute, you can map the givenName, familyName and formatted sub-attributes to separate name.givenName, name.familyName, and name.formatted attributes in the target system, respectively.

  • For complex multi-value attributes, you can use two methods:

    • When importing complex multi-value attributes, Active Roles Synchronization Service can take a single value (and its sub-attributes), map the sub-attributes to a set of target values (similarly to complex single-value attributes), then discard the rest of the complex values of the attribute.

      By default, Active Roles Synchronization Service takes the primary value of the complex multi-value attribute (marked with a specific primary sub-attribute). If no primary value is specified within the complex multi-value attribute, Active Roles Synchronization Service imports the first value (and its sub-attributes) only.

      NOTE: This method imports only the primary value (or the first value, if no primary value is specified). Active Roles Synchronization Service will discard all other values (and their sub-attributes).

    • If you map a complex multi-value attribute (such as the addresses attribute shown in the above example) when configuring a mapping rule for a workflow, you can configure an Active Roles Synchronization Service workflow to process and extract every value (and their sub-attributes) of the complex multi-value attribute with script-based attribute mapping.

      The following procedure will provide an example on how to apply such a PowerShell script to properly process the addresses complex multi-value attribute shown in this chapter.

To configure a custom PowerShell script for a workflow to import complex multi-value attributes

  1. In the Active Roles Synchronization Service, click Sync Workflow, then click the sync workflow that imports data from a SCIM-based source system (for example, the SuccessFactors HR to SQL Server workflow used in Creating a sync workflow for synchronizing data from a SCIM-based Starling Connect connector).

  2. Click the first step of the workflow (in the example SuccessFactors HR to SQL Server workflow, this is named Step 1 (Creation from SCIM Connection to SuccessFactors HR to SQL Connection).

  3. Under Creation Rules, to open the initial population rules, click Forward Sync Rule.

  4. In the Forward Sync Rule window, at the Source item setting, open the Attribute drop-down, and click PowerShell Script.

  5. In the PowerShell Script Editor, paste the following script example, and click OK:

    $addressesJsonArray = $srcObj["addresses"] | ConvertFrom-Json

if ($addressesJsonArray) {
  for ($i = 0; $i -lt $addressesJsonArray.Length; $i++) {
    if ($addressesJsonArray[$i].type -eq "work") {
      return $addressesJsonArray[$i].streetAddress + ", " + $addressesJsonArray[$i].region + ", " + $addressesJsonArray[$i].locality
	}
  }
}

    The example script contains the following key parts:

    • $srcObj refers to the source object that the script will act on.

    • $srcObj["addresses"] extracts the raw value of the addresses attribute. In this example, this attribute is a complex multi-value SCIM attribute, so the attribute value will be a JSON array.

    • $addressesJsonArray is a .NET array object containing the values of the complex multi-value attribute.

    The rest of the script performs the following steps:

    1. It checks that the array is valid.

    2. It traverses the elements of the array, and looks for the first element with a type sub-attribute with a work value.

    3. Once it finds an element with a work value type, it constructs a formatted string from the streetAddress, region and locality sub-attributes.

    4. It returns the results.

  6. Use the output to parse and extract the data into other target values in the target system.

Developing PowerShell scripts for attribute synchronization rules

You can configure synchronization rules for such steps as creating, deprovisioning, or update. Synchronization Service provides a user interface (Synchronization Service Console) that allows you to set up a direct or rules-based synchronization rule without any coding.

However, to set up a script-based synchronization rule, you must develop a Windows PowerShell script that will build values of the target object attributes using values of the source object attributes.

This section provides some reference materials on using the Windows PowerShell Script Host feature and provides the sample script.

Accessing source and target objects using built-in hash tables

Synchronization Service synchronizes data between the source and target objects using the pre-configured synchronization rules.

In the PowerShell scripts used to set up the script-based synchronization rules, you can employ the $srcObj and $dstObj built-in associative arrays (hash tables) that allow the scripts to access the current values of attributes of the source and target objects, respectively. The array keys names are names of the object attributes.

For more information about the use of the associative arrays, see the Microsoft PowerShell Documentation.

In addition to $srcObj and $dstObj, Synchronization Service defines the $Request built-in hash table. The $Request key names are also names of the object attributes. The $Request hash table contains new values of the target object attributes to which the target object attributes must be set after completing the synchronization process.

To clarify the use of built-in hash tables, let us consider the following scenario: you synchronize between the mail attributes of user objects in an LDAP directory (source connected system) and Active Roles Synchronization Service (target connected system) using the following synchronization rule: the value of the mail attribute in the target connected system must be equal to that in the source connected system concatenated with current date.

For example, before the synchronization process started, the source object had the mail attribute: JDoe@mail1.mycompany.com, the target object had the mail attribute: JDoe@mail2009.mycompany.com. After the synchronization process completes, the target user will have the following mail: JDoe@mail1.mycompany.com (5 December, 2012) (if you performed the synchronization process on 5 December, 2012.

The following code snippet illustrates the use of built-in hash tables:

#Returns "JDoe@mail1.mycompany.com
$strSourceMail=$srcObj["mail"]
#Returns JDoe@mail2009.mycompany.com
$strTargetMail=$DstObj["mail"]
#Returns JDoe@mail1.mycompany.com (5 January, 2010)
$strNewMail=$Request["mail"]

Example script

The following script illustrates the use of $srcObj.

A creating task (creating step of a sync workflow as applied to Synchronization Service) causes Synchronization Service to create user identity information from a delimited text file to Active Directory using the following creating rule: the co attribute in all created users must be set to the name of country where the user lives. The script-based creating rule calculates the co attribute value basing on the user's city (the City attribute in the connected data source).

The following script implements the described scenario:

# --- Retrieve the City attribute of the user object in connected data source.
$userCity = $srcObj["City"]
# --- Determine the user's country
switch ($UserCity)
{
"New York" {$country = "United States"; break}
"Paris" {$country = "France"; break}
"Tokyo" {$country = "Japan"; break}
default {$country = "Unknown"}
}
# --- Return the user country. The script-based creating rule
# --- assigns this value to the "co" attribute in the created user object.
$country
# End of the script
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating