Exploring Transformations

Objectives

After completing this lesson, you will be able to:

  • Explore transformations
  • Use transformations

Transformations - Overview

Maintain the transformation logic, which corresponds to the structure and logic of your systems.

Overview

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.

How It Works

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.

Transformation Editors

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.

Transformation Types

Learn about the types of JSON transformations that are needed for the provisioning jobs.

Context

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.

Note

Proxy systems contain both Read and Write transformations.

Example

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.

Transformation Examples

The following examples explain how transformations work.

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

Code snippet
{
 "sourcePath": "$",
 "targetPath": "$"
},
Expand

Source, Intermediate, and Target Data

In this example, the source system JSON data contains the sn[0] attribute. The read transformation converts this attribute to name.familyName in the intermediate JSON data. Then, the write transformation reads the name.familyName attribute and maps it to name.familyName in the target system.

Source Entity Data (from Microsoft Active Directory)

Code snippet
{
 "sAMAccountName": ["jsmith"],
 "mail": ["john.smith@company.com"],
 "givenName": ["John"],
 "sn": ["Smith"],
 "memberOf": ["group1"],
 "memberOf_2": ["group21", "group22"],
 "memberOf_3": ["group31", "group32", "group33"]
}
Expand

Read Transformation (Intermediate JSON Data)

Code snippet

{
 "user": {
 "mappings": [

...

 {
 "sourcePath": "$.%ldap.attribute.user.id%[0]",
 "targetVariable": "entityIdSourceSystem",
 "correlationAttribute": true
 },
 {
 "condition": "('%ldap.attribute.user.id%' == '%ldap.attribute.dn%')",
 "constant": "",
 "targetVariable": "nestedPathRegex",
 "functions": [
 {
 "function": "concatString",
 "prefix": "(?i)cn=.*?,(.*?)",
 "suffix": ",%ldap.user.path%"
 }
 ]
 },
 {
 "condition": "('%ldap.attribute.user.id%' == '%ldap.attribute.dn%')",
 "sourcePath": "$.%ldap.attribute.user.id%[0]",
 "targetPath": "$['urn:sap:cloud:scim:schemas:extension:ad:2.0:User']['nestedPath']",
 "functions": [
 {
 "function": "getMatchedRegexGroup",
 "regex": "${nestedPathRegex}",
 "groupIndex": 1
 }
 ],
 "defaultValue": ""
 },
 {
 "sourcePath": "$.sAMAccountName[0]",
 "targetPath": "$.userName",
 "correlationAttribute": true
 },
 {
 "sourcePath": "$.displayName[0]",
 "optional": true,
 "targetPath": "$.displayName"
 },
 {
 "constant": "urn:ietf:params:scim:schemas:core:2.0:User",
 "targetPath": "$.schemas[0]"
 },
 {
 "sourcePath": "$.mail[0]",
 "optional": true,
 "targetPath": "$.emails[0].value",
 "correlationAttribute": true
 },
 {
 "sourcePath": "$.givenName[0]",
 "optional": true,
 "targetPath": "$.name.givenName"
 },
 {
 "sourcePath": "$.sn[0]",
 "optional": true,
 "targetPath": "$.name.familyName"
 },
 {
 "sourcePath": "$.memberOf",
 "preserveArrayWithSingleElement": true,
 "optional": true,
"targetPath": "$.groups[?(@.value)]"
},

...
Expand

Write Transformation (Intermediate JSON Data)

Code snippet

{
 "user": {
 "condition": "($.emails.length() > 0) && ($.name.familyName EMPTY false)",
 "mappings": [
 {
 "sourcePath": "$.groups",
 "preserveArrayWithSingleElement": true,
 "optional": true,
 "targetPath": "$.corporateGroups"
 },
 {
 "sourceVariable": "entityIdTargetSystem",
 "targetPath": "$.id"
 },
 {
 "constant": "urn:ietf:params:scim:schemas:core:2.0:User",
 "targetPath": "$.schemas[0]"
 },
 {
 "constant": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
 "targetPath": "$.schemas[1]"
 },
 {
 "sourcePath": "$.userName",
 "optional": true,
 "targetPath": "$.userName"
 },
 {
 "sourcePath": "$.emails[*].value",
 "preserveArrayWithSingleElement": true,
 "targetPath": "$.emails[?(@.value)]"
 },
 {
 "sourcePath": "$.userType",
 "optional": true,
 "targetPath": "$.userType"
 },
 {
 "sourcePath": "$.name.givenName",
 "optional": true,
 "targetPath": "$.name.givenName"
 },
 {
 "sourcePath": "$.name.middleName",
 "optional": true,
 "targetPath": "$.name.middleName"
 },
 {
 "sourcePath": "$.name.familyName",
 "optional": true,
 "targetPath": "$.name.familyName"
 },
 {
 "sourcePath": "$.displayName",
 "optional": true,
 "targetPath": "$.displayName"
 },
...
Expand

Target Entity Data (Result in Identity Authentication)

Code snippet

{
 "schemas": [
 "urn:ietf:params:scim:schemas:core:2.0:User",
 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
 ],
 "id": "P000100",
 "userName": "jsmith",
 "name": {
 "familyName": "Smith",
 "givenName": "John"
 },
 "emails": [
 {
 "value": "john.smith@company.com",
 "primary": "true",
 "type": "work"
 }
 ],
 "groups": [
 {
 "value": "group1"
 }
 ],
 "groups_2": [
 {
 "value": "group22"
 }
 ],
 "groups_3": [
 {
 "value": "group31"
 },
 {
 "value": "group32"
 },
 {
 "value": "group33"
 }
 ]
}
Expand

Conditions in Transformations

In this example, you can try to apply a condition on whether an attribute of an entity contains a particular string. The template for such condition is the following:

"condition": "$.<attribute> =~ /.*<text>.*/",

where:

  • =~ means that a regular expression (regex) will be tested in the condition
  • / represents the start and end of the regex
  • .* represents any symbol
  • <text> is a placeholder for the string that you want the value to contain

Example 1

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

"condition": "$.emails[0].value =~ /.*@example.com/",

Example 2

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

Code snippet

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

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.

Transformation Expressions

The transformation logic is based on JSON. The order of the expressions in the file is decisive for how the transformation is executed. The transformation actions are performed in the sequence defined in the transformation logic.

There is a different transformation logic for every entity (users, groups, or roles).

Note

A detailed list of transformation expressions is available on Transformation Expressions | SAP Help Portal (the link for which is here: https://help.sap.com/docs/IDENTITY_PROVISIONING/f48e822d6d484fa5ade7dda78b64d9f5/bb8537bd7ca445a591a1adaef4dee73a.html).

Consider that the links in the Online Documentation change frequently.

Transformation Functions

A function is a hard-coded piece of transformation logic that receives a value denoted by the input specified by a source path or a source variable. As a result, the value is replicated into the target path or target variable accordingly. Functions are used in entity transformations and are included as mappings.

Functions can also be chained, which means the output of one function is the input for the next one. See an example with such functions in the encode / decode section below.

Note
A detailed list of transformation expressions is available on Transformation Functions | SAP Help Portal (the link for which is here: https://help.sap.com/docs/IDENTITY_PROVISIONING/f48e822d6d484fa5ade7dda78b64d9f5/0cdac7ce593548d38b5a78dbf1bb444c.html).

Consider that the links in the Online Documentation change frequently.

Transformation Variables

System variables specify particular attributes of the read and written entities. They help you map attributes between source and target transformations so that the entities are provisioned correctly to the target systems.

Note

A detailed list of transformation expressions is available on Transformation Variables | SAP Help Portal (the link for which is here: https://help.sap.com/docs/IDENTITY_PROVISIONING/f48e822d6d484fa5ade7dda78b64d9f5/8376adbed2e94f04b99ec5cf01adf465.html).

Consider that the links in the Online Documentation change frequently.

Transformation Editors

Identity Provisioning provides the graphical and JSON text editor for managing provisioning system transformations.

Graphical Editor

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.

Note
The graphical editor is available only for Identity Provisioning tenants running on SAP Cloud Identity infrastructure. It is the default editor.

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.

JSON Editor

This editor allows you to work with entities and their transformation mappings in text mode. To add or modify transformations, you need to type. You can also perform operations like select, cut, copy, paste and others. The editor provides line numbering, syntax coloring and syntax validation.

The following example illustrates how the address attribute mapping from the Identity Authentication write transformation is displayed in the JSON editor:

The source path attribute addresses in the internal representation and the target path attribute addresses in the target system are displayed vertically - one below the other.

The transformation expressions and functions are listed in individual lines below the respective sourcePath and targetPath attribute for which they are applicable.

Syntax coloring and syntax validation are enabled by default.

Although the graphical and the JSON editors differ in the user experience they provide, other tasks, such as export and reset transformations, remain the same.

Target System Transformations

Source: Activate the following video and audio to learn about how to access the transformations available in a system of type source.

Proxy:

Target: Activate the following video and audio to learn about how to access the transformations available in a system of type Target.

Log in to track your progress & complete quizzes