有关在 Microsoft Entra ID 中编写特性映射表达式的参考

将预配配置到 SaaS 应用程序时,表达式映射是可指定的属性映射类型之一。 对于这些映射,你必须编写一个类似于脚本的表达式,才能将用户的数据转换为 SaaS 应用程序更能接受的格式。

语法概述

属性映射的表达式语法让人联想到 Visual Basic for Applications (VBA) 函数。

  • 整个表达式必须按函数来定义,名称后接带括号的自变量:FunctionName(<<argument 1>>,<<argument N>>)

  • 函数之间可以相互嵌套。 例如:FunctionOne(FunctionTwo(<<argument1>>))

  • 可以将三种不同类型的参数传递给函数:

    1. 属性,必须括在方括号中。 例如:[attributeName]
    2. 字符串常量必须括在双引号内。 例如:"美国"
    3. 其他函数。 例如:FunctionOne(<<argument1>>, FunctionTwo(<<argument2>>))
  • 对于字符串常量,如果字符串中需要反斜杠 ( \ ) 或引号 ( " ),则必须使用反斜杠 ( \ ) 符号进行转义。 例如 "Company name: \"Contoso\""

  • 语法区分大小写,在函数中以字符串形式键入或者从此处直接复制粘贴时,必须考虑到这一点。

函数列表

AppendAppRoleAssignmentsComplexBitAndCBoolCDateCoalesceConvertToBase64ConvertToUTF8HexCountCStrDateAddDateDiffDateFromNumFormatDateTimeGuidIgnoreFlowIfNullOrEmptyIIFInStrIsNullIsNullOrEmptyIsPresentIsStringItemJoinLeftMidNormalizeDiacriticsNotNowNumFromDatePCaseRandomStringRedactRemoveDuplicatesReplaceSelectUniqueValueSingleAppRoleAssignmentSplitStripSpacesSwitchToLowerToUpperWord


附加

函数:Append(source, suffix)

说明:取源字符串值,并将后缀追加到其末尾。

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是来自源对象的属性的名称。
suffix 必须 String 要附加到源值末尾的字符串。

将常量后缀附加到用户名

示例:如果使用 Salesforce 沙盒,可能需要先向你的所有用户名追加其他后缀,然后才对其进行同步。

表达式:Append([userPrincipalName], ".test")

示例输入/输出:

  • 输入:(userPrincipalName):“John.Doe@contoso.com”
  • 输出:“John.Doe@contoso.com.test”

AppRoleAssignmentsComplex

函数:AppRoleAssignmentsComplex([appRoleAssignments])

说明:用于为一个用户配置多个角色。 有关详细使用情况,请参阅教程 - 为 Microsoft Entra ID 中的 SaaS 应用程序自定义用户预配属性映射

参数:

名称 必选/重复 类型 说明
[appRoleAssignments] 必须 String [appRoleAssignments] 对象。

BitAnd

函数:BitAnd(value1, value2)

说明:此函数将两个参数转换为二进制表示形式,并将一个位设置为:

  • 0 - 如果 value1 和 value2 中的一个或两个相应位为 0
  • 1 - 如果两个相应位均为 1。

换而言之,除了当两个参数的相应位均为 1 时之外,所有情况下均返回 0。

参数:

名称 必选/重复 类型 注释
value1 必需 编号 应与 value2 进行 AND 运算的数字值
value2 必需 编号 应与 value1 进行 AND 运算的数字值

示例:BitAnd(&HF, &HF7)

11110111 AND 00000111 = 00000111,因此 BitAnd 返回 7,即 00000111 的二进制值。


CBool

函数:CBool(Expression)

说明:CBool 基于求值的表达式返回布尔值。 如果该表达式求值为非零值,则 CBool 返回 True,否则返回 False 。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 任何有效表达式

示例:CBool([attribute1] = [attribute2])
如果两个属性具有相同的值,则返回 True。


CDate

函数:
CDate(expression)

说明:
CDate 函数通过字符串返回 UTC DateTime。 DateTime 不是原生属性类型,但可用在 FormatDateTimeDateAdd 等日期函数内。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 表示日期/时间的任何有效字符串。 有关支持的格式,请参阅 .NET 自定义日期和时间格式字符串

备注:
返回的字符串始终采用 UTC 形式,采用 M/d/yyyy h:mm:ss tt 格式。

示例 1:
CDate([StatusHireDate])
示例输入/输出:

  • 输入 (StatusHireDate):“2020-03-16-07:00”
  • 输出:“3/16/2020 7:00:00 AM”<-- 注意,将返回上述日期/时间的 UTC 等效日期/时间

示例 2:
CDate("2021-06-30+08:00")
示例输入/输出:

  • 输入:“2021-06-30+08:00”
  • 输出:“6/29/2021 4:00:00 PM”<-- 注意,将返回上述日期/时间的 UTC 等效日期/时间

示例 3:
CDate("2009-06-15T01:45:30-07:00")
示例输入/输出:

  • 输入:“2009-06-15T01:45:30-07:00”
  • 输出:“6/15/2009 8:45:30 AM”<-- 注意,将返回上述日期/时间的 UTC 等效日期/时间

Coalesce

函数:Coalesce(source1, source2, ..., defaultValue)

说明:返回非 NULL 的第一个源值。 如果所有自变量均为 NULL 且 defaultValue 存在,则会返回 defaultValue。 如果所有自变量均为 NULL 且 defaultValue 不存在,则 Coalesce 返回 NULL。

参数:

名称 必选/重复 类型 说明
source1 … sourceN 必须 String 必需,次数可变。 通常是来自源对象的属性的名称。
defaultValue 可选 String 当所有源值为 NULL 时要使用的默认值。 可以是空字符串 ("")。

如果不为 NULL,则传送 mail 值,否则传送 userPrincipalName

示例:你希望在 mail 特性存在时传送该特性。 如果该属性不存在,你希望改为传送 userPrincipalName 的值。

表达式:Coalesce([mail],[userPrincipalName])

示例输入/输出:

  • 输入 (mail): NULL
  • 输入 (userPrincipalName): "John.Doe@contoso.com"
  • 输出:“John.Doe@contoso.com”

ConvertToBase64

函数:ConvertToBase64(source)

说明:ConvertToBase64 函数将字符串转换为 Unicode base64 字符串。

参数:

名称 必选/重复 类型 注释
source 必须 String 要转换为 base64 的字符串

示例:ConvertToBase64("Hello world!")

返回 "SABlAGwAbABvACAAdwBvAHIAbABkACEA"


ConvertToUTF8Hex

函数:ConvertToUTF8Hex(source)

说明:ConvertToUTF8Hex 函数将字符串转换为 UTF8 十六进制编码值。

参数:

名称 必选/重复 类型 注释
source 必须 String 要转换为 UTF8 十六进制值的字符串

示例:ConvertToUTF8Hex("Hello world!")

返回 48656C6C6F20776F726C6421


计数

函数:Count(attribute)

说明:Count 函数返回多值特性中的元素数目。

参数:

名称 必选/重复 类型 注释
attribute 必需 attribute 统计了元素数目的多值特性

CStr

函数:CStr(value)

说明:CStr 函数将值转换为字符串数据类型。

参数:

名称 必选/重复 类型 注释
value 必须 数字、引用或布尔值 可以是数字值、引用属性或布尔值。

示例:CStr([dn])

返回“cn=Joe,dc=contoso,dc=com”


DateAdd

函数:
DateAdd(interval, value, dateTime)

说明:
返回一个日期/时间字符串,表示某个已添加指定时间间隔的日期。 返回的日期采用以下格式:M/d/yyyy h:mm:ss tt。

参数:

名称 必选/重复 类型 说明
interval 必须 字符串 要添加的时间间隔。 请参阅此表后面的可接受值。
value 必须 Number 要添加的单位数。 它可以是正值(以获取将来的日期)或负值(以获取过去的日期)。
dateTime 必需 DateTime 表示间隔添加到其中的日期的 DateTime。

将日期字符串作为输入传递时,请使用 CDate 函数包装日期/时间字符串。 若要获取 UTC 格式的系统时间,请使用 Now 函数。

间隔字符串必须具有下列值之一:

  • yyyy Year
  • m Month
  • d Day
  • ww Week
  • h Hour
  • n Minute
  • s Second

示例 1:基于 Workday 传入的 StatusHireDate 生成日期值
DateAdd("d", 7, CDate([StatusHireDate]))

示例 interval value dateTime(变量 StatusHireDate 的值) 输出
添加 7 天雇用日期 "d" 7 2012-03-16-07:00 3/23/2012 7:00:00 AM
获取雇用日期前 10 天的日期 "d" -10 2012-03-16-07:00 3/6/2012 7:00:00 AM
添加 2 周雇用日期 "ww" 2 2012-03-16-07:00 3/30/2012 7:00:00 AM
添加 10 个月雇用日期 “m” 10 2012-03-16-07:00 1/16/2013 7:00:00 AM
添加 2 年雇用日期 “yyyy” 2 2012-03-16-07:00 3/16/2014 7:00:00 AM

DateDiff

函数:
DateDiff(interval, date1, date2)

描述:
此函数使用 interval 参数返回一个数字,该数字表示两个输入日期之间的差异。 返回

  • 正数(如果 date2 > date1),
  • 负数(如果 date2 < date1),
  • 0(如果 date2 == date1)

参数:

名称 必需/可选 类型 说明
interval 必须 字符串 用于计算差值的时间间隔。
date1 必需 DateTime 表示有效日期的日期/时间。
date2 必需 DateTime 表示有效日期的日期/时间。

将日期字符串作为输入传递时,请使用 CDate 函数包装日期/时间字符串。 若要获取 UTC 格式的系统时间,请使用 Now 函数。

间隔字符串必须具有下列值之一:

  • yyyy Year
  • m Month
  • d Day
  • ww Week
  • h Hour
  • n Minute
  • s Second

示例 1:将当前日期与 Workday 中具有不同间隔的雇佣日期进行比较
DateDiff("d", Now(), CDate([StatusHireDate]))

示例 interval date1 date2 output
两个日期之间的正数差(以天为单位) d 2021-08-18+08:00 2021-08-31+08:00 13
两个日期之间的负数差(以天为单位) d 2021/8/25 晚上 5:41:18 2012-03-16-07:00 -3449
两个日期之间的差值(以周为单位) ww 2021/8/25 晚上 5:41:18 2012-03-16-07:00 -493
两个日期之间的差值(以月为单位) m 2021/8/25 晚上 5:41:18 2012-03-16-07:00 -113
两个日期之间的差值(以年为单位) yyyy 2021/8/25 晚上 5:41:18 2012-03-16-07:00 -9
两个日期相同时的差值 d 2021-08-31+08:00 2021-08-31+08:00 0
两个日期之间的差值(以小时为单位) h 2021-08-24 2021-08-25 24
两个日期之间的差值(以分钟为单位) n 2021-08-24 2021-08-25 1440
两个日期之间的差值(以秒为单位) s 2021-08-24 2021-08-25 86400

示例 2:将 DateDiff 与 IIF 函数合并用于设置属性值
如果一个帐户在 Workday 中处于活动状态,则仅当雇用日期的范围在接下来的 5 天内时,才将用户的 accountEnabled 属性设置为 True。

Switch([Active], , 
  "1", IIF(DateDiff("d", Now(), CDate([StatusHireDate])) > 5, "False", "True"), 
  "0", "False")

DateFromNum

函数:DateFromNum(value)

说明:DateFromNum 函数将 AD 日期格式的值转换为日期/时间类型。

参数:

名称 必选/重复 类型 注释
value 必须 Date 要转换为日期/时间类型的 AD 日期

示例:DateFromNum([lastLogonTimestamp])

DateFromNum(129699324000000000)

返回表示 2012 年 1 月 1 日 11:00PM 的日期/时间。


FormatDateTime

函数:FormatDateTime(source, dateTimeStyles, inputFormat, outputFormat)

说明:取一种格式的日期字符串并将其转换为不同的格式。

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是来自源对象的属性的名称。
dateTimeStyles 可选 字符串 使用此参数可以指定格式设置选项,这些选项可自定义用于某些日期和时间分析方法的字符串分析。 有关支持的值,请参阅 DateTimeStyles 文档。如果留空,则使用的默认值为 DateTimeStyles.RoundtripKind, DateTimeStyles.AllowLeadingWhite, DateTimeStyles.AllowTrailingWhite
inputFormat 必须 String 源值的预期格式。 有关支持的格式,请参阅 .NET 自定义日期和时间格式字符串
outputFormat 必须 String 输出日期的格式。

输出日期是一种特定格式的字符串

示例:你想要以特定格式将日期发送到 ServiceNow 等 SaaS 应用程序。 可以考虑使用以下表达式。

表达式:

FormatDateTime([extensionAttribute1], , "yyyyMMddHHmmss.fZ", "yyyy-MM-dd")

示例输入/输出:

  • 输入 (extensionAttribute1):“20150123105347.1Z”
  • 输出:“2015-01-23”

Guid

函数:Guid()

说明:函数 Guid 生成新的随机 GUID

示例:
Guid()
示例输出:"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"


IgnoreFlowIfNullOrEmpty

函数:IgnoreFlowIfNullOrEmpty(expression)

说明:如果包含的函数或属性为 NULL 或为空,则 IgnoreFlowIfNullOrEmpty 函数会指示预配服务忽略属性,并将其从流中删除。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 要对其求值的表达式

示例 1:如果特性为 null,则不流式传输该特性
IgnoreFlowIfNullOrEmpty([department])
如果部门特性为 null 或为空,则上述表达式将从预配流中删除该特性。

示例 2:如果表达式映射的计算结果为空字符串或 null,则不流式传输属性
假设 SuccessFactors 属性 prefix 通过以下表达式映射映射到本地 Active Directory 属性 personalTitle
IgnoreFlowIfNullOrEmpty(Switch([prefix], "", "3443", "Dr.", "3444", "Prof.", "3445", "Prof. Dr."))
上述表达式将首先计算 Switch 函数的结果。 如果 前缀 特性没有 Switch 函数内列出的任何值,则 ** 将返回一个空字符串,并且 personalTitle 特性不会包括在本地 Active Directory 的预配流中。


IIF

函数:IIF(condition,valueIfTrue,valueIfFalse)

说明:IIF 函数基于指定的条件返回一组可能值中的一个。

参数:

名称 必选/重复 类型 注释
条件 必需 变量或表达式 计算结果为 true 或 false 的任何值或表达式。
valueIfTrue 必需 变量或字符串 如果条件计算结果为 true,则为返回值。
valueIfFalse 必需 变量或字符串 如果条件计算结果为 false,则为返回值。

以下比较运算符可在以下条件中使用:

  • 等于 (=) 且不等于 (<>)
  • 大于 (>),且大于等于 (>=)
  • 小于 (<),且小于等于 (<=)

示例:如果“国家/地区 = 美国”,则将目标属性值设为“源国家/地区”属性,否则设为“源部门”属性。 IIF([country]="USA",[country],[department])

已知限制

本部分包括 IIF 函数的限制和解决方法。 有关排查用户创建问题的信息,请参阅创建因 null 值/空值而失败

  • IIF 函数当前不支持 AND 和 OR 逻辑运算符。
  • 若要实现 AND 逻辑,请使用沿 trueValue 路径链接的嵌套 IIF 语句。 示例:如果“国家/地区 = 美国”且“省/市/自治区 = 加州”,则返回值“True”,否则返回“False”。 IIF([country]="USA",IIF([state]="CA","True","False"),"False")
  • 若要实现 OR 逻辑,请使用沿 falseValue 路径链接的嵌套 IIF 语句。 示例:如果“国家/地区 = 美国”或“省/市/自治区 = 加州”,则返回值“True”,否则返回“False”。 IIF([country]="USA","True",IIF([state]="CA","True","False"))
  • 如果在 IIF 函数内使用的源属性为空或 null,则将无法进行条件检查。
    • 不支持的 IIF 表达式示例:
      • IIF([country]="","Other",[country])
      • IIF(IsNullOrEmpty([country]),"Other",[country])
      • IIF(IsPresent([country]),[country],"Other")
    • 建议的解决方法:使用 Switch 函数检查是否有空值/null 值。 示例:如果国家/地区属性为空,则将值设置为“其他”。 如有国家/地区特性值,则将其传递到目标特性。
      • Switch([country],[country],"","Other")

InStr

函数:InStr(value1, value2, start, compareType)

说明:InStr 函数查找字符串中第一次出现的某个子字符串。

参数:

名称 必选/重复 类型 注释
value1 必须 String 要在其中进行搜索的字符串
value2 必须 String 要查找的字符串
start 可选 整数 查找子字符串时使用的起始位置
compareType 可选 枚举 可为 vbTextCompare 或 vbBinaryCompare

示例:InStr("The quick brown fox","quick")

求值为 5

InStr("repEated","e",3,vbBinaryCompare)

计算结果为 7


IsNull

函数:IsNull(Expression)

说明:如果表达式求值为 Null,则 IsNull 函数返回 true。 对于属性,Null 表示缺少属性。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 要对其求值的表达式

示例:IsNull([displayName])

如果该属性不存在,则返回 True。


IsNullorEmpty

函数:IsNullOrEmpty(Expression)

说明:如果表达式为 null 或空字符串,则 IsNullOrEmpty 函数返回 true。 如果特性不存在,或存在但为空字符串,其计算结果为 True。 此函数的逆函数命名为 IsPresent。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 要对其求值的表达式

示例:IsNullOrEmpty([displayName])

如果该属性不存在,或者为空字符串,则返回 True。


IsPresent

函数:IsPresent(Expression)

说明:如果表达式求值为非 Null 且非空的字符串,则 IsPresent 函数返回 true。 此函数的逆函数被命名为 IsNullOrEmpty。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 要对其求值的表达式

示例:Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])


IsString

函数:IsString(Expression)

说明:如果表达式的值可为字符串类型,则 IsString 函数的值为 True。

参数:

名称 必选/重复 类型 说明
表达式 必需 表达式 要对其求值的表达式

函数:Item(attribute, index)

说明:Item 函数返回多值字符串/特性中的一个项。

参数:

名称 必选/重复 类型 注释
attribute 必需 属性 要搜索的多值特性。
index 必需 整数 多值字符串中某个项的索引

示例:Item([proxyAddresses], 1) 返回多值特性中的第一个项。 不得使用索引 0。


加入

函数:Join(separator, source1, source2, …)

说明:Join() 类似于 Append(),只不过它可以将多个源字符串值合并到单个字符串中,每个值由分隔符字符串分隔

如果其中一个源值是多值特性,那么该特性中的每个值都联接在一起,由分隔符值分隔。

参数:

名称 必选/重复 类型 说明
separator 必须 字符串 用于在将源值连接为一个字符串时分隔源值的字符串。 如果不需要分隔符,则可以是 ""。
source1 … sourceN 必选,次数可变 字符串 要联接在一起的字符串值。

Left

函数: Left(String, NumChars)

说明:Left 函数从字符串左侧起返回指定数量的字符。 如果 numChar = 0,则返回空字符串。 如果 numChars < 0,则返回输入字符串。 如果字符串为 null,则返回空字符串。 如果字符串包含的字符数比 numChars 中指定的数量少,则返回与该字符串相同的字符串(即,包含参数 1 中的所有字符)。

参数:

名称 必选/重复 类型 注释
字符串 必需 属性 要从中返回字符的字符串
NumChars 必需 整数 一个数字,用于指示要从字符串开头(左侧)返回的字符数

示例:Left("John Doe", 3)

返回 “Joh”。


Mid

函数:Mid(source, start, length)

说明:返回源值的子字符串。 子字符串是一个只包含源字符串中某些字符的字符串。

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是属性的名称。
start 必需 整数 source 字符串中的索引,子字符串应从这里开始。 字符串中第一个字符的索引为 1,第二个字符的索引为 2,依此类推。
length 必需 整数 子字符串的长度。 如果长度超出 source 字符串,则函数将返回从 start 索引到 source 字符串末尾的子字符串

NormalizeDiacritics

函数:NormalizeDiacritics(source)

说明:需要一个字符串自变量。 返回字符串,但将任何标注字符替换为等效的非标注字符。 通常用于将包含标注字符(重音符号)的名字和姓氏转换为可用于各种用户标识符(例如用户主体名称、SAM 帐户名称和电子邮件地址)的合法值。

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是名字或姓氏属性。
带有音调符号的字符 规范化字符 带有音调符号的字符 规范化字符
ä, à, â, ã, å, á, ą, ă, ā, ā́, ā̀, ā̂, ā̃, ǟ, ā̈, ǡ, a̱, å̄ a Ä, À, Â, Ã, Å, Á, Ą, Ă, Ā, Ā́, Ā̀, Ā̂, Ā̃, Ǟ, Ā̈, Ǡ, A̱, Å̄ A
æ, ǣ ae Æ, Ǣ AE
ç, č, ć, c̄, c̱ c Ç, Č, Ć, C̄, C̱ C
ď, d̄, ḏ d Ď, D̄, Ḏ D
ë, è, é, ê, ę, ě, ė, ē, ḗ, ḕ, ē̂, ē̃, ê̄, e̱, ë̄, e̊̄ e Ë, È, É, Ê, Ę, Ě, Ė, Ē, Ḗ, Ḕ, Ē̂, Ē̃, Ê̄, E̱, Ë̄, E̊̄ E
ğ, ḡ, g̱ g Ğ, Ḡ, G̱ G
ï, î, ì, í, ı, ī, ī́, ī̀, ī̂, ī̃, i̱ i Ï, Î, Ì, Í, İ, Ī, Ī́, Ī̀, Ī̂, Ī̃, I̱ I
ľ, ł, l̄, ḹ, ḻ l Ł, Ľ, L̄, Ḹ, Ḻ L
ñ, ń, ň, n̄, ṉ n Ñ, Ń, Ň, N̄, Ṉ N
ö, ò, ő, õ, ô, ó, ō, ṓ, ṑ, ō̂, ō̃, ȫ, ō̈, ǭ, ȭ, ȱ, o̱ o Ö, Ò, Ő, Õ, Ô, Ó, Ō, Ṓ, Ṑ, Ō̂, Ō̃, Ȫ, Ō̈, Ǭ, Ȭ, Ȱ, O̱ O
ø, ø̄, œ̄ oe Ø, Ø̄, Œ̄ OE
ř, r̄, ṟ, ṝ r Ř, R̄, Ṟ, Ṝ R
ß ss
š, ś, ș, ş, s̄, s̱ s Š, Ś, Ș, Ş, S̄, S̱ S
ť, ț, t̄, ṯ t Ť, Ț, T̄, Ṯ T
ü, ù, û, ú, ů, ű, ū, ū́, ū̀, ū̂, ū̃, u̇̄, ǖ, ṻ, ṳ̄, u̱ u Ü, Ù, Û, Ú, Ů, Ű, Ū, Ū́, Ū̀, Ū̂, Ū̃, U̇̄, Ǖ, Ṻ, Ṳ̄, U̱ U
ÿ, ý, ȳ, ȳ́, ȳ̀, ȳ̃, y̱ y Ÿ, Ý, Ȳ, Ȳ́, Ȳ̀, Ȳ̃, Y̱ Y
ź, ž, ż, z̄, ẕ z Ź, Ž, Ż, Z̄, Ẕ Z

从字符串中删除音调符号

示例:将包含重音符号的字符替换为不包含重音符号的等效字符。

表达式:NormalizeDiacritics([givenName])

示例输入/输出:

  • 输入 (givenName):“Zoë”
  • 输出:“Zoe”

Not

函数:Not(source)

说明:对 source 的布尔值取反。 如果 source 值为 True,则返回 False。 否则返回 True。

参数:

名称 必选/重复 类型 注释
source 必需 布尔型字符串 预期的 source 值为“True”或“False”。

Now

函数:Now()

描述:
Now 函数返回表示当前 UTC DateTime 的字符串,格式为 M/d/yyyy h:mm:ss tt。

示例:Now()
返回的示例值:7/2/2021 3:33:38 PM


NumFromDate

函数:NumFromDate(value)

说明: NumFromDate 函数将日期/时间值转换为 Active Directory 格式,设置 accountExpires 等特性时必须采用此格式。 使用此函数可将从云 HR 应用(例如 Workday 和 SuccessFactors)收到的日期/时间值转换为其等效的 AD 表示形式。

参数:

名称 必选/重复 类型 注释
value 必须 字符串 采用 ISO 8601 格式的日期时间字符串。 如果日期变量采用其他格式,请使用 FormatDateTime 函数将日期转换为 ISO 8601 格式。

示例:

  • Workday 示例:假设你要将 Workday 中采用 2020-12-31-08:00 格式的 ContractEndDate 特性映射到 AD 中的 accountExpires 字段,那你可以按下面的方式使用此函数并更改时区偏差,使之与你的区域设置相匹配NumFromDate(Join("", FormatDateTime([ContractEndDate], ,"yyyy-MM-ddzzz", "yyyy-MM-dd"), " 23:59:59-08:00"))

  • SuccessFactors 示例:假设你要将 SuccessFactors 中采用 M/d/yyyy hh:mm:ss tt 格式的 endDate 特性映射到 AD 中的 accountExpires 字段,那你可以按下面的方式使用此函数并更改时区偏差,使之与你的区域设置相匹配NumFromDate(Join("",FormatDateTime([endDate], ,"M/d/yyyy hh:mm:ss tt","yyyy-MM-dd")," 23:59:59-08:00"))


PCase

函数:PCase(source, wordSeparators)

说明:PCase 函数将字符串中每个单词的第一个字符转换为大写形式,并将所有其他字符转换为小写形式。

参数:

名称 必需/可选 类型 注释
source 必须 字符串 要转换为正确大小写的源值。
wordSeparators 可选 字符串 指定一组用作单词分隔符的字符(示例:“,-'”)

备注:

  • 如果未指定 wordSeparators 参数,则 PCase 将在内部调用 .NET 函数 ToTitleCase 将源字符串转换为正确的大小写。 .NET 函数 ToTitleCase 支持全面的一组 Unicode 字符类别作为单词分隔符。
    • 空格字符
    • 换行符
    • 控制字符,例如 CRLF
    • 格式控制字符
    • ConnectorPunctuation 字符,例如下划线
    • DashPunctuation字符,例如破折号和连字符(包括短破折号、长破折号、双连字符等字符)
    • 成对出现的 OpenPunctuation 和 ClosePunctuation 字符,例如圆括号、大括号、尖括号等
    • InitialQuotePunctuation 和 FinalQuotePunctuation 字符,例如单引号、双引号和角引号
    • OtherPunctuation 字符,例如感叹号、数字符号、百分号、& 号、星号、逗号、句号、冒号、分号等
    • MathSymbol 字符,例如加号、小于号、大于号、竖线、波浪号、等号等
    • CurrencySymbol 字符,例如美元符号、美分符号、英镑符号、欧元符号等
    • ModifierSymbol 字符,例如长音符号、重音符号、箭头等
    • OtherSymbol 字符,例如版权符号、度符号、注册符号等
  • 如果指定了 wordSeparators 参数,则 PCase 只会使用指定为单词分隔符的字符。

示例:

假设你要从 SAP SuccessFactors 寻找属性 firstName 和 lastName,而在 HR 中,这两个属性都采用大写。 使用 PCase 函数,可以将名称转换为正确的大小写,如下所示。

Expression 输入 输出 说明
PCase([firstName]) firstName = "PABLO GONSALVES (SECOND)" "Pablo Gonsalves (Second)" 由于未指定 wordSeparators 参数,PCase 函数将使用默认的单词分隔符字符集。
PCase([lastName]," '-") lastName = "PINTO-DE'SILVA" "Pinto-De'Silva" PCase 函数使用 wordSeparators 参数中的字符来识别单词,将其转换为正确的大小写 。
PCase(Join(" ",[firstName],[lastName])) firstName = GREGORY, lastName = "JAMES" "Gregory James" 可以在 PCase 中嵌套 Join 函数。 由于未指定 wordSeparators 参数,PCase 函数将使用默认的单词分隔符字符集。

RandomString

函数:RandomString(Length, MinimumNumbers, MinimumSpecialCharacters, MinimumCapital, MinimumLowerCase, CharactersToAvoid)

说明: RandomString 函数根据指定的条件生成随机字符串。 可在此处确定允许的字符。

参数:

名称 必选/重复 类型 说明
时长 必须 Number 随机字符串的总长度。 这应该大于或等于 MinimumNumbers、MinimumSpecialCharacters 和 MinimumCapital 的总长度。 最多 256 个字符。
MinimumNumbers 必须 Number 随机字符串的最小数目。
MinimumSpecialCharacters 必须 Number 特殊字符的最小数目。
MinimumCapital 必须 Number 随机字符串中大写字母的最小数目。
MinimumLowerCase 必须 Number 随机字符串中小写字母的最小数目。
CharactersToAvoid 可选 String 生成随机字符串时要排除的字符。

示例 1: - 生成无特殊字符限制的随机字符串:RandomString(6,3,0,0,3)生成包含 6 个字符的随机字符串。 字符串包含 3 个数字和 3 个小写字符 (1a73qt)。

示例 2: - 生成有特殊字符限制的随机字符串:RandomString(10,2,2,2,1,"?,")生成包含 10 个字符的随机字符串。 字符串至少包含 2 个数字、2 个特殊字符、2 个大写字母、1 个小写字母,并排除字符“?”和“,”(例如 1@!2BaRg53)。


Redact

函数:Redact()

说明:Redact 函数将预配日志中的属性值替换为字符串字面量“[Redact]”。

参数:

名称 必选/重复 类型 注释
属性/值 必须 String 指定要从日志中编校的属性或常量/字符串。

示例 1:编辑属性:Redact([userPrincipalName])从预配日志中删除 userPrincipalName。

示例 2:编辑字符串:Redact("StringToBeRedacted")从预配日志中删除常量字符串。

示例 3:编辑随机字符串:Redact(RandomString(6,3,0,0,3))从预配日志中删除随机字符串。


RemoveDuplicates

函数:RemoveDuplicates(attribute)

说明:RemoveDuplicates 函数取多值字符串,并确保每个值唯一。

参数:

名称 必选/重复 类型 注释
attribute 必需 多值特性 已移除重复值的多值特性

示例:RemoveDuplicates([proxyAddresses]) 返回净化的 proxyAddress 特性,其中的所有重复值已移除。


Replace

函数:Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)

说明:以区分大小写的方式替换字符串中的值。 该函数的行为因提供的参数而异:

  • 当提供了 oldValuereplacementValue 时:

    • 将 source 中出现的所有 oldValue 替换为 replacementValue
  • 当提供了 oldValuetemplate 时:

    • template 中出现的所有 oldValue 替换为 source
  • 如果已提供 regexPatternreplacementValue

    • 函数将 regexPattern 应用到 source 字符串,你可以使用 regex 组名称来构造 replacementValue 的字符串。

注意

如要详细了解正则表达式分组构造和命名子表达式,请参阅正则表达式中的分组构造

  • 当提供 regexPatternregexGroupNamereplacementValue 时:

    • 函数将 regexPattern 应用到 source 字符串,并将与 regexGroupName 匹配的所有值替换为 replacementValue
  • 如果已提供 regexPatternregexGroupNamereplacementAttributeName

    • 如果 source 具有值,则返回 source
    • 如果 source 没有值,则函数会将 regexPattern 应用到 replacementAttributeName 并返回与 regexGroupName 相匹配的值

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是 source 对象中的属性的名称。
oldValue 可选 字符串 要在 sourcetemplate 中替换的值。
regexPattern 可选 字符串 source 中要替换的值的正则表达式模式。 当使用 replacementAttributeName 时,将应用 regexPattern 提取 replacementAttributeName 中的值。
regexGroupName 可选 字符串 regexPattern 中的组名称。 使用指定的 replacementAttributeName 时,我们会从 replacementAttributeName 中提取指定正则表达式组的值,并将其作为替换值返回
replacementValue 可选 字符串 用于替换旧值的新值。
replacementAttributeName 可选 字符串 用于替换值的属性的名称
template 可选 字符串 如果提供了 template 值,我们会在模板中查找 oldValue 并将其替换为 source 值。

使用正则表达式替换字符

示例 1:使用 oldValue 和 replacementValue 将整个 source 字符串替换为另一个字符串。

假设你的 HR 系统具有 BusinessTitle 属性。 作为最近的职务更改的一部分,你的公司希望将业务头衔为“Product Developer”的全部人员更新为“Software Engineer”。 在这种情况下,可以在属性映射中使用以下表达式。

Replace([BusinessTitle],"Product Developer", , , "Software Engineer", , )

  • source:[BusinessTitle]
  • oldValue:“Product Developer”
  • replacementValue:“Software Engineer”
  • 表达式输出:Software Engineer

示例 2:使用 oldValue 和 template 将 source 字符串插入另一模板化字符串。

此方案中的 oldValue 参数为误用。 我们将在实际应用过程中替换该值。
假设你希望始终以 <username>@contoso.com 格式生成登录 ID。 有一个名为 UserID 的源特性,你希望该值用于登录 ID 的 <username> 部分。 在这种情况下,可以在属性映射中使用以下表达式。

Replace([UserID],"<username>", , , , , "<username>@contoso.com")

  • source: [UserID] = "jsmith"
  • oldValue:“<username>
  • template:“<username>@contoso.com
  • 表达式输出:“jsmith@contoso.com”

示例 3:使用 regexPattern 和 replacementValue 提取部分 source 字符串,并将其替换为空字符串或使用正则表达式模式或正则表达式组名称生成的自定义值。

假设源属性 telephoneNumber 包含以空格字符分隔的 country codephone number 组件。 例如:+91 9998887777。在这种情况下,可以在属性映射中使用以下表达式来提取 10 位数字的电话号码。

Replace([telephoneNumber], , "\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})", , "${phoneNumber}", , )

  • source: [telephoneNumber] = "+91 9998887777"
  • regexPattern:“\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})
  • replacementValue:“${phoneNumber}
  • 表达式输出:9998887777

你还可以使用此模式来删除字符和折叠字符串。 例如,下面的表达式在手机号字符串中移除了括号、短划线和空格字符,并只返回数字。

Replace([mobile], , "[()\\s-]+", , "", , )

  • source:[mobile] = "+1 (999) 888-7777"
  • regexPattern:“[()\\s-]+
  • replacementValue:“”(空字符串)
  • 表达式输出:19998887777

示例 4:使用 regexPattern、regexGroupName 和 replacementValue 提取 source 字符串的一部分,并将其替换为另一个文本值或空字符串。

假设源系统属性 AddressLineData 具有两个街道编号和街道名称组件。 作为最近移动的一部分,假设地址的街道号已更改,并且你只想更新地址行的街道号部分。 在这种情况下,可以在属性映射中使用以下表达式来提取街道号。

Replace([AddressLineData], ,"(?<streetNumber>^\\d*)","streetNumber", "888", , )

  • source: [AddressLineData] = "545 Tremont Street"
  • regexPattern:“(?<streetNumber>^\\d*)
  • regexGroupName:“streetNumber”
  • replacementValue:“888”
  • 表达式输出:888 Tremont Street

下面是另一个示例,其中 UPN 的域后缀替换为空字符串,以生成不带域后缀的登录 ID。

Replace([userPrincipalName], , "(?<Suffix>@(.)*)", "Suffix", "", , )

  • source: [userPrincipalName] = "jsmith@contoso.com"
  • regexPattern:“(?<Suffix>@(.)*)
  • regexGroupName:“Suffix”
  • replacementValue:“”(空字符串)
  • 表达式输出:jsmith

示例 5:使用 regexPattern、regexGroupName 和 replacementAttributeName 处理源属性为空或没有值时的情况。

假设你的源系统具有 telephoneNumber 属性。 如果 telephoneNumber 为空,则需要提取移动电话号码属性的 10 位数字。 在这种情况下,可以在属性映射中使用以下表达式。

Replace([telephoneNumber], , "\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})", "phoneNumber" , , [mobile], )

  • source: [telephoneNumber] = ""(空字符串)
  • regexPattern:“\\+(?<isdCode>\\d* )(?<phoneNumber>\\d{10})
  • regexGroupName:“phoneNumber”
  • replacementAttributeName: [mobile] = "+91 8887779999"
  • 表达式输出:8887779999

示例 6:你需要查找与正则表达式值匹配的字符并将其删除。

Replace([mailNickname], , "[a-zA-Z_]*", , "", , )

  • source:[mailNickname]
  • oldValue:“john_doe72”
  • replaceValue:“”
  • 表达式输出:72

SelectUniqueValue

函数:SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …)

说明:需要至少两个自变量,这些自变量是使用表达式定义的唯一值生成规则。 此函数会评估每个规则,然后在目标应用/目录中检查生成的值的唯一性。 返回找到的第一个唯一值。 如果所有值都已存在于目标中,则会托管该条目并在审核日志中记录原因。 可以提供的参数数目没有上限。

  • 此函数必须是顶级函数,不能嵌套。

  • 此函数不能应用到具有匹配优先级的特性。

  • 此函数仅供用于创建条目。 将其与属性一起使用时,请将“应用映射”属性设置为“仅在创建对象期间”。

  • 当前支持将此函数用于以下应用程序:

    • Workday 到 Azure Active Directory 的用户预配
    • SuccessFactors 到 Active Directory 域服务用户预配
    • 向本地 Active Directory 进行 API 驱动的预配

    不支持将 SelectUniqueValue 与其他预配应用程序一起使用。

  • SelectUniqueValue 函数在本地 Active Directory 中执行的 LDAP 搜索不会转义特殊字符(如音调符号)。 如果传递包含特殊字符的字符串(如“Jéssica Smith”),则会遇到处理错误。 按此示例所示嵌套 NormalizeDiacritics 函数,以规范特殊字符。

参数:

名称 必选/重复 类型 说明
uniqueValueRule1 … uniqueValueRuleN 需要至少 2 个,没有上限 字符串 要评估的唯一值生成规则的列表。

为 userPrincipalName (UPN) 属性生成唯一值

示例:你需要根据用户的名字、中间名和姓氏为 UPN 特性生成值,并在将该值分配给 UPN 特性之前在目标 AD 目录中检查其唯一性。

表达式:

    SelectUniqueValue( 
        Join("@", NormalizeDiacritics(StripSpaces(Join(".",  [PreferredFirstName], [PreferredLastName]))), "contoso.com"), 
        Join("@", NormalizeDiacritics(StripSpaces(Join(".",  Mid([PreferredFirstName], 1, 1), [PreferredLastName]))), "contoso.com"),
        Join("@", NormalizeDiacritics(StripSpaces(Join(".",  Mid([PreferredFirstName], 1, 2), [PreferredLastName]))), "contoso.com")
    )

示例输入/输出:

  • 输入 (PreferredFirstName):"John"
  • 输入 (PreferredLastName):"Smith"
  • 输出:"John.Smith@contoso.com",如果 UPN 值 John.Smith@contoso.com 尚未存在于目录中
  • 输出:"J.Smith@contoso.com",如果 UPN 值 John.Smith@contoso.com 已存在于目录中
  • 输出:"Jo.Smith@contoso.com",如果上面的两个值已存在于目录中

SingleAppRoleAssignment

函数:SingleAppRoleAssignment([appRoleAssignments])

说明:对于给定的应用程序,从向一个用户分配的所有 appRoleAssignments 列表中返回单个 appRoleAssignment。 需要此函数才能将 appRoleAssignments 对象转换为单个角色名称字符串。 最佳做法是确保一次给一位用户只分配一个 appRoleAssignment。 如果用户具有多个应用角色分配,则不支持此功能。

参数:

名称 必选/重复 类型 说明
[appRoleAssignments] 必须 String [appRoleAssignments] 对象。

拆分

函数:Split(source, delimiter)

说明:使用指定的分隔符将字符串拆分为多值数组。

参数:

名称 必选/重复 类型 注释
source 必须 String 要更新的 source 值。
delimiter 必须 字符串 指定用于拆分字符串的字符(示例:“,”)

将字符串拆分为多值数组

示例:你需要提取一个以逗号分隔的字符串列表,并将这些字符串拆分为可插入到多值特性(例如 Salesforce 的 PermissionSets 特性)的数组。 在此示例中,Microsoft Entra ID 的 extensionAttribute5 中填充了一个权限集列表。

表达式:Split([extensionAttribute5], ",")

示例输入/输出:

  • 输入 (extensionAttribute5):"PermissionSetOne, PermissionSetTwo"
  • 输出:["PermissionSetOne", "PermissionSetTwo"]

StripSpaces

函数:StripSpaces(source)

说明:从源字符串中删除所有空格 (" ") 字符。

参数:

名称 必选/重复 类型 注释
source 必须 String 要更新的 source 值。

开关

函数:Switch(source, defaultValue, key1, value1, key2, value2, …)

说明:当源值匹配某个键时,返回该键的值 。 当 source 值未与任何 key 匹配时,则返回 defaultValueKeyvalue 参数必须始终成对出现。 该函数始终需要偶数个参数。 不应该对 manager 等引用属性使用该函数。

注意

Switch 函数会对 source 值和 key 值执行区分大小写的字符串比较。 如果要执行不区分大小写的比较,请在使用嵌套的 ToLower 函数进行比较之前规范化 source 字符串,并确保对所有 key 字符串都使用小写。 示例:Switch(ToLower([statusFlag]), "0", "true", "1", "false", "0")。 在此示例中,source 属性 statusFlag 的值可以为“True”、“true”或“TRUE”。 但是,Switch 函数始终会将其转换为小写字符串“true”,然后再与 key 参数进行比较。

注意

对于 source 参数,请不要使用嵌套函数 IsPresent、IsNull 或 IsNullOrEmpty。 请改用字面量空字符串作为键值之一。
示例:Switch([statusFlag], "Default Value", "true", "1", "", "0")。 在此例中,如果 source 特性 statusFlag 为空,Switch 函数会返回值 0

注意

问题: 使用 switch 语句时,预配服务错误地将特性值设置为目标系统中的 null。
解决方法: 使用 IIF 语句而不是 switch 语句来防止意外的 null 值,或使用 Switch 语句的 IgnoreFlowIfNullOrEmpty 函数。 例如,switch ([companyName],“External”,“Company A”,“A”,“Company B”,“B”) 应表示为 IIF ([companyName] = “Company A”,“A”,IIF ([companyName] = “Company B”,“B”,“External”))。 如果默认值为特性,请使用一个表达式,例如 IgnoreFlowIfNullOrEmpty (switch ([companyName],[companyName],“Company A”、“A”、“Company B”,“B”))。
根本原因:此问题特定于 Microsoft Entra ID 是源系统且 switch 语句包含默认值的场景。

参数:

名称 必选/重复 类型 注释
source 必须 String 要更新的 source 值。
defaultValue 可选 字符串 当 source 不匹配任何 key 时使用的默认值。 可以是空字符串 ("")。
key 必须 String 用来比较 source 值的 key
value 必须 String 与该 key 匹配的 source 的替换值。

根据预定义的选项集替换值

示例:根据存储在 Microsoft Entra ID 中的状态代码来定义用户的时区。 如果状态代码与任何预定义选项都不匹配,则使用默认值“澳大利亚/悉尼”。

表达式:Switch([state], "Australia/Sydney", "NSW", "Australia/Sydney","QLD", "Australia/Brisbane", "SA", "Australia/Adelaide")

示例输入/输出:

  • 输入 (state):“QLD”
  • 输出:“澳大利亚/布里斯班”

ToLower

函数:ToLower(source, culture)

说明:取源字符串值,并使用指定的区域性规则将其转换为小写。 如果没有指定任何区域性信息,则使用固定区域性。

如果要将目标系统中的现有值设置为小写,请更新目标应用程序的架构,并将所需特性的 caseExact 属性设置为“true”。

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是来自源对象的属性的名称
culture 可选 字符串 基于 RFC 4646 的区域性名称格式是 languagecode2-country/regioncode2,其中 languagecode2 是两个字母的语言代码,country/regioncode2 是两个字母的子区域性代码。 示例包括代表日语(日本)的 ja-JP 和代表英语(美国)的 en-US。 在双字母语言代码不可用的情况下,使用派生自 ISO 639-2 的三字母代码。

将生成的 userPrincipalName (UPN) 值转换为小写

示例:你要通过连接 PreferredFirstName 和 PreferredLastName 源字段并将所有字符转换为小写,来生成 UPN 值。

ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))

示例输入/输出:

  • 输入 (PreferredFirstName):"John"
  • 输入 (PreferredLastName):"Smith"
  • 输出:“john.smith@contoso.com”

ToUpper

函数:ToUpper(source, culture)

说明:取源字符串值,并使用指定的区域性规则将其转换为大写。 如果没有指定任何区域性信息,则使用固定区域性。

如果要将目标系统中的现有值设置为大写,请更新目标应用程序的架构,并将相关特性的 caseExact 属性设置为“true”。

参数:

名称 必选/重复 类型 注释
source 必须 String 通常是来自源对象的属性的名称。
culture 可选 字符串 基于 RFC 4646 的区域性名称格式是 languagecode2-country/regioncode2,其中 languagecode2 是两个字母的语言代码,country/regioncode2 是两个字母的子区域性代码。 示例包括代表日语(日本)的 ja-JP 和代表英语(美国)的 en-US。 在双字母语言代码不可用的情况下,使用派生自 ISO 639-2 的三字母代码。

Word

函数:Word(String,WordNumber,Delimiters)

说明:Word 函数根据描述要使用的分隔符以及要返回的单词数的参数,返回字符串中包含的单词。 字符串中的字符由分隔符中其中一个字符分隔的每个字符串被标识为单词:

如果数字 < 1,则返回空字符串。 如果字符串为 null,则返回空字符串。 如果字符串包含的单词少于应返回数字或字符串不包含由分隔符标识的任何单词,则返回空字符串。

参数:

名称 必选/重复 类型 注释
字符串 必需 多值特性 要从中返回单词的字符串。
WordNumber 必需 整数 用来标识应返回的单词个数的数字
delimiters 必须 String 一个字符串,表示应该用来标识单词的分隔符

示例:Word("The quick brown fox",3," ")

返回“brown”。

Word("This,string!has&many separators",3,",!&#")

返回“has”。


示例

本部分提供更多的表达式函数用法示例。

删除已知域名

从用户的电子邮件地址中删除已知域名,以获取用户名。 例如,如果域为“contoso.com”,则可以使用以下表达式:

表达式:Replace([mail], "@contoso.com", , ,"", ,)

示例输入/输出:

  • 输入 (mail):“john.doe@contoso.com”
  • 输出:“john.doe”

通过连接名字和姓氏部分来生成用户别名

取用户名字的前 3 个字母和用户姓氏的前 5 个字母生成用户别名。

表达式:Append(Mid([givenName], 1, 3), Mid([surname], 1, 5))

示例输入/输出:

  • 输入 (givenName):“John”
  • 输入 (surname):“Doe”
  • 输出:“JohDoe”

在姓氏和名字之间添加英文逗号。

在姓氏和名字之间添加英文逗号。

表达式:Join(", ", "", [surname], [givenName])

示例输入/输出:

  • 输入 (givenName):“John”
  • 输入 (surname):“Doe”
  • 输出:“Doe, John”

根据用户的 Microsoft Entra 对象 ID 为其生成 ID。 从 ID 中删除任何字母并在开头添加 1000。

此表达式让您能以 1000 开头,为用户生成可能是唯一的标识符。

表达式: Join("", 1000, Replace(ConvertToUTF8Hex([objectId]), , "[a-zA-Z_]*", , "", , ))

示例输入/输出:

  • INPUT: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
  • 输出:"100064303565343762312333930392343435612626135652636136306362633065346234"