Share via


String Map Operations - Usage and Examples

 

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:

String Map Operations

The following table lists the String Map Operations in Microsoft Azure BizTalk Services:

Map Operator

Description

Parameters

Output

String Concatenate

Concatenates strings in the order listed.

Requires at least one input parameter. No maximum limit on the number input parameters:

Input_1:

Required. A string that is concatenated to.

Input_n:

Optional. A string that is concatenated with the previous string input.

Note

Strings are concatenated in the order listed.

A string that concatenated the input strings in the order specified.

For example, when using “1 Microsoft Way” and “Redmond WA” as input strings, the result is “1 Microsoft WayRedmond WA”.

Important

There is no trailing space at the end of the first string or a leading space at the beginning of the second string. As a result, there is no space between “Way” and “Redmond”.

String Find

Returns the starting position of a substring.

Requires exactly two input parameters:

Input string:

Required. A string that is being searched through.

Search String

Required. A string that is being searched for.

A numeric value starting at 1 that is the starting position of the first character in the substring. Zero (0) indicates that the substring was not found.

For example, searching for the “Redmond” substring within the “1 Microsoft Way Redmond WA” input string returns a numeric value of 17.

String Left

Retrieves a specified number of characters, starting with the leftmost character.

Requires exactly two input parameters:

Input string:

Required. A string to retrieve a specified number of its leftmost characters.

Number of Characters:

Required. A numeric value that represents the number of leftmost characters to retrieve.

A string that contains the specified number of leftmost characters.

For example, using “Redmond WA” as an input string and 3 for the Number of Characters, the result is “Red”.

Lowercase

Converts any uppercase characters within a string to lowercase.

Requires exactly one input parameter:

Input string:

Required. A string to convert any uppercase characters to lowercase.

Any uppercase characters within the string are now in lowercase.

For example, an input string of “Redmond WA” is returned as “redmond wa”.

String Right

Retrieves a specified number of characters, starting with the rightmost character.

Requires exactly two input parameters:

Input string:

Required. A string to retrieve a specified number of its rightmost characters.

Number of Characters

Required. A numeric value that represents the number of rightmost characters to retrieve.

A string that contains the specified number of rightmost characters.

For example, using “Redmond WA” as an input string and 3 for the Number of Characters, the result is “ WA”.

Important

There is a space between “Redmond” and “WA”. As a result, the space is displayed in the output.

Size

Retrieves the length of a string.

Requires exactly one input parameter:

Input string:

Required. A string to determine the length.

A numeric value that is the length of the string.

For example, “Redmond WA” as an input string returns a numeric value of 10.

String Extract

Extracts a substring by specifying the start and end positions.

Requires exactly three input parameters:

Input string

Required. A string to extract from.

Start Index

Required. A numeric value starting at 1 that is the starting character of the substring to be extracted.

End Index

Required. A numeric value starting at 1 that is the ending character of the substring to be extracted.

A string that contains the extracted substring.

For example, a Start Index of 2 and End Index of 5 of the “Redmond WA” input string returns “edmo”; where “e” is the second character, “d” is the third character, “m” is the fourth character and “o” is the fifth character.

An empty string is returned if the substring cannot be extracted due to incorrect Start Index and End Index values.

If the Start Index or the End Index parameters exceed the size of the input string, a substring is still returned as though these parameters were set to the exact size of the string. For example, a Start Index of 12 and End Index of 5 of the “Redmond WA” input string would return “Redmond WA” because the Start Index exceeds the size of the input string.

String Left Trim

Removes leading white-space characters from a string.

Requires exactly one input parameter:

Input string

Required. A string to remove leading white spaces.

A string with any leading white-space characters removed.

For example, an input string of “ Redmond WA” returns “Redmond WA”.

String Right Trim

Removes trailing white-space characters from a string.

Requires exactly one input parameter:

Input string

Required. A string to remove trailing white spaces.

A string with any trailing white-space characters removed.

For example, an input string of “Redmond WA ” returns “Redmond WA”.

Uppercase

Converts any lowercase characters in a string to uppercase.

Requires exactly one input parameter:

Input string

Required. A string to convert any lowercase characters to uppercase.

Any lowercase characters within the string are now in uppercase.

For example, an input string of “Redmond WA” returns “REDMOND WA”.

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 String is configurable in a BizTalk Service project and the BizTalk Service Artifacts project. Steps:

  1. Open a BizTalk Service project or a BizTalk Service Artifacts project in Visual Studio.

  2. Double-click a Transform (.trfm) to open the Transform Designer.

  3. In the Transform toolbar, select Settings.

Error Handling tab

In the Error Handling tab, String Operations has two Behavior options:

  • Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and is then sent to the user who sent the message.

  • Output default value Null: A null string value is returned as the output. A null string behaves as an empty string behaves except when sorting a List. When sorting a List, null strings are considered less than empty strings.

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.

Additional Map Operations

Loop Map Operations - Usage and Examples

Expressions in BizTalk Services - Usage and Examples

List Map Operations - Usage and Examples

Cumulative Map Operations - Usage and Examples

Date / Time Map Operations - Usage and Examples

Miscellaneous Map Operations - Usage and Examples

See Also

Create a Transform or Map