Expressions in BizTalk Services - Usage and Examples

Article
06/12/2017

Important

Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.

If you're brand new to Logic Apps, then we suggest getting started here:

What are logic apps
Create your first logic app, or quickly get started using a pre-built template
View all the available connectors you can use in your logic apps

Lists the Expression Map Operations in Microsoft Azure BizTalk Services.

Expressions Map Operators

Map Operation	Description	Parameters	Output
Arithmetic Expression	Evaluates a mathematical expression using inputs and constants. Arithmetic Expressions consists of the following operators: Addition Subtraction Multiplication Division Modulo Absolute Value Maximum Minimum Round Square Root	Can have 0 to 100 optional input parameters: Input A numeric value. Arithmetic Expression A mathematical expression defined using the inputs and constants. Note The maximum length for an expression is 1024 characters.	A numeric value that is the result of the computation. See Arithmetic Expression Examples: BizTalk Services.
Logical Expression	Evaluates a condition and outputs the Boolean value of the evaluation. Logical Expression consists of the following operators: Relational Operators: > < >= <= == != Logical Negation (!) Conditional AND (&&) Conditional OR (\|\|)	Can have 0 to 100 optional input parameters: Input Can be a numeric value, string value or Boolean value. Logical Expression An expression defined using the inputs and constants that evaluate to a Boolean value. Note The maximum length for an expression is 1024 characters.	True is returned if the Logical Expression returns true. Otherwise, False is returned. See Logical Expression Examples: BizTalk Services.
If-Then-Else Expression	Evaluates a statement that results in one of two possible outputs.	Can have 0 to 100 optional input parameters: Input Can be a numeric value, string value or Boolean value. Condition An expression defined using the inputs and constants. Then Value If statement or expression is true, this value is used. Else Value If statement or expression is false, this value is used. Note The maximum length for an expression is 1024 characters.	The result is based on a true or false evaluation of the conditional expression. If true, the Then Value is used. If false, the Else Value is used. See If-Then-Else Expression Example: BizTalk Services.
Conditional Assignment	Returns a value from one of two input parameters. If the first input value is True, then a node is created in the output document with the second input value. If the first input value is False, then the corresponding node is not created in the output document.	Requires exactly two input parameters: Condition An expression that results in a Boolean value. Can be one of the following: Link from tree node Link from a Map Operation Assign Value The value assigned to the destination node if the condition is true. Note This Map Operation can only be connected to a destination tree node.	If the Condition value is "true", then a node is created with the Assign Value input value. See Conditional Assignment Example: BizTalk Services.

The following table lists additional functions that can be used with any Map Operation:

Function	Expression	Description
Exists	Exists(Source_Node_Name)	Requires a single input that is the element name in the source document. If the element exists, True is returned. Otherwise, False is returned.
IsDate	IsDate(Input1)	Requires a single input of the type string. The DateTime.TryParse() method is used to parse the input into a DateTime object. If the input is parsed successfully, True is returned. Otherwise, False is returned.
IsEmpty	IsEmpty(Input1)	Requires a single input of the type string. If the string is null or empty, True is returned. Otherwise, False is returned. If the input is not a string object, True is returned.
IsNil	IsNil(Source_Node_Name)	Requires a single argument that is the element name in the source document. If the element exists and xsi:nil is set to True, then True is returned. Otherwise, False is returned.
IsNumber	IsNumber(Input1)	Requires a single input of the type string. The Double.TryParse() method is used to parse the input into a double. If the input is parsed successfully, True is returned. Otherwise, False is returned. Note The comma “,” is supported as the thousands separator and the period “.” is supported as a decimal point.

Important

All Map Operation and functions can be used within other Map Operation and functions except Exists and IsNil. Exists and IsNil point to a single node in the source document.

Error and Data Handling

BizTalk Services provides the ability to configure how an error is handled and how an empty or null node is handled. The error handling behavior of the following Expression Map Operations is configurable:

Logical Expression
Arithmetic Expression
If-Then-Else Expression

Steps:

Open a BizTalk Service project or the BizTalk Service Artifacts project in Visual Studio.
Double-click a Transform (.trfm) to open the Transform Designer.
In the Transform toolbar, click Settings.

Error Handling tab

In the Error Handling tab, the following Expression Map Operations have two Behavior options:

Logical Expression:
- Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and the error is then sent back to the client that sent the message.
- Output default value false: If the Map Operation fails, False is returned as the output.
Arithmetic Expression:
- Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and the error is then sent to the client that sent the message.
- Output default value NaN: If the Map Operation fails, NaN (Not a Number) is returned as the output.
- Output default value 0: If the Map Operation fails, zero (0) is returned as the output.
If-Then-Else Expression:
- Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and the error is then sent back to the client that sent the message.
- Output Null/Zero/False based on type of output: If the Map Operation fails, Null/Zero/False is returned as the output based on type of output.

Null/Empty Data Handling tab

In the Null/Empty Data Handling tab, there are three options:

Consider empty nodes in cumulative operations: By default, this is not checked. When not checked, no empty nodes are included in the iteration. When checked, all nodes, including empty nodes, are included in the iteration.

EXAMPLE: There is a document with 10 <record> nodes. Three of these <record> nodes are empty. When Consider empty nodes in iterations is not checked, the Map Operation returns a value of seven. When Consider empty nodes in iterations is checked, the Map Operation returns a value of 10.
Consider empty nodes in iterations: By default, this is not checked. When not checked, no empty nodes are included in the iteration. When checked, all nodes, including empty nodes, are included in the iteration.

EXAMPLE: there is a document with 10 <record> nodes. Three of these <record> nodes are empty. When Consider empty nodes in iterations is not checked, the Map Operation iterates seven times for the non-empty nodes. As a result, seven <record> nodes are generated in the Target. When Consider empty nodes in iterations is checked, the Map Operation iterates 10 times for all nodes, including the empty nodes. As a result, 10 <record> nodes are generated in the Target.
Target Node Generation: If empty nodes are configured to be considered, you choose to generate an empty node in the output or to not generate an empty node in the output. Specifically:
- Do not generate empty nodes: Default option.
- Generate empty nodes
EXAMPLE: There is a document with 10 <record> nodes. Three of these <record> nodes are empty. Consider empty nodes in cumulative operations or Consider empty nodes in iterations are not checked, the Map Operation iterates seven times for the non-empty nodes. As a result, seven <record> nodes are generated in the Target. When Consider empty nodes in iterations is checked, the Map Operation iterates 10 times for all nodes, including the empty nodes. As a result, 10 <record> nodes are generated in the Target.