了解转换（Transformation）

学习目标

描述转换的概念。

转换 — 概览

维护转换逻辑，使其与您的系统结构和逻辑相对应。

概览

对于 Identity Provisioning 服务支持的每个系统，都有一个初始（默认）转换逻辑，用于在实体的系统特定 JSON 表示与一种通用 JSON 之间进行双向转换。创建新系统并保存后，您可以在 Transformations 选项卡上看到它。您可以调整转换映射规则，以反映源系统或目标系统中实体的当前设置。

工作原理

在预配作业期间，源系统读取其实体，然后使用配置的读取转换将源系统特定的 JSON 转换为通用 JSON 格式。随后，该通用 JSON 格式被传递给目标系统，由目标系统应用写入转换。

Identity Provisioning 服务的管理员可以通过调整转换逻辑来改变此行为，使其只读取应预配到目标系统的实体。此过滤器可以加速实体的处理及其向目标系统的预配。

转换编辑器

Identity Provisioning 服务提供两种用于处理转换代码的编辑器：图形编辑器和 JSON（文本）编辑器。默认显示图形编辑器。

参数化系统转换

它们使用取自系统属性集的参数。参数由唯一键和值组成。与标准属性一样，它们可以在系统的 Properties 选项卡中和/或系统的目标（destination）属性（在平台 cockpit 中）中配置。当某个参数同时存在于两个属性集中时，系统属性优先于系统目标属性。

在 JSON 数据中，其中一个参数的唯一键由百分号 (%) 包围。在转换求值期间，每一次出现的 %<...>% 都会被替换为相应参数的值。没有值的参数引用保持不变——例如：

示例

LDAP 参数 — 列表	LDAP 参数 — 映射转换
ldap.attribute.user.mail=mail	示例代码代码片段复制代码`/* LDAP Server (source) system: */ { "sourcePath": "$.%ldap.attribute.user.mail%\[0\]", "targetPath": "$.emails\[0\].value", "optional": true }, { "sourcePath": "$.%ldap.attribute.user.givenName%\[0\]", "targetPath": "$.name.givenName", "optional": true },`展开
ldap.attribute.user.givenName=givenName
ldap.attribute.user.groups=memberOf

内部属性

注意

Identity Provisioning 在多种情况下使用内部属性。客户不得使用内部属性。

下表中展示了一个示例：

示例

属性名称	值
destinationName	在 SAP BTP cockpit 中创建的目标（destination）的名称

转换类型

了解预配作业所需的 JSON 转换类型。

上下文

在实体预配之前会发生两种类型的转换：

读取转换 ——从源系统到预配框架。它读取源系统中的数据，并将其传输到预配框架中的中间 JSON 数据。从源系统读取实体可以是完整的（全量读取）或部分的（增量读取）。
写入转换 ——从预配框架到目标系统。它准备要写入目标系统的数据。

两种转换都会产生 JSON 数据。

每个受支持的系统都保存并需要特定的 JSON 数据。要将源 JSON 数据转换为中间 JSON 版本（可用于转换为受支持的目标系统），Identity Provisioning 管理员可以使用 Transformations 选项卡上建议的 JSON 转换逻辑，并将其调整为所需的转换。

来自源系统的所有转换都会根据 System for Cross-domain Identity Management (SCIM 2.0) 规范，将其特定的 JSON 数据转换为中间数据。

注意

代理系统同时包含读取和写入转换。

转换示例

以下示例说明了转换的工作原理。

基本转换

基本转换将输入 JSON 消息中的所有属性复制到输出 JSON 消息中。

{
"sourcePath": "$",
"targetPath": "$"
},

源数据、中间数据和目标数据

在此示例中，源系统 JSON 数据包含 sn[0] 属性。

读取转换将此属性转换为中间 JSON 数据中的 name.familyName。然后，写入转换读取 name.familyName 属性，并将其映射到目标系统中的 name.familyName。

源实体数据（来自 Microsoft Active Directory）

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

读取转换（中间 JSON 数据）

{
"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)]"
},

...

写入转换（中间 JSON 数据）

{
"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"
},
...

目标实体数据（Identity Authentication 中的结果）

{
"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"
}
]
}

转换中的条件

在此示例中，您可以尝试针对实体的某个属性是否包含特定字符串来应用条件。

此类条件的模板如下：

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

其中：

=~ 表示将在条件中测试正则表达式 (regex)
/ 表示正则表达式的开始和结束
.* 表示任意符号

是您希望值包含的字符串的占位符

示例 1

通过此示例，您可以检查用户的第一个电子邮件地址是否包含特定域：

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

示例 2

通过此示例，您可以基于用户的 userName 是否包含特定字符串，将用户分配给某个组：

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

结果： 这会将所有 userName 中包含 "explorer" 的用户分配到 "Explorers" 组，并将所有 userName 中包含 "scifi" 的用户分配到 "Scientists" 组。

转换表达式

转换逻辑基于 JSON。文件中表达式的顺序决定了转换的执行方式。转换操作按转换逻辑中定义的顺序执行。

每个实体（用户、组或角色）都有不同的转换逻辑。

转换函数

函数是一段硬编码的转换逻辑，它接收由源路径或源变量指定的输入所表示的值。结果是，该值会相应地复制到目标路径或目标变量中。函数用于实体转换，并作为映射包含在内。

转换变量

系统变量指定所读取和写入实体的特定属性。它们帮助您在源转换和目标转换之间映射属性，以便实体正确地预配到目标系统。

转换编辑器

Identity Provisioning 提供图形编辑器和 JSON 编辑器，用于管理预配系统转换。

图形编辑器

此编辑器允许您以图形方式建模实体（用户、组、角色）及其内容（属性映射和转换表达式，如条件、函数、常量等）。它具有以下优势：

可视化：实体以彩色框组织。每个实体都有专属颜色。用户始终为蓝色，组为橙色，角色为绿色。源路径属性和目标路径属性水平显示（并排）。它们由箭头连接，指示数据读取和写入的方向。颜色编码便于识别特定配置。被忽略的实体以灰色显示，被跳过的操作和条件以橙色显示。
简化：除定义条件的情况外，不再需要键入代码和遵循 JSON 语法规则。表达式和函数及其可能的值已预填，并可在下拉列表中选择。编辑器会负责添加点表示法，即用句点 (.) 分隔子元素、将字符串值括在双引号中、在 JSONPath 表达式前添加美元符号 ($)。
校验： JSON 校验器和预览可确保输入符合预期格式。