Writing expressions for attribute mappings in Microsoft Entra ID
In brief
The reference was refreshed across its function list and function sections, including descriptions, syntax, remarks, and examples.
What Entra admins need to know
Use the updated reference when configuring cloud sync expression mappings.
This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.
Documentation change
The comparison below shows only the changed extract. Use the full-page view for complete context.
Writing expressions for attribute mappings in Microsoft Entra ID
When you configure cloud sync, one of the types of attribute mappings that you can specify is an expression mapping.
The expression mapping allows you to customize attributes using a script-like expression. This allows you to transform the on-premises data into a new or different value. For example, you may want to combine two attributes into a single attribute because this single attribute is used by one of your cloud applications.
FunctionName(<<argument 1>>,<<argument N>>)
You may nest functions within each other. For example:
FunctionOne(FunctionTwo(<<argument1>>))You can pass three different types of arguments into functions:
- Attributes, which must be enclosed in square brackets. For example: [attributeName]
- String constants, which must be enclosed in double quotes. For example: "United States"
- Other Functions. For example: FunctionOne(
<<argument1>>, FunctionTwo(<<argument2>>))
For string constants, if you need a backslash ( \ ) or quotation mark ( " ) in the string, it must be escaped with the backslash ( \ ) symbol. For example: "Company name: \"Contoso\""
List of functions
| List of functions | Description |
|---|---|
| Append | Takes a source string value and appends the suffix to the end of it. |
| DateFromNum | The DateFromNum function converts a value in AD’s date format to a DateTime type. |
| DNComponent | The DNComponent function returns the value of a specified DN component going from left. |
| Error | The Error function is used to return a custom error. |
| FormatDateTime | Takes a date string from one format and converts it into a different format. |
| GUID | The function Guid generates a new random GUID. |
| IIF | The IIF function returns one of a set of possible values based on a specified condition. |
| InStr | The InStr function finds the first occurrence of a substring in a string. |
| IsNull | If the expression evaluates to Null, then the IsNull function returns true. |
| IsNullOrEmpty | If the expression is null or an empty string, then the IsNullOrEmpty function returns true. |
| IsPresent | If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true. |
| IsString | If the expression can be evaluated to a string type, then the IsString function evaluates to True. |
| Item | The Item function returns one item from a multi-valued string/attribute. |
| Join | Join() is similar to Append(), except that it can combine multiple source string values into a single string, and each value will be separated by a separator string. |
| Left | The Left function returns a specified number of characters from the left of a string. |
| Mid | Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string. |
| NormalizeDiacritics | Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters. |
| Not | Flips the boolean value of the source. If source value is "True", returns "False". Otherwise, returns "True". |
| RemoveDuplicates | The RemoveDuplicates function takes a multi-valued string and make sure each value is unique. |
| Replace | Replaces values within a string. |
| SelectUniqueValue | Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory. |
| SingleAppRoleAssignment | Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. |
| Split | Splits a string into a multi-valued array, using the specified delimiter character. |
| StringFromSID | The StringFromSid function converts a byte array containing a security identifier to a string. |
| StripSpaces | Removes all space (" ") characters from the source string. |
| Switch | When source value matches a key, returns value for that key. |
| ToLower | Takes a source string value and converts it to lower case using the culture rules that are specified. |
| ToUpper | Takes a source string value and converts it to upper case using the culture rules that are specified. |
| Trim | The Trim function removes leading and trailing white spaces from a string. |
| Word | The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return. |
Append
Function:
Append(source, suffix)
Description:
Takes a source string value and appends the suffix to the end of it.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
BitAnd
Description:
The BitAnd function sets specified bits on a value.
Syntax:num BitAnd(num value1, num value2)
- value1, value2: numeric values that should be AND’ed together
Remarks:
This function converts both parameters to the binary representation and sets a bit to:
- 0 - if one or both of the corresponding bits in value1 and value2 are 0
In other words, it returns 0 in all cases except when the corresponding bits of both parameters are 1.
Example:
BitAnd(&HF, &HF7)
Returns 7 because hexadecimal "F" AND "F7" evaluate to this value.
CBool
Description:
The CBool function returns a Boolean based on the evaluated expression
Syntax:bool CBool(exp Expression)
Remarks:
If the expression evaluates to a non-zero value, then CBool returns True, else it returns False.
Example:CBool([attrib1] = [attrib2])
Returns True if both attributes have the same value.
ConvertFromBase64
Description:
The ConvertFromBase64 function converts the specified base64 encoded value to a regular string.
Syntax:str ConvertFromBase64(str source) - assumes Unicode for encodingstr ConvertFromBase64(str source, enum Encoding)
- source: Base64 encoded string
- Encoding: Unicode, ASCII, UTF8
ExampleConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)
Both examples return "Hello world!"
ConvertToBase64
Description:
The ConvertToBase64 function converts a string to a Unicode base64 string.
Converts the value of an array of integers to its equivalent string representation that is encoded with base-64 digits.
Syntax:str ConvertToBase64(str source)
Example:ConvertToBase64("Hello world!")
Returns "SABlAGwAbABvACAAdwBvAHIAbABkACEA"
ConvertToUTF8Hex
Description:
The ConvertToUTF8Hex function converts a string to a UTF8 Hex encoded value.
Syntax:str ConvertToUTF8Hex(str source)
Remarks:
The output format of this function is used by Microsoft Entra ID as DN attribute format.
Example:ConvertToUTF8Hex("Hello world!")
Returns 48656C6C6F20776F726C6421
Count
Description:
The Count function returns the number of elements in a multi-valued attribute
Syntax:num Count(mvstr attribute)
CStr
Description:
The CStr function converts to a string data type.
Syntax:str CStr(num value)str CStr(ref value)str CStr(bool value)
- value: Can be a numeric value, reference attribute, or Boolean.
Example:CStr([dn])
Could return "cn=Joe,dc=contoso,dc=com"
DateFromNum
Description:
The DateFromNum function converts a value in AD’s date format to a DateTime type.
Syntax:dt DateFromNum(num value)
Example:DateFromNum([lastLogonTimestamp])DateFromNum(129699324000000000)
Returns a DateTime representing 2012-01-01 23:00:00
DNComponent
Description:
The DNComponent function returns the value of a specified DN component going from left.
Syntax:str DNComponent(ref dn, num ComponentNumber)
- dn: the reference attribute to interpret
- ComponentNumber: The component in the DN to return
Example:DNComponent(CRef([dn]),1)
If dn is "cn=Joe,ou=…," it returns Joe
Error
Description:
The Error function is used to return a custom error.
Syntax:void Error(str ErrorMessage)
Example:IIF(IsPresent([accountName]),[accountName],Error("AccountName is required"))
If the attribute accountName is not present, throw an error on the object.
FormatDateTime
Function:
FormatDateTime(source, inputFormat, outputFormat)
Description:
Takes a date string from one format and converts it into a different format.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
Guid
Description:
The function Guid generates a new random GUID
Syntax:str Guid()
IIF
Description:
The IIF function returns one of a set of possible values based on a specified condition.
Syntax:var IIF(exp condition, var valueIfTrue, var valueIfFalse)
- condition: any value or expression that can be evaluated to true or false.
- valueIfTrue: If the condition evaluates to true, the returned value.
- valueIfFalse: If the condition evaluates to false, the returned value.
Example:IIF([employeeType]="Intern","t-" & [alias],[alias])
If the user is an intern, returns the alias of a user with "t-" added to the beginning of it, else returns the user’s alias as is.
InStr
Description:
The InStr function finds the first occurrence of a substring in a string
Syntax:
num InStr(str stringcheck, str stringmatch)num InStr(str stringcheck, str stringmatch, num start)num InStr(str stringcheck, str stringmatch, num start, enum compare)
- stringcheck: string to be searched
- start: starting position to find the substring
- compare: vbTextCompare or vbBinaryCompare
Remarks:
Returns the position where the substring was found or 0 if not found.
Example:InStr("The quick brown fox","quick")
Evaluates to 5
InStr("repEated","e",3,vbBinaryCompare)
Evaluates to 7
IsNull
Description:
If the expression evaluates to Null, then the IsNull function returns true.
Syntax:bool IsNull(var Expression)
Remarks:
For an attribute, a Null is expressed by the absence of the attribute.
Example:IsNull([displayName])
Returns True if the attribute is not present in the CS or MV.
IsNullOrEmpty
Description:
If the expression is null or an empty string, then the IsNullOrEmpty function returns true.
Syntax:bool IsNullOrEmpty(var Expression)
Remarks:
For an attribute, this would evaluate to True if the attribute is absent or is present but is an empty string.
The inverse of this function is named IsPresent.
Example:IsNullOrEmpty([displayName])
Returns True if the attribute is not present or is an empty string in the CS or MV.
IsPresent
Description:
If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true.
Syntax:bool IsPresent(var expression)
Remarks:
The inverse of this function is named IsNullOrEmpty.
Example:Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])
Item
Description:
The Item function returns one item from a multi-valued string/attribute.
Syntax:var Item(mvstr attribute, num index)
- attribute: multi-valued attribute
- index: index to an item in the multi-valued string.
Remarks:
The Item function is useful together with the Contains function since the latter function returns the index to an item in the multi-valued attribute.
Throws an error if index is out of bounds.
Example:Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)
Returns the primary email address.
IsString
Description:
If the expression can be evaluated to a string type, then the IsString function evaluates to True.
Syntax:bool IsString(var expression)
Remarks:
Used to determine if CStr() can be successful to parse the expression.
Join
Function:
Join(separator, source1, source2, …)
Description:
Join() is similar to Append(), except that it can combine multiple source string values into a single string, and each value will be separated by a separator string.
If one of the source values is a multi-value attribute, then every value in that attribute will be joined together, separated by the separator value.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
Left
Description:
The Left function returns a specified number of characters from the left of a string.
Syntax:str Left(str string, num NumChars)
- string: the string to return characters from
- NumChars: a number identifying the number of characters to return from the beginning (left) of string
Remarks:
A string containing the first numChars characters in string:
- If numChars = 0, return empty string.
If string contains fewer characters than the number specified in numChars, a string identical to string (that is, containing all characters in parameter 1) is returned.
Example:Left("John Doe", 3)
Returns Joh.
Mid
Function:
Mid(source, start, length)
Description:
Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
NormalizeDiacritics
Function:
NormalizeDiacritics(source)
Description:
Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters. Typically used to convert first names and last names containing diacritical characters (accent marks) into legal values that can be used in various user identifiers such as user principal names, SAM account names, and email addresses.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
Not
Function:
Not(source)
Description:
Flips the boolean value of the source. If source value is "True", returns "False". Otherwise, returns "True".
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
RemoveDuplicates
Description:
The RemoveDuplicates function takes a multi-valued string and make sure each value is unique.
Syntax:mvstr RemoveDuplicates(mvstr attribute)
Example:RemoveDuplicates([proxyAddresses])
Returns a sanitized proxyAddress attribute where all duplicate values have been removed.
Replace
Function:
Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template)
Description:
Replaces values within a string. It works differently depending on the parameters provided:
When oldValue and replacementValue are provided:
- Replaces all occurrences of oldValue in the source with replacementValue
When oldValue and template are provided:
- Replaces all occurrences of the oldValue in the template with the source value
When regexPattern and replacementValue are provided:
- The function applies the regexPattern to the source string and you can use the regex group names to construct the string for replacementValue
When regexPattern, regexGroupName, replacementValue are provided:
- The function applies the regexPattern to the source string and replaces all values matching regexGroupName with replacementValue
When regexPattern, regexGroupName, replacementAttributeName are provided:
- If source has no value, source is returned
- If source has a value, the function applies the regexPattern to the source string and replaces all values matching regexGroupName with the value associated with replacementAttributeName
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
SelectUniqueValue
Function:
SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …)
Description:
Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory. The first unique value found will be the one returned. If all of the values already exist in the target, the entry will get escrowed and the reason gets logged in the audit logs. There is no upper bound to the number of arguments that can be provided.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
SingleAppRoleAssignment
Function:
SingleAppRoleAssignment([appRoleAssignments])
Description:
Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. Note that the best practice is to ensure only one appRoleAssignment is assigned to one user at a time, and if multiple roles are assigned the role string returned may not be predictable.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
Split
Function:
Split(source, delimiter)
Description:
Splits a string into a multi-valued array, using the specified delimiter character.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
StringFromSid
Description: The StringFromSid function converts a byte array containing a security identifier to a string.
Syntax:
str StringFromSid(bin ObjectSID)
StripSpaces
Function:
StripSpaces(source)
Description:
Removes all space (" ") characters from the source string.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
Switch
Function:
Switch(source, defaultValue, key1, value1, key2, value2, …)
Description:
When source value matches a key, returns value for that key. If source value doesn't match any keys, returns defaultValue. Key and value parameters must always come in pairs. The function always expects an even number of parameters.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
ToLower
Function:
ToLower(source, culture)
Description:
Takes a source string value and converts it to lower case using the culture rules that are specified. If there is no culture info specified, then it will use Invariant culture.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
ToUpper
Function:
ToUpper(source, culture)
Description:
Takes a source string value and converts it to upper case using the culture rules that are specified. If there is no culture info specified, then it will use Invariant culture.
Parameters:
| Name | Required/ Repeating | Type | Notes |
|---|
Trim
Description: The Trim function removes leading and trailing white spaces from a string.
Syntax:
str Trim(str value)
Example:
Trim(" Test ")
Returns "Test".
Trim([proxyAddresses])
Removes leading and trailing spaces for each value in the proxyAddress attribute.
Word
Description: The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return.
Syntax:
str Word(str string, num WordNumber, str delimiters)
- string: the string to return a word from.
- WordNumber: a number identifying which word number should return.
- delimiters: a string representing the delimiter(s) that should be used to identify words
Remarks: Each string of characters in string separated by the one of the characters in delimiters are identified as words:
- If number < 1, returns empty string.
If string contains less than number words, or string does not contain any words identified by delimiters, an empty string is returned.
Example:
Word("The quick brown fox",3," ")
Returns "brown"
Word("This,string!has&many separators",3,",!&#")
Would return "has"
Examples
- OUTPUT: "72"
Convert generated userPrincipalName (UPN) value to lower case
In the example below, the UPN value is generated by concatenating the PreferredFirstName and PreferredLastName source fields and the ToLower function operates on the generated string to convert all characters to lower case.
ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))
Expression:
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")
)
* **OUTPUT**: "[email protected]" if the above two UPN values already exist in the directory
## Next steps
- [What is provisioning?](../what-is-provisioning.md)
- [What is Microsoft Entra Cloud Sync?](what-is-cloud-sync.md)
@@ -9,7 +9,7 @@ ms.subservice: hybrid-cloud-sync # Writing expressions for attribute mappings in Microsoft Entra ID-When you configure cloud sync, one of the types of attribute mappings that you can specify is an expression mapping. +When you configure cloud sync, one of the types of attribute mappings that you can specify is an expression mapping. The expression mapping allows you to customize attributes using a script-like expression. This allows you to transform the on-premises data into a new or different value. For example, you may want to combine two attributes into a single attribute because this single attribute is used by one of your cloud applications. @@ -22,13 +22,14 @@ The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic *FunctionName(`<<argument 1>>`,`<<argument N>>`)* * You may nest functions within each other. For example: <br> *FunctionOne(FunctionTwo(`<<argument1>>`))* * You can pass three different types of arguments into functions:- + 1. Attributes, which must be enclosed in square brackets. For example: [attributeName] 2. String constants, which must be enclosed in double quotes. For example: "United States" 3. Other Functions. For example: FunctionOne(`<<argument1>>`, FunctionTwo(`<<argument2>>`)) * For string constants, if you need a backslash ( \ ) or quotation mark ( " ) in the string, it must be escaped with the backslash ( \ ) symbol. For example: "Company name: \\"Contoso\\"" ## List of functions+ | List of functions | Description | |-----|----| |[Append](#append)|Takes a source string value and appends the suffix to the end of it.|@@ -42,42 +43,42 @@ The syntax for Expressions for Attribute Mappings is reminiscent of Visual Basic |[DateFromNum](#datefromnum)|The DateFromNum function converts a value in AD’s date format to a DateTime type.| |[DNComponent](#dncomponent)|The DNComponent function returns the value of a specified DN component going from left.| |[Error](#error)|The Error function is used to return a custom error.|-|[FormatDateTime](#formatdatetime) |Takes a date string from one format and converts it into a different format.| -|[GUID](#guid)|The function Guid generates a new random GUID.| +|[FormatDateTime](#formatdatetime) |Takes a date string from one format and converts it into a different format.|+|[GUID](#guid)|The function Guid generates a new random GUID.| |[IIF](#iif)|The IIF function returns one of a set of possible values based on a specified condition.| |[InStr](#instr)|The InStr function finds the first occurrence of a substring in a string.| |[IsNull](#isnull)|If the expression evaluates to Null, then the IsNull function returns true.|-|[IsNullOrEmpty](#isnullorempty)|If the expression is null or an empty string, then the IsNullOrEmpty function returns true.| -|[IsPresent](#ispresent)|If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true.| +|[IsNullOrEmpty](#isnullorempty)|If the expression is null or an empty string, then the IsNullOrEmpty function returns true.|+|[IsPresent](#ispresent)|If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true.| |[IsString](#isstring)|If the expression can be evaluated to a string type, then the IsString function evaluates to True.| |[Item](#item)|The Item function returns one item from a multi-valued string/attribute.|-|[Join](#join) |Join() is similar to Append(), except that it can combine multiple **source** string values into a single string, and each value will be separated by a **separator** string.| +|[Join](#join) |Join() is similar to Append(), except that it can combine multiple **source** string values into a single string, and each value will be separated by a **separator** string.| |[Left](#left)|The Left function returns a specified number of characters from the left of a string.| |[Mid](#mid) |Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string.| |[NormalizeDiacritics](#normalizediacritics)|Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters.|-|[Not](#not) |Flips the boolean value of the **source**. If **source** value is "*True*", returns "*False*". Otherwise, returns "*True*".| -|[RemoveDuplicates](#removeduplicates)|The RemoveDuplicates function takes a multi-valued string and make sure each value is unique.| -|[Replace](#replace) |Replaces values within a string. | -|[SelectUniqueValue](#selectuniquevalue)|Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory.| -|[SingleAppRoleAssignment](#singleapproleassignment)|Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application.| +|[Not](#not) |Flips the boolean value of the **source**. If **source** value is "*True*", returns "*False*". Otherwise, returns "*True*".|+|[RemoveDuplicates](#removeduplicates)|The RemoveDuplicates function takes a multi-valued string and make sure each value is unique.|+|[Replace](#replace) |Replaces values within a string. |+|[SelectUniqueValue](#selectuniquevalue)|Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory.|+|[SingleAppRoleAssignment](#singleapproleassignment)|Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application.| |[Split](#split)|Splits a string into a multi-valued array, using the specified delimiter character.|-|[StringFromSID](#stringfromsid)|The StringFromSid function converts a byte array containing a security identifier to a string.| -|[StripSpaces](#stripspaces) |Removes all space (" ") characters from the source string.| -|[Switch](#switch)|When **source** value matches a **key**, returns **value** for that **key**. | -|[ToLower](#tolower)|Takes a *source* string value and converts it to lower case using the culture rules that are specified.| +|[StringFromSID](#stringfromsid)|The StringFromSid function converts a byte array containing a security identifier to a string.|+|[StripSpaces](#stripspaces) |Removes all space (" ") characters from the source string.|+|[Switch](#switch)|When **source** value matches a **key**, returns **value** for that **key**. |+|[ToLower](#tolower)|Takes a *source* string value and converts it to lower case using the culture rules that are specified.| |[ToUpper](#toupper)|Takes a *source* string value and converts it to upper case using the culture rules that are specified.| |[Trim](#trim)|The Trim function removes leading and trailing white spaces from a string.| |[Word](#word)|The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return.| --- ### Append-**Function:**<br> +**Function:**<br> Append(source, suffix) -**Description:**<br> +**Description:**<br> Takes a source string value and appends the suffix to the end of it. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -86,15 +87,15 @@ Takes a source string value and appends the suffix to the end of it. --- ### BitAnd-**Description:** +**Description:** The BitAnd function sets specified bits on a value. -**Syntax:** +**Syntax:** `num BitAnd(num value1, num value2)` * value1, value2: numeric values that should be AND’ed together -**Remarks:** +**Remarks:** This function converts both parameters to the binary representation and sets a bit to: * 0 - if one or both of the corresponding bits in *value1* and *value2* are 0@@ -102,147 +103,147 @@ This function converts both parameters to the binary representation and sets a b In other words, it returns 0 in all cases except when the corresponding bits of both parameters are 1. -**Example:** - +**Example:**+ `BitAnd(&HF, &HF7)`</br> Returns 7 because hexadecimal "F" AND "F7" evaluate to this value. --- ### CBool-**Description:** +**Description:** The CBool function returns a Boolean based on the evaluated expression -**Syntax:** +**Syntax:** `bool CBool(exp Expression)` -**Remarks:** +**Remarks:** If the expression evaluates to a non-zero value, then CBool returns True, else it returns False. -**Example:** -`CBool([attrib1] = [attrib2])` +**Example:**+`CBool([attrib1] = [attrib2])` Returns True if both attributes have the same value. --- ### ConvertFromBase64-**Description:** +**Description:** The ConvertFromBase64 function converts the specified base64 encoded value to a regular string. -**Syntax:** -`str ConvertFromBase64(str source)` - assumes Unicode for encoding +**Syntax:**+`str ConvertFromBase64(str source)` - assumes Unicode for encoding `str ConvertFromBase64(str source, enum Encoding)` -* source: Base64 encoded string +* source: Base64 encoded string * Encoding: Unicode, ASCII, UTF8 -**Example** -`ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")` +**Example**+`ConvertFromBase64("SABlAGwAbABvACAAdwBvAHIAbABkACEA")` `ConvertFromBase64("SGVsbG8gd29ybGQh", UTF8)` Both examples return "*Hello world!*" --- ### ConvertToBase64-**Description:** -The ConvertToBase64 function converts a string to a Unicode base64 string. +**Description:**+The ConvertToBase64 function converts a string to a Unicode base64 string. Converts the value of an array of integers to its equivalent string representation that is encoded with base-64 digits. -**Syntax:** +**Syntax:** `str ConvertToBase64(str source)` -**Example:** -`ConvertToBase64("Hello world!")` +**Example:**+`ConvertToBase64("Hello world!")` Returns "SABlAGwAbABvACAAdwBvAHIAbABkACEA" --- ### ConvertToUTF8Hex-**Description:** +**Description:** The ConvertToUTF8Hex function converts a string to a UTF8 Hex encoded value. -**Syntax:** +**Syntax:** `str ConvertToUTF8Hex(str source)` -**Remarks:** +**Remarks:** The output format of this function is used by Microsoft Entra ID as DN attribute format. -**Example:** -`ConvertToUTF8Hex("Hello world!")` +**Example:**+`ConvertToUTF8Hex("Hello world!")` Returns 48656C6C6F20776F726C6421 --- ### Count-**Description:** +**Description:** The Count function returns the number of elements in a multi-valued attribute -**Syntax:** +**Syntax:** `num Count(mvstr attribute)` --- ### CStr-**Description:** +**Description:** The CStr function converts to a string data type. -**Syntax:** -`str CStr(num value)` -`str CStr(ref value)` -`str CStr(bool value)` +**Syntax:**+`str CStr(num value)`+`str CStr(ref value)`+`str CStr(bool value)` * value: Can be a numeric value, reference attribute, or Boolean. -**Example:** -`CStr([dn])` +**Example:**+`CStr([dn])` Could return "cn=Joe,dc=contoso,dc=com" --- ### DateFromNum-**Description:** +**Description:** The DateFromNum function converts a value in AD’s date format to a DateTime type. -**Syntax:** +**Syntax:** `dt DateFromNum(num value)` -**Example:** -`DateFromNum([lastLogonTimestamp])` -`DateFromNum(129699324000000000)` +**Example:**+`DateFromNum([lastLogonTimestamp])`+`DateFromNum(129699324000000000)` Returns a DateTime representing 2012-01-01 23:00:00 --- ### DNComponent-**Description:** +**Description:** The DNComponent function returns the value of a specified DN component going from left. -**Syntax:** +**Syntax:** `str DNComponent(ref dn, num ComponentNumber)` * dn: the reference attribute to interpret * ComponentNumber: The component in the DN to return -**Example:** -`DNComponent(CRef([dn]),1)` +**Example:**+`DNComponent(CRef([dn]),1)` If dn is "cn=Joe,ou=…," it returns Joe --- ### Error-**Description:** +**Description:** The Error function is used to return a custom error. -**Syntax:** +**Syntax:** `void Error(str ErrorMessage)` -**Example:** -`IIF(IsPresent([accountName]),[accountName],Error("AccountName is required"))` +**Example:**+`IIF(IsPresent([accountName]),[accountName],Error("AccountName is required"))` If the attribute accountName is not present, throw an error on the object. --- ### FormatDateTime-**Function:**<br> +**Function:**<br> FormatDateTime(source, inputFormat, outputFormat) -**Description:**<br> +**Description:**<br> Takes a date string from one format and converts it into a different format. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -252,37 +253,37 @@ Takes a date string from one format and converts it into a different format. --- ### Guid-**Description:** +**Description:** The function Guid generates a new random GUID -**Syntax:** +**Syntax:** `str Guid()` --- ### IIF-**Description:** +**Description:** The IIF function returns one of a set of possible values based on a specified condition. -**Syntax:** +**Syntax:** `var IIF(exp condition, var valueIfTrue, var valueIfFalse)` * condition: any value or expression that can be evaluated to true or false. * valueIfTrue: If the condition evaluates to true, the returned value. * valueIfFalse: If the condition evaluates to false, the returned value. -**Example:** -`IIF([employeeType]="Intern","t-" & [alias],[alias])` +**Example:**+`IIF([employeeType]="Intern","t-" & [alias],[alias])` If the user is an intern, returns the alias of a user with "t-" added to the beginning of it, else returns the user’s alias as is. --- ### InStr-**Description:** +**Description:** The InStr function finds the first occurrence of a substring in a string -**Syntax:** +**Syntax:** -`num InStr(str stringcheck, str stringmatch)` -`num InStr(str stringcheck, str stringmatch, num start)` +`num InStr(str stringcheck, str stringmatch)`+`num InStr(str stringcheck, str stringmatch, num start)` `num InStr(str stringcheck, str stringmatch, num start, enum compare)` * stringcheck: string to be searched@@ -290,103 +291,103 @@ The InStr function finds the first occurrence of a substring in a string * start: starting position to find the substring * compare: vbTextCompare or vbBinaryCompare -**Remarks:** +**Remarks:** Returns the position where the substring was found or 0 if not found. -**Example:** -`InStr("The quick brown fox","quick")` +**Example:**+`InStr("The quick brown fox","quick")` Evaluates to 5 -`InStr("repEated","e",3,vbBinaryCompare)` +`InStr("repEated","e",3,vbBinaryCompare)` Evaluates to 7 --- ### IsNull-**Description:** +**Description:** If the expression evaluates to Null, then the IsNull function returns true. -**Syntax:** +**Syntax:** `bool IsNull(var Expression)` -**Remarks:** +**Remarks:** For an attribute, a Null is expressed by the absence of the attribute. -**Example:** -`IsNull([displayName])` +**Example:**+`IsNull([displayName])` Returns True if the attribute is not present in the CS or MV. --- ### IsNullOrEmpty-**Description:** +**Description:** If the expression is null or an empty string, then the IsNullOrEmpty function returns true. -**Syntax:** +**Syntax:** `bool IsNullOrEmpty(var Expression)` -**Remarks:** -For an attribute, this would evaluate to True if the attribute is absent or is present but is an empty string. +**Remarks:**+For an attribute, this would evaluate to True if the attribute is absent or is present but is an empty string. The inverse of this function is named IsPresent. -**Example:** -`IsNullOrEmpty([displayName])` +**Example:**+`IsNullOrEmpty([displayName])` Returns True if the attribute is not present or is an empty string in the CS or MV. --- ### IsPresent-**Description:** +**Description:** If the expression evaluates to a string that is not Null and is not empty, then the IsPresent function returns true. -**Syntax:** +**Syntax:** `bool IsPresent(var expression)` -**Remarks:** +**Remarks:** The inverse of this function is named IsNullOrEmpty. -**Example:** +**Example:** `Switch(IsPresent([directManager]),[directManager], IsPresent([skiplevelManager]),[skiplevelManager], IsPresent([director]),[director])` --- ### Item-**Description:** +**Description:** The Item function returns one item from a multi-valued string/attribute. -**Syntax:** +**Syntax:** `var Item(mvstr attribute, num index)` * attribute: multi-valued attribute * index: index to an item in the multi-valued string. -**Remarks:** +**Remarks:** The Item function is useful together with the Contains function since the latter function returns the index to an item in the multi-valued attribute. Throws an error if index is out of bounds. -**Example:** -`Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)` +**Example:**+`Mid(Item([proxyAddresses],Contains([proxyAddresses], "SMTP:")),6)` Returns the primary email address. --- ### IsString-**Description:** +**Description:** If the expression can be evaluated to a string type, then the IsString function evaluates to True. -**Syntax:** +**Syntax:** `bool IsString(var expression)` -**Remarks:** +**Remarks:** Used to determine if CStr() can be successful to parse the expression. --- ### Join-**Function:**<br> +**Function:**<br> Join(separator, source1, source2, …) -**Description:**<br> +**Description:**<br> Join() is similar to Append(), except that it can combine multiple **source** string values into a single string, and each value will be separated by a **separator** string. If one of the source values is a multi-value attribute, then every value in that attribute will be joined together, separated by the separator value. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -395,16 +396,16 @@ If one of the source values is a multi-value attribute, then every value in that --- ### Left-**Description:** +**Description:** The Left function returns a specified number of characters from the left of a string. -**Syntax:** +**Syntax:** `str Left(str string, num NumChars)` * string: the string to return characters from * NumChars: a number identifying the number of characters to return from the beginning (left) of string -**Remarks:** +**Remarks:** A string containing the first numChars characters in string: * If numChars = 0, return empty string.@@ -413,19 +414,19 @@ A string containing the first numChars characters in string: If string contains fewer characters than the number specified in numChars, a string identical to string (that is, containing all characters in parameter 1) is returned. -**Example:** -`Left("John Doe", 3)` +**Example:**+`Left("John Doe", 3)` Returns `Joh`. --- ### Mid-**Function:**<br> +**Function:**<br> Mid(source, start, length) -**Description:**<br> +**Description:**<br> Returns a substring of the source value. A substring is a string that contains only some of the characters from the source string. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -435,13 +436,13 @@ Returns a substring of the source value. A substring is a string that contains o --- ### NormalizeDiacritics-**Function:**<br> +**Function:**<br> NormalizeDiacritics(source) -**Description:**<br> +**Description:**<br> Requires one string argument. Returns the string, but with any diacritical characters replaced with equivalent non-diacritical characters. Typically used to convert first names and last names containing diacritical characters (accent marks) into legal values that can be used in various user identifiers such as user principal names, SAM account names, and email addresses. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -449,13 +450,13 @@ Requires one string argument. Returns the string, but with any diacritical chara --- ### Not-**Function:**<br> +**Function:**<br> Not(source) -**Description:**<br> +**Description:**<br> Flips the boolean value of the **source**. If **source** value is "*True*", returns "*False*". Otherwise, returns "*True*". -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -463,42 +464,42 @@ Flips the boolean value of the **source**. If **source** value is "*True*", retu --- ### RemoveDuplicates-**Description:** +**Description:** The RemoveDuplicates function takes a multi-valued string and make sure each value is unique. -**Syntax:** +**Syntax:** `mvstr RemoveDuplicates(mvstr attribute)` -**Example:** -`RemoveDuplicates([proxyAddresses])` +**Example:**+`RemoveDuplicates([proxyAddresses])` Returns a sanitized proxyAddress attribute where all duplicate values have been removed. --- ### Replace-**Function:**<br> +**Function:**<br> Replace(source, oldValue, regexPattern, regexGroupName, replacementValue, replacementAttributeName, template) **Description:**<br> Replaces values within a string. It works differently depending on the parameters provided: * When **oldValue** and **replacementValue** are provided:- + * Replaces all occurrences of **oldValue** in the **source** with **replacementValue** * When **oldValue** and **template** are provided:- + * Replaces all occurrences of the **oldValue** in the **template** with the **source** value * When **regexPattern** and **replacementValue** are provided: * The function applies the **regexPattern** to the **source** string and you can use the regex group names to construct the string for **replacementValue** * When **regexPattern**, **regexGroupName**, **replacementValue** are provided:- + * The function applies the **regexPattern** to the **source** string and replaces all values matching **regexGroupName** with **replacementValue** * When **regexPattern**, **regexGroupName**, **replacementAttributeName** are provided:- + * If **source** has no value, **source** is returned * If **source** has a value, the function applies the **regexPattern** to the **source** string and replaces all values matching **regexGroupName** with the value associated with **replacementAttributeName** -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -512,20 +513,20 @@ Replaces values within a string. It works differently depending on the parameter --- ### SelectUniqueValue-**Function:**<br> +**Function:**<br> SelectUniqueValue(uniqueValueRule1, uniqueValueRule2, uniqueValueRule3, …) -**Description:**<br> +**Description:**<br> Requires a minimum of two arguments, which are unique value generation rules defined using expressions. The function evaluates each rule and then checks the value generated for uniqueness in the target app/directory. The first unique value found will be the one returned. If all of the values already exist in the target, the entry will get escrowed and the reason gets logged in the audit logs. There is no upper bound to the number of arguments that can be provided. > [!NOTE] > - This is a top-level function, it cannot be nested.-> - This function cannot be applied to attributes that have a matching precedence. +> - This function cannot be applied to attributes that have a matching precedence. > - This function is only meant to be used for entry creations. When using it with an attribute, set the **Apply Mapping** property to **Only during object creation**.-> - This function is currently only supported for "Workday and SuccessFactors to Active Directory User Provisioning". It cannot be used with other provisioning applications. +> - This function is currently only supported for "Workday and SuccessFactors to Active Directory User Provisioning". It cannot be used with other provisioning applications. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -534,13 +535,13 @@ Requires a minimum of two arguments, which are unique value generation rules def --- ### SingleAppRoleAssignment-**Function:**<br> +**Function:**<br> SingleAppRoleAssignment([appRoleAssignments]) -**Description:**<br> -Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. Note that the best practice is to ensure only one appRoleAssignment is assigned to one user at a time, and if multiple roles are assigned the role string returned may not be predictable. +**Description:**<br>+Returns a single appRoleAssignment from the list of all appRoleAssignments assigned to a user for a given application. This function is required to convert the appRoleAssignments object into a single role name string. Note that the best practice is to ensure only one appRoleAssignment is assigned to one user at a time, and if multiple roles are assigned the role string returned may not be predictable. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | |--- | --- | --- | --- |@@ -548,13 +549,13 @@ Returns a single appRoleAssignment from the list of all appRoleAssignments assig --- ### Split-**Function:**<br> +**Function:**<br> Split(source, delimiter) -**Description:**<br> +**Description:**<br> Splits a string into a multi-valued array, using the specified delimiter character. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -563,21 +564,21 @@ Splits a string into a multi-valued array, using the specified delimiter charact --- ### StringFromSid-**Description:** +**Description:** The StringFromSid function converts a byte array containing a security identifier to a string. -**Syntax:** -`str StringFromSid(bin ObjectSID)` +**Syntax:**+`str StringFromSid(bin ObjectSID)` --- ### StripSpaces-**Function:**<br> +**Function:**<br> StripSpaces(source) -**Description:**<br> +**Description:**<br> Removes all space (" ") characters from the source string. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -585,13 +586,13 @@ Removes all space (" ") characters from the source string. --- ### Switch-**Function:**<br> +**Function:**<br> Switch(source, defaultValue, key1, value1, key2, value2, …) -**Description:**<br> +**Description:**<br> When **source** value matches a **key**, returns **value** for that **key**. If **source** value doesn't match any keys, returns **defaultValue**. **Key** and **value** parameters must always come in pairs. The function always expects an even number of parameters. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -602,13 +603,13 @@ When **source** value matches a **key**, returns **value** for that **key**. If --- ### ToLower-**Function:**<br> +**Function:**<br> ToLower(source, culture) -**Description:**<br> +**Description:**<br> Takes a *source* string value and converts it to lower case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -618,13 +619,13 @@ Takes a *source* string value and converts it to lower case using the culture ru --- ### ToUpper-**Function:**<br> +**Function:**<br> ToUpper(source, culture) -**Description:**<br> +**Description:**<br> Takes a *source* string value and converts it to upper case using the culture rules that are specified. If there is no *culture* info specified, then it will use Invariant culture. -**Parameters:**<br> +**Parameters:**<br> | Name | Required/ Repeating | Type | Notes | | --- | --- | --- | --- |@@ -634,32 +635,32 @@ Takes a *source* string value and converts it to upper case using the culture ru --- ### Trim-**Description:** +**Description:** The Trim function removes leading and trailing white spaces from a string. -**Syntax:** -`str Trim(str value)` +**Syntax:**+`str Trim(str value)` -**Example:** -`Trim(" Test ")` +**Example:**+`Trim(" Test ")` Returns "Test". -`Trim([proxyAddresses])` +`Trim([proxyAddresses])` Removes leading and trailing spaces for each value in the proxyAddress attribute. --- ### Word-**Description:** +**Description:** The Word function returns a word contained within a string, based on parameters describing the delimiters to use and the word number to return. -**Syntax:** +**Syntax:** `str Word(str string, num WordNumber, str delimiters)` * string: the string to return a word from. * WordNumber: a number identifying which word number should return. * delimiters: a string representing the delimiter(s) that should be used to identify words -**Remarks:** +**Remarks:** Each string of characters in string separated by the one of the characters in delimiters are identified as words: * If number < 1, returns empty string.@@ -667,11 +668,11 @@ Each string of characters in string separated by the one of the characters in de If string contains less than number words, or string does not contain any words identified by delimiters, an empty string is returned. -**Example:** -`Word("The quick brown fox",3," ")` +**Example:**+`Word("The quick brown fox",3," ")` Returns "brown" -`Word("This,string!has&many separators",3,",!&#")` +`Word("This,string!has&many separators",3,",!&#")` Would return "has" ## Examples@@ -771,7 +772,7 @@ Replace([mailNickname], , "[a-zA-Z_]*", , "", , ) * **OUTPUT**: "72" ### Convert generated userPrincipalName (UPN) value to lower case-In the example below, the UPN value is generated by concatenating the PreferredFirstName and PreferredLastName source fields and the ToLower function operates on the generated string to convert all characters to lower case. +In the example below, the UPN value is generated by concatenating the PreferredFirstName and PreferredLastName source fields and the ToLower function operates on the generated string to convert all characters to lower case. `ToLower(Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"))` @@ -787,8 +788,8 @@ Based on the user's first name, middle name and last name, you need to generate **Expression:** <br> ```ad-attr-mapping-expr- SelectUniqueValue( - Join("@", NormalizeDiacritics(StripSpaces(Join(".", [PreferredFirstName], [PreferredLastName]))), "contoso.com"), + 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") )@@ -803,7 +804,7 @@ Based on the user's first name, middle name and last name, you need to generate * **OUTPUT**: "[email protected]" if the above two UPN values already exist in the directory -## Next steps +## Next steps - [What is provisioning?](../what-is-provisioning.md) - [What is Microsoft Entra Cloud Sync?](what-is-cloud-sync.md) 