In my last blog post, I explain in detail the String functions available in the new Data Mapper, and I endup documenting each of them.
String functions are used to manipulate strings in standard ways, such as conversions to all uppercase or all lowercase, string concatenation, determination of string length, white space trimming, etc. If you come from the BizTalk Server background or are migrating BizTalk Server projects, they are the equivalent of String Functoids inside BizTalk Mapper Editor.
The String functoids are:
Codepoints to string: Converts the specified codepoints value to a string and returns the result.
Concat: Combines two or more strings and returns the combined string.
Contains: Returns true or false based on whether the string input contains the specified substring.
Ends with: Returns true or false based on whether the string input ends with the specified substring.
Length: Returns the number of items in the specified string or array.
Lowercase: Returns a string in lowercase format.
Name: Returns the local name of the selector node, which is useful when you want to retrieve the name of the incoming message component, not the value.
Regular expression matches: Returns true or false based on whether the string input matches the specified regular expression.
Regular expression replace: Returns a string created from the string input by using a given regular expression to find and replace matching substrings with the specified string.
Replace: Replaces a substring with the specified string and return the new complete string.
Starts with: Returns true if the given string starts with the specified substring.
String to codepoints: Converts the specified string to codepoints.
Substring: Returns characters from the specified string, starting from the specified position.
Substring after: Returns the characters that follow the specified substring in the source string.
Substring before: Returns the characters that precede the specified substring in the source string.
Trim: Returns the specified string with all the leading and trailing white space characters removed.
Trim left: Returns the specified string with all the leading white space characters removed.
Trim right: Returns the specified string with all the trailing white space characters removed.
Uppercase: Returns a string in uppercase format.
In this video, we will see each of these String Functions in action. For each one, we will provide simple input data, and we will see what the expected output is.
Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more, you can buy (or help buy) my son a Star Wars Lego!
Author: Sandro Pereira
Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc.
He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.
View all posts by Sandro Pereira
String functions are used to manipulate strings in standard ways, such as conversions to all uppercase or all lowercase, string concatenation, determination of string length, white space trimming, etc. If you come from the BizTalk Server background or are migrating BizTalk Server projects, they are the equivalent of String Functoids inside BizTalk Mapper Editor.
Available Functions
The String functoids are:
Codepoints to string: Converts the specified codepoints value to a string and returns the result.
Concat: Combines two or more strings and returns the combined string.
Contains: Returns true or false based on whether the string input contains the specified substring.
Ends with: Returns true or false based on whether the string input ends with the specified substring.
Length: Returns the number of items in the specified string or array.
Name: Returns the local name of the selector node, which is useful when you want to retrieve the name of the incoming message component, not the value.
Regular expression matches: Returns true or false based on whether the string input matches the specified regular expression.
Regular expression replace: Returns a string created from the string input by using a given regular expression to find and replace matching substrings with the specified string.
Replace: Replaces a substring with the specified string and return the new complete string.
Starts with: Returns true if the given string starts with the specified substring.
This function states that you can convert the specified codepoints value to a string and returns the result. but first, we need to understand what is a codepoint! In character encoding terminology, a code point, codepoint, or code position is a numerical value that maps to a specific character. Code points usually represent a single grapheme, usually a letter, digit, punctuation mark, or whitespace but sometimes represent symbols, control characters, or formatting. You can check and learn more about codepoint here: https://codepoints.net/. For example, the codepoint 65 is the letter A.
Behind the scenes, this function is translated to the following XPath function: codepoints-to-string()
codepoints-to-string($arg as xs:string) as xs:string
Concat
This function states that you can combine two or more strings and returns the combined string.
Behind the scenes, this function is translated to the following XPath function: concat()
concat( $arg1 as xs:anyAtomicType?, $arg2 as xs:anyAtomicType?, … ) as xs:string
Rules:
This function accepts two or more xs:anyAtomicType arguments and casts each one to xs:string. The function returns the xs:string that is, the concatenation of the values of its arguments after conversion. If any argument is the empty sequence, that argument is treated as the zero-length string.
The concat function is specified to allow two or more arguments, which are concatenated together. This is the only function specified in this document that allows a variable number of arguments.
Contains
This function states that it returns true or false based on whether the string input (argument 1) contains the specified substring (argument 2).
Behind the scenes, this function is translated to the following XPath function: contains()
contains($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean
Rules:
If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
If the value of $arg2 is the zero-length string, then the function returns true.
If the value of $arg1 is the zero-length string, the function returns false.
Ends with
This function states that it returns true or false based on whether the string input ends with the specified substring.
Behind the scenes, this function is translated to the following XPath function: ends-with()
ends-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean
Rules:
If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
If the value of $arg2 is the zero-length string, then the function returns true.
If the value of $arg1 is the zero-length string, and the value of $arg2 is not the zero-length string, then the function returns false.
The function returns an xs:boolean indicating whether or not the value of $arg1 ends with a sequence of collation units that provides a match to the collation units of $arg2 according to the collation that is used.
Length
This function states that it returns the number of items in the specified string or array.
Behind the scenes, this function is translated to the following XPath function: string-lenght()
string-length($arg as xs:string?) as xs:integer
Rules:
The function returns an xs:integer equal to the length in characters of the value of $arg.
If the value of $arg is the empty sequence, the function returns the xs:integer value zero (0).
Lowercase
This function states that it returns a string in lowercase format.
Behind the scenes, this function is translated to the following XPath function: lower-case()
lower-case($arg as xs:string?) as xs:string
Rules:
If the value of $arg is the empty sequence, the zero-length string is returned.
Otherwise, the function returns the value of $arg after translating every character to its lower-case correspondent as defined in the appropriate case mappings section in the Unicode standard.
Name
This function states that it returns the local name of the selector node, which is useful when you want to retrieve the name of the incoming message component, not the value.
Behind the scenes, this function is translated to the following XPath function: local-name-from-QName()
local-name-from-QName($arg as xs:QName?) as xs:NCName
Rules:
If $arg is the empty sequence, the function returns the empty sequence.
Otherwise, the function returns a xs:NCName representing the local part of $arg.
Regular expression matches
This function states that it returns true or false based on whether the string input matches the specified regular expression.
Behind the scenes, this function is translated to the following XPath function: matches()
matches($input as xs:string?, $pattern as xs:string) as xs:boolean
Rules:
If $input is the empty sequence, it is interpreted as the zero-length string.
The function returns true if $input or some substring of $input matches the regular expression supplied as $pattern. Otherwise, the function returns false.
Regular expression replace
This function states that it returns a string created from the string input by using a given regular expression to find and replace matching substrings with the specified string.
Behind the scenes, this function is translated to the following XPath function: replace()
replace($input as xs:string?, $pattern as xs:string, $replacement as xs:string) as xs:string
Rules:
If $input is the empty sequence, it is interpreted as the zero-length string.
The function returns the xs:string that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern with an occurrence of the $replacement string.
If two overlapping substrings of $input both match the $pattern, then only the first one (that is, the one whose first character comes first in the $input string) is replaced.
In this sample above, if the city element from the source message has the value abracadabra then the output will be *c*bra
Replace
This function states that it replaces a substring with the specified string and returns the new complete string.
Behind the scenes, this function is translated to the following XPath function: replace()
replace($input as xs:string?, $pattern as xs:string, $replacement as xs:string) as xs:string
This will be exactly the same as the previous one, but instead of using a regular expression pattern, we use a string to be replaced.
Starts with
This function states that it returns true if the given string starts with the specified substring.
Behind the scenes, this function is translated to the following XPath function: starts-with()
starts-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean
Rules:
If the value of $arg1 or $arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.
If the value of $arg2 is the zero-length string, then the function returns true. If the value of $arg1 is the zero-length string, and the value of $arg2 is not the zero-length string, then the function returns false.
String to codepoints
This function states that it converts the specified string to codepoints. But first, we need to understand what is a codepoint! In character encoding terminology, a code point, codepoint, or code position is a numerical value that maps to a specific character. Code points usually represent a single grapheme, usually a letter, digit, punctuation mark, or whitespace but sometimes represent symbols, control characters, or formatting. You can check and learn more about codepoint here: https://codepoints.net/. For example, the letter A is the codepoint 65.
Behind the scenes, this function is translated to the following XPath function: string-to-codepoints()
fn:string-to-codepoints($arg as xs:string?) as xs:integer
Rules:
The function returns a sequence of integers, each integer being the Unicode codepoint of the corresponding character in $arg.
If $arg is a zero-length string or the empty sequence, the function returns the empty sequence.
Substring
This function states that it returns characters from the specified string, starting from the specified position.
Behind the scenes, this function is translated to the following XPath function: substring()
substring($sourceString as xs:string?, $start as xs:double, $length as xs:double) as xs:string
or
substring($sourceString as xs:string?, $start as xs:double) as xs:string
Rules:
If the value of $sourceString is the empty sequence, the function returns the zero-length string.
Otherwise, the function returns a string comprising those characters of $sourceString whose index position (counting from one) is greater than or equal to the value of $start (rounded to an integer), and (if $length is specified) less than the sum of $start and $length (both rounded to integers).
The characters returned do not extend beyond $sourceString. If $start is zero or negative, only those characters in positions greater than zero are returned.
Substring after
This function states that it returns the characters that follow the specified substring in the source string.
Behind the scenes, this function is translated to the following XPath function: substring-after()
substring-after($arg1 as xs:string?, $arg2 as xs:string?) as xs:string
Rules:
If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
If the value of $arg2 is the zero-length string, then the function returns the value of $arg1.
If the value of $arg1 does not contain a string that is equal to the value of $arg2, then the function returns the zero-length string.
Substring before
This function states that it returns the characters that precede the specified substring in the source string.
Behind the scenes, this function is translated to the following XPath function: substring-before()
substring-before($arg1 as xs:string?, $arg2 as xs:string?) as xs:string
Rules:
If the value of $arg1 or $arg2 is the empty sequence or contains only ignorable collation units, it is interpreted as the zero-length string.
If the value of $arg2 is the zero-length string, then the function returns the zero-length string.
If the value of $arg1 does not contain a string that is equal to the value of $arg2, then the function returns the zero-length string.
Trim
This function states that it returns the specified string with all the leading and trailing white space characters removed.
Behind the scenes, this function is translated to the following XPath function: replace()
replace($input as xs:string?, ‘^s*|s*$’, ”)
This is a specific call to the replace() function where the second and third arguments are already specified behind the scenes. Trim functoid is an abstraction of this replace() function call.
Trim left
This function states that it returns the specified string with all the leading white space characters removed.
Behind the scenes, this function is translated to the following XPath function: replace()
replace($input as xs:string?, ‘^s+’, ”)
This is a specific call to the replace() function where the second and third arguments are already specified behind the scenes. Trim functoid is an abstraction of this replace() function call.
Trim right
This function states that it returns the specified string with all the trailing white space characters removed.
Behind the scenes, this function is translated to the following XPath function: replace()
replace($input as xs:string?, ‘s+$’, ”)
This is a specific call to the replace() function where the second and third arguments are already specified behind the scenes. Trim functoid is an abstraction of this replace() function call.
Uppercase
This function states that it returns a string in uppercase format.
Behind the scenes, this function is translated to the following XPath function: upper-case()
upper-case($arg as xs:string?) as xs:string
Rules:
If the value of $arg is the empty sequence, the zero-length string is returned.
Otherwise, the function returns the value of $arg after translating every character to its upper-case correspondent as defined in the appropriate case mappings section in the Unicode standard.
Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more, you can buy (or help buy) my son a Star Wars Lego!
Author: Sandro Pereira
Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc.
He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.
View all posts by Sandro Pereira
I love this project! I have much fun doing it, and I use it a lot in my clients. So for me is what I call a win-win situation. So today I update BizTalk Mapper Extensions UtilityPack project with one new Functoid that you can use on your BizTalk Server maps Functoid: String Splitter Functoid.
Last week I had the needed to use a particular mapping functionality several times in different maps:
Extract one specific subset of a concatenated string;
For example “AA.123.SANDRO.312” and I need to extract the third position: “SANDRO”
My first strategy was to create a Scripting Functoid, but because I have to use it in different maps, I quickly change my approach and created this new Functoid that now you can use inside your BizTalk Server maps.
String Splitter Functoid
This functoid allows you to convert a string to a number (integer)
Parameters
This functoid split a string by a specific splitter character, and it accepts 3 inputs:
The first parameter is the input value to be split;
AA.123.SANDRO.312
AA-123-SANDRO-3122.
The second parameter is the position to be returned (the subset of the string to be retrieved);
The third parameter is the splitter character;
The output of the functoid will be a string present in the split array, example: SANDRO
In this In sample described in the above picture, we are receiving a string: “AA.123.SANDRO.312.1” and we want to retrieve the fourth subset of the concatenated string delimited by “.” character. So, in this case, the functoid will return: “1”.
BizTalk Mapper Extensions UtilityPack is a set of libraries with several useful functoids to include and use it in a map, which will provide an extension of BizTalk Mapper capabilities.
Where to download?
You can download this functoid along with all the existing one on the BizTalk Mapper Extensions UtilityPack here: BizTalk Mapper Extensions UtilityPack GitHub
Author: Sandro Pereira
Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community. View all posts by Sandro Pereira