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 Conversion functoids are:
To DateTime: Returns the specified value as a DateTime value.
To integer: Returns the specified value as an integer.
To number: Returns the specified value as a number.
To string: Returns the specified value as a string.
To DateTime
This function states that it returns the specified value as a DateTime value.
Behind the scenes, this function is translated to a Type casting rule in XQuery: date()
date(string?)
Rules:
Castable values are restricted by the target types implementation restrictions. For example, you cannot cast a date string with a negative year to xs:date. Such casts will result in the empty sequence if the value is provided at run time (instead of raising a run-time error).
To integer
This function states that it returns the specified value as an integer.
Behind the scenes, this function is translated to the following XPath function: number()idiv 1
number($arg as xs:anyAtomicType?) as xs:doubleidiv 1
Note: idiv is an integer division operator. XPath supports two division operators named div and idiv. Each of these operators accepts two operands of any numeric type. $arg1 idiv $arg2 is equivalent to ($arg1 div $arg2) cast as xs:integer? except for error cases.
Rules:
If $arg is the empty sequence, or if $arg cannot be converted to an xs:double, the xs:double value NaN is returned.
Otherwise, $arg is converted to an xs:double following the rules of casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.
To number
This function states that it returns the specified value as a number.
Behind the scenes, this function is translated to the following XPath function:: number()
number($arg as xs:anyAtomicType?) as xs:double
Rules:
If $arg is the empty sequence, or if $arg cannot be converted to an xs:double, the xs:double value NaN is returned.
Otherwise, $arg is converted to an xs:double following the rules of casting to xs:double. If the conversion to xs:double fails, the xs:double value NaN is returned.
To string
This function states that it returns the specified value as a string.
Behind the scenes, this function is translated to a Type casting rule in XQuery: string()
string string(object?)
Rules:
A node-set is converted to a string by returning the string-value of the node in the node-set that is first in document order. If the node-set is empty, an empty string is returned.
A number is converted to a string as follows
NaN is converted to the string NaN
positive zero is converted to the string 0
negative zero is converted to the string 0
positive infinity is converted to the string Infinity
negative infinity is converted to the string -Infinity
if the number is an integer, the number is represented in decimal form as a Number with no decimal point and no leading zeros, preceded by a minus sign (-) if the number is negative
otherwise, the number is represented in decimal form as a Number including a decimal point with at least one digit before the decimal point and at least one digit after the decimal point, preceded by a minus sign (-) if the number is negative; there must be no leading zeros before the decimal point apart possibly from the one required digit immediately before the decimal point; beyond the one required digit after the decimal point there must be as many, but only as many, more digits as are needed to uniquely distinguish the number from all other IEEE 754 numeric values.
The boolean false value is converted to the string false. The boolean true value is converted to the string true.
An object of a type other than the four basic types is converted to a string in a way that is dependent on that type.
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
In a general and abstract way, we can say that Data Mapper maps are graphical representations of XSLT 3.0 (Extensible Stylesheet Language Transformation) documents that allow us to perform simple and visual transformations between XML and JSON messages (more formats will be added in the future). But in reality, Data Mapper maps are composed of two files: a Map Definition file (.yml) that basically is an abstraction of the underlying implementation. And one XSLT file (.xslt) contains all the transformation rules – This is the file that in runtime will be executed by the Logic Apps (standard) engine.
What types of transformation can we apply in Logic Apps?
Similar to BizTalk Server, we can define two types of transformations:
Syntax Transformations: In BizTalk Server, this type of transformation occurs in receive or send pipelines and aims to transform a document into another representation, e.g., CSV to XML. In Logic Apps, that will occur inside the Logic Apps by using an Integration Account or certain actions and expressions depending on which syntax transformation we need to perform. Here the document maintains the same data (semantics) but changes the syntax that is represented. I.e., we translate the document, but typically we don’t modify the structure. Normally, this type of transformation is bidirectional, since we still have the same semantic content, we can apply the same transformation logic and obtain the document in its original format.
Semantic Transformations: In BizTalk Server, this type of transformation usually occurs only in BizTalk maps. Inside Logic Apps (Standard), they will take place in the Data Mapper. Here the document can maintain the same syntax that is represented (XML or JSON) – not mandatory since Data Mapper supports at the moment JSON Schemas and XML Schemas – but changes its semantics (data content). These types of transformations are typically one-way. Since we add and aggregate small parts of the information that compose the document into another document, we may miss important details for its reconstruction.
Introduction to the Data Mapper
The Data Mapper enables us to perform transformations of complex messages visually and effortlessly, graphically represented by links that define the relationships between the various elements of messages.
These relationships between elements are internally implemented as XSL Transformations (XSLT – Extensible Stylesheet Language Transformation), the standard Worldwide Web Consortium (W3C) recommended to perform message transformations.
Data Mapper is a Visual Code extension that allows you to perform mapping transformations. Currently, it has its own extension, but that will be merged with the main extension in the future.
Essentially the editor consists of three main modules:
Source Schema view: this is the data structure of the source message and is on the left side of the main window;
Destination Schema view: this is the data structure of the target message and is on the right side of the main window; the links that define the mapping lead into the destination schema tree view from the grid view, and ultimately from the source schema tree view.
Mapping areaview: is in the middle of the main window, between the two data structures (source and target); This area plays a critical role in the definition of maps, containing the links and Functions that control how data in a source instance message is transformed into an instance message that conforms to the destination schema. The mapping area can have multiple layers, each of them associated with a specific record on the destination schema, allowing us this way to organize complex maps in a better way.
Apart from these three modules, there are other important windows for the developer:
Function panel: At the left side of the source schema, providing access to all Functions we can use in the Data Mapper.
Function properties panel: in this panel, we can see and modify the properties of a selected function inside the Data Mapper.
Task List and Output windows: much of the time hidden, we can and must use these windows to examine the results of saving and testing we do in our maps. These windows normally appear underneath the Mapping area or the Function properties panel.
Code view Panel: On this panel, you can view Map definitions rules (abstraction of the underlying implementation). It is a read-only panel.
Basic maps functionalities (Document mapping)
There are several mapping functionalities that you can perform inside maps, like Data normalization, Transform Injection (XLST injection), calculating values covering math and scientific functoids, and so on. Still, most of the time, transformations are quite simple, and when we perform a transformation in the message 5 basic functionalities typically arise:
Simple mapping of a given value (direct copy)
Concatenation of values
Conditional selection
Custom scripts
Add new values (data)
Here we will take a simple transformation problem that will address each one of these functionalities or operations, providing a simple example of how to accomplish this inside the Data Mapper. Of course, there are plenty of other operations or transformation rules that we could do that will not be addressed here.
Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more content, 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
Used to perform a variety of operations over collections, such as cumulative sum, short, or get distinct values.
Average, Count, Direct Access, Distinct Values, Filter, Index, Join, Maximum, Minimum, Reverse, Sort, Sub Sequence, Sum
Conversion
Used to convert values to specific times.
To DateTime, To integer, To number, To string
Date and TimeUsed to perform a variety of operations over Dates, such as retrieving the current date and time or adding dates.
Add days, Add DayTime to Date, Add DayTime to DateTime, Add DayTime to Time, Add YearMonth to DateTime, Adjust Date, Adjust DateTime, Adjust Time, Current date. Current DateTime value, Current time, DateTime, Day from DAte, Day from DateTime, Equal Date, Equal DateTime, Equal Day, Equal Month, Equal MonthDay, Equal Time, Equal Year, Equal YearMonth, Greater Date, Greater DateTime, Greater Time, Hours from DateTime, Hours from Time, Less Date, Less DateTime, Less Time, Minutes from DateTime, Minutes from Time, Month from Date, Month from DateTime, Seconds from DateTime, Seconds from Time, Subtract Dates, Subtract DateTimes, Subtract DateTime from Date, Subtract DateTime from DateTime, Subtract DateTime from Time, Subtract Times, Subtract YearMonth from Date, Subtract YearMonth from DateTime, Time zone from Date, Time zone from DateTime, Time zone from Time, Year from Date, Year from DateTime.
Logical comparisonUsed to perform a variety of logical operations, such as greater than and logical existence.
Equal, Exists, Greater, Greater or equal, if, if else, Is date, Is DateTime, Is nil, Is null, Is number, Is string, Less, Less or equal, Logical AND, Logical NOT, Logical OR, Not equal
MathematicalUsed to perform a variety of mathematical and scientific operations, such as addition and multiplication.
Used to perform a variety of string functions, such as trimming and concatenation.
Codepoints to string, Concat, Contains, Ends with, Length, Lowercase, Name, Regular expression matches, Regular expression replace, Replace, Start with, String to codepoints, Substring, Substring after, Substring before, Trim, Trim left, Trim right, Uppercase
Utility
Used to perform a variety of additional and distinct operations that don’t fit in the above Categories, such as stopping a transformation and returning the specified error code and description or format a number or a date.
Copy, Error, Format date, Format DateTime value, Format number, Format time
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
Today, after almost 3 years since I did the last update on the package, I updated it with a new suite of functoids that are now part of the BizTalk Mapper Extensions UtilityPack project available for BizTalk Server 2020: DateTime Functoids.
DateTime Functoids
This library includes a suite of functoids to perform several DateTime operations that you can use inside the BizTalk mapper.
This project, for now, only contains a single custom Functoid:
Get Current Date Functoid: This functoid allows you to get the current date and/or time in a specific format.
This functoid requires one input parameter:
date, time, or DateTime format;
Examples:
Input yyyyMMdd >>> Output = 20230526
Input HHmm >>> Output = 1519
BizTalk Mapper Extensions UtilityPack
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 can I download it?
You can download the complete Azure Function source code here:
Hope you find this helpful! So, if you liked the content or found it helpful and want to help me write more content, 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
Last weekend I delivered a session about BizTalk Server 2020 in action on Global Integration Bootcamp 2020 Madrid, where I spoke about the new features available in the most recent version of the product.
Today I will start this series of blog posts about what’s new in BizTalk Server 2020 by beginning to speak about one of the most expected and log time requested features: XSLT 3.0 Support.
XSLT 3.0 represents a significant upgrade of the XSLT 1.0 (and even XSLT 2.0) standards to become a general-purpose transformation language for the most common data storage and messaging formats.
There are a lot of advantages to using XSLT 3.0 compare with the XSLT 1.0 or, in fact, XSLT 2.0, and the goal here is not to address every single of them, but we can highlight the following one:
Extended Function Set, Sequences, Arrays, and Maps: The initial function set for XSLT1.0 was the same as XPath 1.0 functions and was very limited. Minimal math support, no regular expression support, minimal string manipulation capabilities, no support for set (sequence) operations, no support for dates.
Grouping:
xsl:for-each-group: a set of items can be selected and arranged into groups based on specific criteria (for example, common values); then each group can be processed in turn
special XPath functions within for-each-group: current-grouping-key(), currentgroup()
Variants of <xsl:for-each-group>:
group-adjacent: adjacent items are allocated to the same group if they have common values for the grouping key
group-starting-with: whenever an item matches the pattern, a new group is started with this item
group-by: whenever an item matches the pattern, a new group is started after this item
Sorting:
xsl:sort: can be used inside of <xsl:for-each>, <xsl:for-each-group>, <xsl:applytemplates> and <xsl:perform-sort>. It defines the order in which the data is processed by the instruction.
Several subsequent sort keys can be defined
BizTalk’s default XSL transform engine implementation is based on .Net Framework XSLT Transformations. This support is limited to XSLT 1.0.
Starting with BizTalk Server 2020, users can choose Saxon:registered: 9 (Saxon 9 HE) as the XSLT transform engine. But most importantly, it will be possible to plug-in your own custom XSLT transform engine.
YYou can implement a custom XSLT transform engine by defining XSLT transform implementation derived from abstract class Microsoft.XLANGs.BaseTypes.ITransform2 in assembly Microsoft.XLANGs.BaseTypes.dll.
This makes it possible for BizTalk server maps to support newer versions of XSLT. Using Saxon 9 HE, we can readily use XSLT3.0.
Use XSLT Transform Engine property to specify the XSLT transform engine you wish to use:
This was one of the most expected features, but be careful, this can be a poisoned gift because Saxon 9 HE doesn’t support embedded scripting. As a result, functoids shipped as part of BizTalk may not function well. And for many cases, this can be a showstopper.
The advantages of using XSLT 3.0 with Saxon 9 HE:
Development: The XSLT file can be developed separately and hosted in a BizTalk map. It will simplify specific scenarios, especially scenarios that grouping and sorting are required. As we mentioned above, XSLT 3.0 provides an extended set of functions, which was very limited within XSLT 1.0.
Disadvantages when using XSLT 3.0 with Saxon 9 HD:
Level of effort: Not quite as intuitive, Functoids are easier to read visually on the map grid and therefore Requires “geeky” coding skills.
Overview: You lose the visual map representation. You can conjugate Saxon 9 HE with the BizTalk Mapper, but it is harder to do it.
BizTalk Mapper Editor limitations: except for a few built-in Functoids like Scripting Functoid (not all script types will work properly) or advance Functoids, BizTalk Functoids will not work while using the Saxon 9 HE XSLT Transformation Engine.
BizTalk Development Tool Integration: it is a brand new feature, and it seems that doesn’t have, at least for now, the same level of integration capabilities with the BizTalk Server development tools that we are usual to have and use if we compared with the default transformation engine
Today we will address the last suite of functoids that are part of the BizTalk Mapper Extensions UtilityPack project available for BizTalk Server 2020: Math Functoids. And with this blog post, we finally arrive to the end of this project migration.
Math Functoids
This library includes a suite of functoids to perform a variety of basic mathematical operations that you can use this inside BizTalk mapper.
This project includes the following Custom Functoids:
Negate Number Functoid: Use Negate Functoif to return the input double as its negated form.
This functoid requires one input parameter:
A number (double or int) to be negated;
The output result will be the input value in his negative form. If it’s positive, it will return as negative and vice-versa.
Examples:
Input 1 >>> Output = -1
Input -23,09 >>> Output = 23,09
Input 0 >>> Output = 0
SmartRound Functoid: Use SmartRound to return the rounded double, by the second parameter input.
The functoid takes two mandatory input parameters:
Parameter 1: Number to be rounded (double or int)
Parameter 2: Number to decimals places
The output of the functoid will be the input number rounded up or down to the specified decimal places.
Examples:
Input 23 rounded to 2 >>> Output = 23,00
Input 24,005900 rounded to 3 >>> Output = 24,006
BizTalk Mapper Extensions UtilityPack
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:
This library includes a suite of functoids to perform a variety of database operations, mainly to extract data from a database for use in an output instance message.
This project includes the following Custom Functoids:
Adv Database Lookup Functoid: Use the Adv Database Lookup functoid to extract information from a database and store it as a Microsoft ActiveX Data Objects (ADO) recordset.
This functoid requires the following 3 inputs:
a database connection string;
A table name;
and a WHERE clause.
Returns a recordset containing the result records.
Adv Value Extractor: Use the Adv Value Extractor functoid to extract the appropriate column value from a recordset returned by the Adv Database Lookup function.
This functoid requires two inputs parameters:
a link to the Adv Database Lookup functoid;
and a column name.
Returns a string with the value of the specified column;
BizTalk Mapper Extensions UtilityPack
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:
Todas we will address one of my favorites suite of functoids that will be available for BizTalk Server 2020: Logical Functoids. This is part of the BizTalk Mapper Extensions UtilityPack project migration task I been doing in the last few days.
Logical Functoids
This library includes a suite of functoids to perform a variety of logical operations, often controlling whether a particular element or attribute is created in an output instance message. Most of the Logical Functoids are a replica of the existent Logical Functoids that came with BizTalk Server with the advantage that these will allow you to connect with others Custom String Functoids. They are fully compatible with existing functoids and don’t produce any more additional code.
This project includes the following Custom Functoids:
Advance Logical AND Functoid: Use the Advance Logical AND functoid to return the logical AND of input parameters. It determines whether all of the specified input parameters are true.
This functoid requires a minimum of two input parameters and a maximum of one hundred:
Parameter 1: A value that can be evaluated as either True or False.
Parameters 2 – 100: Values that can be evaluated as either True or False.
Returns the logical AND of parameters. True if all of the specified input parameters evaluate to True; False otherwise.
Advance Equal Functoid: Use the Advance Equal functoid to return the value “true” if the first input parameter is equal to the second input parameter. It tests whether the two input parameters are equal.
This functoid requires two input parameters:
Parameter 1: A value to be tested for equality with parameter 2.
Parameter 2: A value to be tested for equality with parameter 1.
Returns True if the values of the two input parameters are equal; False otherwise.
Advance Greater Than Functoid: Use the Advance Greater Than functoid to return the value “true” if the first input parameter is greater than the second input parameter. It tests whether the first input parameter is greater than the second input parameter.
This functoid requires two input parameters:
Parameter 1: A value to be tested to determine whether it is greater than parameter 2.
Parameter 2: A value to be tested to determine whether it is greater than parameter 1.
Returns True if the value of the first input parameter is greater than the value of the second input parameter; False otherwise.
Advance Greater Than or Equal To Functoid: Use the Advance Greater Than or Equal To functoid to return the value “true” if the first input parameter is greater than or equal to the second input parameter. It tests whether the first input parameter is greater than or equal to the second input parameter.
This functoid requires two input parameters:
Parameter 1: A value to be tested to determine whether it is greater than or equal to parameter 2.
Parameter 2: A value to be tested to determine whether it is greater than or equal to parameter 1.
Returns True if the value of the first input parameter is greater than or equal to the value of the second input parameter; False otherwise.
Advance Less Than Functoid: Use the Advance Less Than functoid to return the value “true” if the first input parameter is less than the second input parameter. It tests whether the first input parameter is less than the second input parameter.
This functoid requires two input parameters:
Parameter 1: A value to be tested to determine whether it is less than parameter 2.
Parameter 2: A value to be tested to determine whether it is less than parameter 1.
Returns True if the value of the first input parameter is less than the value of the second input parameter; False otherwise.
Advance Less Than or Equal To Functoid: Use the Advance Less Than or Equal To functoid to return the value “true” if the first input parameter is less than or equal to the second input parameter. It tests whether the first input parameter is less than or equal to the second input parameter.
This functoid requires two input parameters:
Parameter 1: A value to be tested to determine whether it is less than or equal to parameter 2.
Parameter 2: A value to be tested to determine whether it is less than or equal to parameter 1.
Returns True if the value of the first input parameter is less than or equal to the value of the second input parameter; False otherwise.
Advance Not Equal Functoid: Use the Advance Not Equal functoid to return the value “true” if the first input parameter is not equal to the second input parameter. It tests whether the two input parameters are not equal.
This functoid requires two input parameters:
Parameter 1: A value to be tested for inequality with parameter 2.
Parameter 2: A value to be tested for inequality with parameter 1.
Returns True if the values of the two input parameters are not equal; False otherwise.
Advance Logical NOT Functoid: Use the Advance Logical NOT functoid to return the logical inversion of the input parameter. Use to logically negate the value of the Boolean input parameter.
This functoid requires one input parameter only:
Parameter 1: A value that can be evaluated as either True or False.
Returns True if the specified input parameter evaluates to False; False otherwise.
Advance Logical OR Functoid: Use the Advance Logical OR functoid to return the logical OR of input parameters. The input parameters have to be Boolean or numeric. It determines whether any of the specified input parameters are true.
This functoid requires a minimum of two input parameters and a maximum of one hundred:
Parameter 1: A value that can be evaluated as either True or False.
Parameters 2 – 100: Values that can be evaluated as either True or False.
Returns True if any of the specified input parameters evaluate to True; False otherwise.
If-Then-Else Functoid: Use the If-Then-Else Functoid to return a value from one of two input parameters based on a condition. If the condition (first input) is True, then the value of the second input parameter is returned, otherwise, the Third input is returned.
This functoid requires three input parameters:
A boolean representing the result of a previous condition
The value to be returned if the condition is True.
The value to be returned if the condition is False.
If the condition is True, then the value of the second input parameter is returned, otherwise, the third input is returned.
BizTalk Mapper Extensions UtilityPack
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:
