How to use account field expressions - Identity as a Service

This topic describes how to use advanced account field expressions in the IDaaS built-in expression engine and provides details about model fields, functions, and reference examples.

Basics

IDaaS has a built-in expression engine. In SAML and OpenID Connect (OIDC) applications, you can use advanced expressions to add new parameters to the returned user information. Use expressions if the target application requires additional parameters that need to be converted, concatenated, or evaluated.

Similarly, you can use the same method to customize field values with expressions when you configure field mappings for synchronization with an identity provider.

This topic provides reference examples to help you understand the scenarios and methods for using expressions.

For example, in an OIDC single sign-on (SSO) configuration, you can extend the returned id_token information. In the extension value, you can enter an advanced expression such as full_phone to achieve a specific processing goal.

For more information, see SAML attribute statement mapping rules, OIDC id_token extension value mapping rules, and Field management.

Expressions consist of two parts:

Models, which include User (for IDaaS accounts) and AppUser (for application accounts).
Functions, which represent logical operations.

Model descriptions

1. User

The following fields are in the IDaaS User model. You can reference them using formats such as user.username and user.lockExpireTime.

Field Display Name	Field ID	Data Type	Required	Unique	User Permissions	Description
Account ID	userId	String	No	Yes	Visible	The user ID.
Username	username	String	Yes	Yes	Visible	The username.
Display name	displayName	String	No	No	Editable	The user's display name.
Email	email	String	No	Yes	Editable	The email address.
Mobile phone	phoneNumber	Number	No	Yes	Editable	The phone number.
Phone area code	phoneRegion	Number	No	No	Editable	The area code for the phone number. Example: The area code for China is "86", without "00" or "+".
External ID	userExternalId	String	No	Yes	Visible	The user's external ID.
Source type	userSourceType	String	No	No	Visible	The source type. Valid values: build_in: Self-built. ding_talk: DingTalk. ad: AD. ldap: LDAP. we_com: WeCom. lark: Lark. idp_auto_build: Automatically created by an IdP.
Source ID	userSourceId	String	No	No	Visible	The source ID.
Account status	status	String	No	No	Visible	The user status. Valid values: enabled: Enabled. disabled: Disabled.
Description	description	String	No	No	Visible	The description.
Account expiration time	accountExpireTime	Number	No	No	Visible	The time when the user account expires. This is a UNIX timestamp in milliseconds.
Account registration time	registerTime	Number	No	No	Visible	The time when the user registered. This is a UNIX timestamp in milliseconds.
Password expiration time	passwordExpireTime	Number	No	No	Visible	The time when the password expires. This is a UNIX timestamp in milliseconds.
Lock expiration time	lockExpireTime	Number	No	No	Visible	The time when the lock expires. This is a UNIX timestamp in milliseconds.
Creation time	createTime	Number	No	No	Visible	The time when the account was created. This is a UNIX timestamp in milliseconds.
Update time	updateTime	Number	No	No	Visible	The time when the user information was last updated. This is a UNIX timestamp in milliseconds.

2. App User

The following fields are in the IDaaS AppUser model. You can reference them using a format such as appUser.username.

Property	Description
username	The username of the application account.

3. IdP User

The IdP User model is used for synchronization with an identity provider. For example, the office location field for DingTalk is idpUser.work_place.

For specific fields, see the documentation for the corresponding identity provider, such as the DingTalk Help Document - User Details.

Important

For OIDC identity providers (see Attach an OIDC identity provider), when you use expressions in the automatic attachment feature, the idpUser. prefix applies only to the sub, phoneNumber, and email fields from the id_token (for example, idpUser.sub). For all other fields, you must use the idpUser.rawUserInfo. prefix (for example, idpUser.rawUserInfo.aud).

Function descriptions

The following table describes the available functions and provides examples:

Function name	Function definition	Description	Example
Append	Append(str1, str2, ..., strn)	Concatenates the input parameters into a new string. This is equivalent to `str1+str2+...`.	Input: `Append("str1", "@example.com")` Output: `str1@example.com`
Join	Join(source1, source2, ..., sourceN, separator)	Joins multiple source values into a single string, separated by the specified separator.	Input: `Join("str1", "str2", 123,"-")` Output: `"str1-str2-123"`
Coalesce	Coalesce(source1, source2, ..., sourceN, defaultValue)	Returns the first non-empty parameter from the input. If all parameters are empty, it returns null. A non-empty parameter is not null and has a length greater than 0.	Input: `Coalesce("", user.phoneRegion, "86")` Output: If the phone area code is empty or missing, the output is `86`.
IIF	IIF(condition, whenTrue, whenFalse)	Ternary operation. Returns a value based on the result of the condition. If the condition is true, it returns whenTrue. If the condition is false, it returns whenFalse.	Example 1: Input: `IIF(true, 1, 2)` Output: `1` Example 2: Input: `IIF(false, 1, 2)` Output: `2`
IsNull	IsNull(value)	If the value is null or missing, the output is true.	Example 1: Input: `IsNull(null)` Output: `true` Example 2: Input: `IsNull("")` Output: false
IsNullOrEmpty	IsNullOrEmpty(value)	If the value is null or an empty string, the output is true.	Example 1: Input: `IsNullOrEmpty(user.email)` Output: If the email is null or missing, the output is `true`. Example 2: Input: `IsNullOrEmpty("")` Output: `true`
Now	Now()	Returns a string representing the current UTC DateTime in the yyyy-MM-dd'T'HH:mm:ssXXX format.	Output: 2021-11 01T09:52:11Z
StringReplace	StringReplace("hello $VariableName", "$VariableName", ReplaceString)	Performs a simple string replacement.	Input: `StringReplace("hello $str", "$str", "world")` Output: `hello world`
Trim	Trim(source)	Removes leading and trailing whitespace characters from the source string.	Input: `Trim(" 123 ")` Output: `123`
TrimLeft	TrimLeft(source)	Removes leading whitespace characters from the source string.	Input: `TrimLeft(" 123 ")` Output: `123`
TrimRight	TrimRight(source)	Removes trailing whitespace characters from the source string.	Input: `TrimRight(" 123 ")` Output: `123`
ToLower	ToLower(source)	Converts a string to all lowercase.	Input: `ToLower(" Abc ")` Output: `abc`
ToUpper	ToUpper(source)	Converts a string to all uppercase.	Input: `ToUpper(" Abc ")` Output: `ABC`
Substring	Substring(source, fromIndex, endIndex)	Returns a substring of the string. The substring starts at fromIndex and ends before endIndex. source: Required. The source string. It can be any type supported by the syntax. fromIndex: Required. An integer. If it is not an integer, the function returns null. endIndex: Required. An integer. If it is not an integer, the function returns null.	Example 1: Input: `Substring("0123456", 1, 5)` Output: `1234` Example 2: Input: `Substring("0123456", -1, 7)` Output: `0123456` Example 3: Input: `Substring("0123456", "1", 5)` Output: null
SubstringBefore	SubstringBefore(source, subString)	Searches a source string from left to right for a target string and returns the substring that follows the first occurrence. If the target string is not found, null is returned. Parameters: source: Required. The source string. It can be any type supported by the syntax. target: Required. The target string. The value can be of any data type that is supported by the syntax. Return value: string	Example 1: Input: `SubstringBefore("test@example@com", "@")` Output: `"test"`
Array	Array(source1, source2,...)	Combines multiple values into an array. The values can be of the Object type.	Input: `Array(1, 2, 3)` Output: `[1, 2, 3]`
ArrayAdd	ArrayAdd(Array(), "test")	Adds an element to an array object.	Input: `ArrayAdd(Array(), "test")` Output: `["test"]`
ArrayMap	ArrayMap($ArrayObject, __item.ObjectProperty)	Creates a new array with the values of a specific property from an array of objects.	Get a list of group IDs for a user: Input: `ArrayMap(user.groups, __item.groupId)` Output: `["groupId1","groupId2","groupId3"]`
ArrayIndex	ArrayIndex(Array(), n)	Gets the element at a specific index in an array. The index starts from 0.	Input: `ArrayIndex(Array(1,2,3), 0)` Output: `1`
ArrayJoin	ArrayJoin(Array(), str)	Joins the elements of an array into a string, using a specified separator.	Input: `ArrayJoin(Array(1,2,3), "-")` Output: `"1-2-3"`
Object	Object(key1, value1, key2, value2, ...)	Creates an Object by combining key-value pairs. Supports zero or an even number of parameters.	Input: `Object("key1", "value1", "key2", "value2")` Output object: `{"key1": "value1", "key2": "value2"}`
ObjectIndex	ObjectIndex(user, "username")	Gets the value of a specific property from an object.	The code `ObjectIndex(user, "username")` is equivalent to `user.username`.
ObjectToJsonString	ObjectToJsonString(user.groups)	Converts an object to a JSON string.	-
Contains	Contains(str1,str2)	Checks if a string contains another string. Returns true or false.	Example 1: Input: `Contains("test", "t")` Output: `true` Example 2: Input: `Contains("test", "a")` Output: `false`
Or	Or(true,false,...,true)	Performs a logical OR operation on multiple conditions. If any condition is true, the result is true.	Example 1: Input: `Or(true,false)` Output: `true` Example 2: Input: `Or(true,true,false)` Output: `true` Example 3: Input: `Or(false,false)` Output: `false`
And	And(true,false,...,true)	Performs a logical AND operation on multiple conditions. If any condition is false, the result is false.	Example 1: Input: `And(true,false)` Output: `false` Example 2: Input: `And(true,true,false)` Output: `false` Example 3: Input: `And(true,true,true)` Output: `true`
xOr	xOr(true,false,...,true)	Requires exactly two conditions. Returns false if both conditions are true or both are false. Returns true if one condition is true and the other is false.	Example 1: Input: `xOr(true,false)` Output: `true` Example 2: Input: `xOr(true,true)` Output: `false` Example 3: Input: `And(false,false)` Output: `false`
StartsWith	StartsWith(str1, str2)	Checks if a string starts with a specified prefix. This function takes exactly two parameters.	Example 1: Input: `StartsWith("test", "t")` Output: `true` Example 2: Input: `StartsWith("test", "e")` Output: `false`
Split	Split("str1,str2,str3")	Splits a string into an array of substrings.	Example 1: Input: `Split("str1,str2,str3",",")` Output: `Array(str1,str2,str3)`
Equals	Equals(str1,str2)	Compares two strings for equality. Equals(str1,str2). Equals(str1,str2,false) performs a case-sensitive comparison. Equals(str1,str2,true) performs a case-insensitive comparison.	Example 1: Input: `Equals("test","Test")` Output: `false` Example 2: Input: `Equals("test","Test",true)` Output: `true` Example 3: Input: `Equals("test","Test",false)` Output: `false`
CurrentTimeMillis	CurrentTimeMillis()	The current UNIX timestamp in milliseconds.	-
SamlArray	SamlArray(Array())	Available only for SAML SSO.	Input: `SamlArray(Array("group1","group2"))` SAML Response output: `<saml2:Attribute Name="grouIdArray"` `NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">` <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:type="xsd:string"> group1 `</saml2:AttributeValue>` `<saml2:AttributeValue` xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string"> group2 `</saml2:AttributeValue>` Input: `SamlArray(Array("group1","group2"))` SAML Response output: `</saml2:Attribute>`
ExtractPhoneRegion	ExtractPhoneRegion(source, defaultRegion,autoAppendPlusSignal)	Extracts the area code from a phone number. source: The phone number. autoAppendPlusSignal: Specifies whether to automatically add a plus sign (+). Set to true to add the sign, or false to not add it. defaultRegion: The default country or region for the mobile phone area code. For the country or region code, use the Alpha-2 code from the ISO 3166 Country Codes standard (https://www.iso.org/obp/ui/#search), such as CN, US, and TW. If the phone number includes an area code with a plus sign (+) prefix, omit the autoAppendPlusSignal and defaultRegion parameters. If the phone number includes an area code without a plus sign (+) prefix, set autoAppendPlusSignal to true and defaultRegion to the default country or region code. If the phone number does not include an area code, set autoAppendPlusSignal to false and defaultRegion to the default country or region code.	Example 1: If the phone number is `+86131xxxxx000`, `+86 131xxxxx000`, or `+86-131xxxxx000`: Input: ExtractPhoneRegion(idpUser.mobile) Return value: 86 Example 2: If the phone number is `86131xxxxx000`, `86 131xxxxx000`, or `86-131xxxxx000`: Input: ExtractPhoneRegion(idpUser.mobile, "CN", true) Return value: 86 Example 3: If the phone number is `131xxxxx000`: Input: ExtractPhoneRegion(idpUser.mobile, "CN", false) Return value: 86
ExtractPhoneNumber	ExtractPhoneNumber(source, defaultRegion,autoAppendPlusSignal)	Extracts the phone number without the area code. source: The phone number. autoAppendPlusSignal: Specifies whether to automatically add a plus sign (+). Set to true to add the sign, or false to not add it. defaultRegion: The default country or region for the mobile phone area code. For the country or region code, use the Alpha-2 code from the ISO 3166 Country Codes standard (https://www.iso.org/obp/ui/#search). For example, CN, US, and TW. If a phone number includes an area code that is prefixed with a plus sign (+), you do not need to pass the autoAppendPlusSignal and deafaultRegion parameters. If a phone number includes an area code without a plus sign (+), set autoAppendPlusSignal to true and set defaultRegion to the default country or region code. If a phone number does not include an area code and you want to set a default one, set autoAppendPlusSignal to false and set defaultRegion to the default country or region code.	Example 1: If the phone number is `+86131xxxxx000`, `+86 131xxxxx000`, or `+86-131xxxxx000`: Input: ExtractPhoneNumber(idpUser.mobile) Return value: 131xxxxx000 Example 2: If the phone number is `86131xxxxx000`, `86 131xxxxx000`, or `86-131xxxxx000`: Input: ExtractPhoneNumber(idpUser.mobile, "CN", true) Return value: 131xxxxx000 Example 3: If the phone number is `131xxxxx000`: Input: ExtractPhoneNumber(idpUser.mobile, "CN", false) Return value: 131xxxxx000

Reference examples

Result	Example expression
Get the username and append the fixed string "@example.com".	`Append(user.username, "@example.com")`
If the email is not empty, return the email. If the email is empty, return the phone number.	`Coalesce(user.email, user.phoneNumber)`
If the phone number is empty, use a fixed phone number as the default.	`IIF(IsNullOrEmpty(user.phoneNumber), "1888888****", user.phoneNumber)`
Concatenate the phone area code and the phone number with a hyphen (-).	`Join(user.phoneRegion, user.phoneNumber, "-")`
Return a custom welcome message that includes the display name.	`StringReplace("hello $DisplayName", "$DisplayName", user.displayName)`
Mask the middle four digits of the phone number with asterisks (*).	`Append(` `SubString(user.phoneNumber, 0, 4),` `"****",` `SubString(user.phoneNumber, 8, 10)` )
Extract the username from the email address.	`SubstringBefore(user.email, "@")`
Assemble the email field in the array format specified by the System for Cross-domain Identity Management (SCIM) protocol.	`Array(Object("email", user.email, "type", "work", "primary", true))`

User model JSON example:

{
  "customFieldMap": {
        "place": {
            "fieldName": "place",
            "fieldValue": "beijing"
        },
        "age": {
            "fieldName": "age",
            "fieldValue": "18"
        }
    },
    "identityProviderUserMap": {
        "idp_m2gngriuenktdkxxxxxx": {
            "identityProviderId": "idp_m2gngriuenktdkxxxxxx",
            "identityProviderType": "ding_talk",
            "identityProviderExternalId": "corp_1234xxxxxxx",
            "identityProviderUserId": "b2ed5fc0xxxxx"
        }
    },
    "organizationalUnits": [
        {
            "organizationalUnitId": "ou_sdfadtaaxxxxxx",
            "organizationalUnitName": "name_001",
            "primary": false
        },
        {
            "organizationalUnitId": "ou_werttxxxxxx",
            "organizationalUnitName": "name_002",
            "primary": true
        }
    ],
    "primaryOrganizationalUnitId": "ou_werttxxxxxx",
    "customFields": [
        {
            "fieldName": "place",
            "fieldValue": "beijing"
        },
        {
            "fieldName": "age",
            "fieldValue": "18"
        }
    ],
    "groups": [
        {
            "groupId": "group_jp6al4sn4n4wjgjxxxxxx",
            "groupName": "group1",
            "groupExternalId": "group_jp6al4sn4n4wjgjxxxxxx"
        },
        {
            "groupId": "group_vavikcxewkf5h3oxxxxxx",
            "groupName": "group2",
            "groupExternalId": "group_vavikcxewkf5h3oxxxxxx"
        }
    ],
  "userId": "user_x3zyd6cxxxxxxxxxxxxx",
  "username": "name_001",
  "displayName": "displayname_001",
  "passwordSet": true,
  "phoneRegion": "86",
  "phoneNumber": "333xxxx3333",
  "phoneNumberVerified": true,
  "email": "xxxxx@example.com",
  "emailVerified": true,
  "userExternalId": "b2ed5fc0xxxxxxxxxx",
  "userSourceType": "ding_talk",
  "userSourceId": "corp_1234xxxxxxx",
  "status": "enabled",
  "accountExpireTime": "-1",
  "passwordExpireTime": "-1",
  "registerTime": "1730454581598",
  "lockExpireTime": "-1",
  "createTime": "1730454582379",
  "updateTime": "1733479455307"
}