Expression Language

Cloud Sync uses an expression language for attribute mapping transformations. Expressions let you compute target attribute values from source attributes using functions, string manipulation, conditionals, and type conversions.

The syntax is similar to Visual Basic for Applications (VBA) function calls. If you have worked with Connect Sync expressions, the concepts are familiar but the implementation differs.

Syntax Basics

Expressions are function calls with arguments in parentheses:

FunctionName(argument1, argument2, ...)

Three types of arguments:

Attributes - enclosed in square brackets: [displayName], [mail], [givenName]
String constants - enclosed in double quotes: "contoso.com", "@"
Nested functions - functions can be arguments to other functions

Escape rules:

Backslash (\) and double quotes (") in string constants must be escaped with a backslash: "Company: \"Contoso\""

Core Functions

Conditionals

IIF(condition, valueIfTrue, valueIfFalse) - the workhorse conditional. Returns one of two values based on a boolean condition.

IIF([employeeType]="Intern", "t-" & [alias], [alias])

String Functions

Function	Description	Example
`Append(source, suffix)`	Appends suffix to source	`Append([mail], ".test")`
`Join(separator, source1, source2, ...)`	Joins multiple values with a separator	`Join(".", [givenName], [surname])`
`Left(string, numChars)`	Returns N characters from the left	`Left([surname], 5)`
`Mid(source, start, length)`	Returns a substring (1-indexed)	`Mid([telephoneNumber], 2, 8)`
`Replace(source, oldValue, ...)`	Replaces values in a string	`Replace([mail], "@fabrikam.com", , , "@contoso.com", , )`
`Trim(value)`	Removes leading/trailing whitespace	`Trim([displayName])`
`ToLower(source)`	Converts to lowercase	`ToLower([userPrincipalName])`
`ToUpper(source)`	Converts to uppercase	`ToUpper([department])`
`StripSpaces(source)`	Removes all spaces	`StripSpaces([telephoneNumber])`
`NormalizeDiacritics(source)`	Replaces accented characters	`NormalizeDiacritics([givenName])`
`Word(string, number, delimiters)`	Returns the Nth word	`Word([displayName], 1, " ")`
`Split(source, delimiter)`	Splits into multi-valued array	`Split([extensionAttribute5], ",")`

Type Conversions

Function	Description
`CBool(expression)`	Converts to boolean
`CStr(value)`	Converts to string
`ConvertToBase64(source)`	Encodes as base64
`ConvertFromBase64(source)`	Decodes from base64
`ConvertToUTF8Hex(source)`	Converts to UTF8 hex (used for DN format)
`FormatDateTime(source, inputFormat, outputFormat)`	Reformats date strings

Null Handling

Function	Description
`IsNull(expression)`	Returns true if the expression is null
`IsNullOrEmpty(expression)`	Returns true if null or empty string
`IsPresent(expression)`	Returns true if the string is not null and not empty

Other Functions

Function	Description
`BitAnd(value1, value2)`	Bitwise AND
`Count(attribute)`	Count elements in a multi-valued attribute
`Guid()`	Generate a new random GUID
`InStr(string, substring)`	Find position of substring
`Item(attribute, index)`	Return one item from multi-valued attribute
`RemoveDuplicates(attribute)`	Deduplicate multi-valued attribute
`SelectUniqueValue(rule1, rule2, ...)`	Generate unique values (entry creation only)
`Switch(source, default, key1, val1, ...)`	Map values via key-value pairs
`StringFromSid(objectSID)`	Convert SID bytes to string
`Error(message)`	Throw a custom error
`DateFromNum(value)`	Convert AD date format to DateTime
`DNComponent(dn, component)`	Extract a component from a DN

Common Patterns

Build an email address from name attributes

Join("@", NormalizeDiacritics(StripSpaces(Join(".", [givenName], [surname]))), "contoso.com")

Set displayName to “Last, First” format

IIF(IsNullOrEmpty([givenName]), [sn], Join(", ", [sn], [givenName]))

Strip a domain from an email

Replace([mail], "@contoso.com", , , "", , )

Map department to time zone

Switch([state], "UTC", "NSW", "Australia/Sydney", "QLD", "Australia/Brisbane", "CA", "America/Los_Angeles")

Set a NULL value

To clear an attribute, use an expression with an empty string:

""

This flows a NULL value to the target attribute.

The Expression Builder

Cloud Sync provides a visual expression builder in the Entra admin center that simplifies writing and testing expressions.

To use it:

In your Cloud Sync configuration, go to Attribute mapping.
Select an attribute mapping and change the Mapping type to Expression.
Select Try the expression builder.
Choose a function from the dropdown. The builder shows the function’s parameter fields.
Fill in the parameters.
Select Add expression to see the generated syntax.
Test the expression by selecting a source attribute, entering a test value, and selecting Test expression. The output is shown immediately.
When satisfied, select Apply expression.

The expression builder is particularly useful for Replace(), which has many optional parameter combinations that are easy to get wrong when writing manually.

Differences from Connect Sync Expressions

Cloud Sync and Connect Sync both use expression languages for attribute transformations, but they are not interchangeable. Expressions written for one engine do not directly port to the other.

Aspect	Connect Sync	Cloud Sync
Where expressions are written	Synchronization Rules Editor (on-premises)	Entra admin center or MS Graph API (cloud)
Precedence system	Rules have numeric precedence; lowest number wins	No rule precedence system; one mapping per attribute
Special literals	`NULL`, `AuthoritativeNull`, `IgnoreThisFlow`	Empty string `""` for null; no equivalent of `AuthoritativeNull` or `IgnoreThisFlow`
Multi-valued merge types	Update, Merge, MergeCaseInsensitive	Not configurable
Testing	Must run a sync cycle or use preview in Sync Service Manager	On-demand provisioning and expression builder provide instant testing
Function set	Largely overlapping but not identical	Largely overlapping but not identical

Key gotchas when migrating expressions:

AuthoritativeNull does not exist in Cloud Sync. If your Connect Sync rules use it to force-clear attributes regardless of other rules, you need to rethink the approach in Cloud Sync since there is no rule precedence competition.
IgnoreThisFlow does not exist in Cloud Sync. If your Connect Sync rules conditionally skip attribute flows, you need to handle the conditional differently.
No merge types for multi-valued attributes. Cloud Sync overwrites multi-valued attributes rather than merging. If you relied on Merge or MergeCaseInsensitive for proxyAddresses, this is a behavioral difference.

For details on Connect Sync’s expression system, see the sync rules deep dive.