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:
-
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
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:
Open a BizTalk Service project or a BizTalk Service Artifacts project in Visual Studio.
Double-click a Transform (.trfm) to open the Transform Designer.
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