Configure synchronization
To enable automated provisioning or even to import users from another system, we need to use the Synchronization functionality in OpenIAM. Synchronization is used for the following tasks:
- Importing data from source to OpenIAM
- Importing data from a source, bringing into OpenIAM, applying rules to enable downstream provisioning and deprovisioning.
At a high level, the synchronization engine is responsible for:
- Getting data from the connector or CSV file and bringing it into OpenIAM
- This can be done either on an ad-hoc basis or it can be a regularly scheduled task.
- Mapping the incoming data from the source to objects in the OpenIAM system
- Passing the incoming data to the provisioning service to update downstream systems.
Configure synchronization
To configure synchronization follow the steps below:
- Goto Webconsole -> Provisioning -> Synchronization
- Several examples have been provided to help you get started. If you are new to OpenIAM, then please leverage these examples instead of creating a new configuration. The steps below will describe how to create a new configuration.
- Click on
Create Synchronization. You will the screen below. Complete the form based on the table below.
| Field name | Description |
|---|---|
| Name | Descriptive value to identify this configuration. |
| Number of Threads | Set this value to 1, which is the default. This controls how many threads will be created to process data coming from the connector or CSV file. This is a performance optimization for processing large datasets. However, creating too many threads can take away resources from other operations and thereby have a negative impact. |
| Is active? | Flag which determines if the synchronization configuration can be executed. Making a configuration In-active is a way to disable the task. |
| Detect orphan | Orphan management should not be enabled for processing data from a source system. Orphan management is used to detect records in a target system which are not in source. This will be covered in detail in the Orphan management section |
| Provision to target systems | This flag enables down stream provisioning to target system. Once you have configured you synchronization and managed systems, you MUST enable this checkbox to allow for downstream provisioning. This checkbox provides an easy to stop downstream impact. |
| Synchronization source | Determine if you will be importing the data using connectors or from a CSV file. Based on this, select either 'CSV file' or the name of the connector. |
| Managed System | Indicates which managed system the user should automatically be added to. When implementing automated provisioning, this value should be set to OpenIAM as you will determine which managed system the user will be provisioned to in the synchronization scripts below. |
| Synchronization object | Defines the type of object that will be imported. Select User in this case. |
| Synch type | Allows you to define if this should be an incremental or complete synch. While developing your script, you can start with Complete. In production, it will be use to enable incremental sync if you are working with large datasets and your source system has an attribute similar to the whenChanged in LDAP to determine which objects have changed since the last time synchronization ran. |
| Synch Frequency | Describes how often the synchronization process should run, if you want it to running automatically. If this field has value new batch task will be created with name 'Synchronization=sync config name'. If task wasn't created check your cron expression, it has wrong format. The frequency is expressed as a CRON expression. A CRON expression is a string of 6 or 7 fields, separated by a white space, that represents a schedule. In this case, select Cron job. |
| Following expression shows how to run a task every 24 hours: 0 /24 * * ? | |
| Pre-processor script | Pre-processor script runs before synchronization starts. |
| Post-processor script | Post-processor script runs after synchronization has been completed. |
| Validation Rule | Groovy script to validate the incoming data from the file. |
| Transformation Implementation | This can be either based on a policy map or a transformation scripts (aka. Groovy script). Select Transformation Scripts |
| Transformation rule | Select the Groovy script which will be responsible for mapping data from the CSV file to objects which OpenIAM understands.A bulk of the work that is performed during synchronization stems from this script. The sections below describe how you can create your own transformation script. |
| IDM Repository Field | Field which uniquely identifies a user in OpenIAM. Select from one of the following: EMPLOYEE ID, IDM USER ID (internal guid), PRIMARY EMAIL ADDRESS, PRINCIPAL NAME. If these do not apply, then select CUSTOM ATTRIBUTE and enter the attribute name. |
| Source Attribute Name | Attribute name form your source (via connector and CSV) which uniquely identifies a user. |
| Custom Rule for Matching | In cases where its not possible to match on a single field, you can create a Custom match rule, using Groovy script, which will allow for more complex matching algorithms. |
| Attribute names lookup | When getting data from Connectors, the Attribute name lookup is a simple script which define the list of attributes from the source system which should be made available to the Transformation script. For example, if you are working with LDAP or Active Directory, you will only be able to map attributes in the transformation script which have first been defined in the Attribute names lookup script. |
| File Name | Name of the CSV file that has been uploaded. Use the Choose file button to upload the file. |
Develop Synchronization scripts
As you can see from the above configuration, there are several places in the synchronization framework where you can introduce custom Groovy scripts. These scripts provide an open framework that can be adapted to meet your business requirements.
Synchronization troubleshooting
The table below provides a description for common synchronization error messages that are captured in the OpenIAM audit logs to assist administrators with troubleshooting.
| Synchronization error message | Description |
|---|---|
| TRANSFORMATION_RETURN_SKIP | This is a response that is returned when specified conditions in the transformation groovy script that is called to populate the OpenIAM user object during synchronization fail to be met. By default, this response is triggered within a try-catch block in the execute method of the transformation script. |
| Unparseable date: "N" | This error is returned when the date attribute in an OpenIAM user object is unable to be assigned a value due to an incorrect format. Ensure the value for date from the source record is parsed by the transformation script. |
| DUPLICATE_PRINCIPAL | This error is returned when the synchronization process attempts to create a principal name that already exists. |
| INTERNAL_ERROR | Unspecified error. Administrators can troubleshoot by examining the synchronization logs. |
| VALIDATION_ERROR | This error is returned when criteria in the validation script is not met during synchronization, or if system validation for an attribute fails within OpenIAM (such as due to regex syntax, for example). |
| MATCH_ATTR_EMPTY | This error is returned when the matching attribute in the source record is empty. |