Exploring Transformations

For every system supported by the Identity Provisioning service, there is an initial (default) transformation logic that converts the system specific JSON representation of the entities from/to one common JSON. You can see it on the Transformations tab when you create a new system, after saving it. You can adjust the transformation mapping rules to reflect the current setup of entities from the source or target system.

During the provisioning job, the source system reads its entities, and then using the configured read transformation, converts the source system specific JSON to the common JSON format. This common JSON format is then passed to the target system, which applies the write transformation.

The administrator of the Identity Provisioning service can change this behavior by adapting the transformation logic to only read the entities that should be provisioned to the target system. This filter can speed up the processing of the entities and their provisioning to the target system.

The Identity Provisioning service provides two editors for working with the transformation code: graphical editor and JSON (text) editor. The graphical editor is displayed by default. You can switch between them on the Transformations tab.

Two types of transformations occur before the provisioning of entities:

1. Read Transformation – from the source system to the provisioning framework. It reads the data in the source system and transfers it to an intermediate JSON data in the provisioning framework. The reading of entities from the source system can be complete (full read) or partial (delta read).
2. Write Transformation – from the provisioning framework to the target system. It prepares the data to be written to the target system.

Both transformations result in JSON data.

Every supported system holds and requires specific JSON data. To convert the source JSON data to an intermediate JSON version (which can be used for transformation to a supported target system), the Identity Provisioning administrator can use the suggested JSON transformation logic on the Transformations tab and adapt it to the required transformation.

All transformations from the source systems transform their specific JSON data to intermediate data according to the System for Cross-domain Identity Management (SCIM 2.0) specification.

If the source JSON data contains the attribute name, the read transformation converts this attribute to name23 in the intermediate JSON data. Then, the write transformation should use the attribute name23 (instead of name) as the sourcePath attribute.

The following examples explain how transformations work.

The basic transformation copies all attributes from the input JSON messages to the output JSON ones.

With this example, you can check if the first email address of a user contains a particular domain:

With this example, you can assign a user to a group, based on their userName containing a particular string:

1234567891011

{
 "condition": "$.userName =~ /.*explorer.*/",
 "constant": "Explorers",
 "targetPath": "$.groups[0].value"
},
{
 "condition": "$.userName =~ /.*scifi.*/",
 "constant": "Scientists",
 "targetPath": "$.groups[1].value"
}

Result: This will assign all users, which have "explorer" in their userName, to the "Explorers" group, and all users, which contain "scifi" in their userName, to the "Scientists" group.

This editor allows you to graphically model the entities (users, groups, roles) and their content (attribute mappings and transformation expressions, like conditions, functions, constants, and others). It offers the following advantages:

• Visualization

  Entities are organized in colored boxes. Every entity has a dedicated color. Users are always blue, groups are orange, and roles are green. Source and target path attributes are displayed horizontally (side-by-side). They are connected with an arrow which indicates the direction of reading and writing the data. Color coding makes it easy to identify specific configurations. Ignored entities are greyed out, skipped operations and conditions are displayed in orange.

• Simplification

  Typing code and following JSON syntax rules are no longer needed, except in cases when conditions are defined. Expressions and functions along with their possible values are pre-filled and available for selection in dropdown lists. The editor takes care of adding the dot notation, that is, separating child elements with a period (.), enclosing string values within double quotes, prepending the dollar sign ($) to the JSONPath expression.

• Validation

  The JSON validator and the preview ensure that the input is in the expected format.

The following interactive screenshot shows the main elements of the graphical editor. Hover over the image and click the highlighted areas for more information.

The following example illustrates the means by which the address attribute mapping from the Identity Authentication write transformation is displayed in the graphical editor. Compare the same attribute with its representation in the JSON editor below.

The source path attribute addresses in the internal representation (on the left-hand side) and the target path attribute addresses in the target system (on the right-hand side) are displayed horizontally. The arrow shows the direction of reading and writing the data. The transformation expressions and functions are listed under the respective sourcePath and targetPath attribute for which they are applicable.