Integration Advisor – Mapping element functions for comparing nodes and values

[gunther_stuhec]

This blog describes the diverse functions for comparing the content of two input items, which can be atomic values of node structures. The result can be either a boolean value of “true” or “false”, or an integer for rating the comparison. These functions can be combined with other XPath based functions. The functions are:

• compare compares two inputs and tells which of them is greater or if both are equal


• contains tells if one input string contains another, smaller, input string


• deep-equal compares the sequences of two input nodes for a deep equality


• ends-with tells if one input string ends with another, smaller, input string


• matches compares two inputs by using regular expression


• starts-withtells if one input string starts with another, smaller, input string

compare

compare($arg as string?, $arg2 as string?[, $collation as sting]?)

The compare function compares two string-based input values from either source leaf nodes or from outputs of other, embedded functions. The result is an integer value, which represents the following values:

• -1 – If the first input value is in alphabetical and numerical order lower than the second input value.


• 0 – If the first input value is in alphabetical and numerical order equal to the second input value.


• 1 – If the first input value is in alphabetical and numerical order greater than the second input value.

Furthermore an input value is greater than the other input value, if it has the same set of characters plus additional characters at the end. For example, “Salem cum pane” is greater than “Salem”.

It may be more convenient to use the comparison operators (See ##BLOG##), because these are just simple characters representing the operations. The exception is the collation of precise linguistic comparison such as the German “ß” and “ss”. If this is the case, it is necessary to use the compare function.

Input	Occur.	Base type	Description
$arg	1..1	string?	First string-based comparand
$arg2	1..1	string?	Second string-based comparand
$collation	0..1	string	Defines the collation of a character map such as the German character ß might count as equal to ss.
Output		integer?

 

Example 1

The first example returns -1, because the value of the first leaf node (D_4440) in the function is alphabetically lower than the value of the second node (D_4440_2) in the function.

Figure 1: First value is lower than second value

Example input values, function and output:

Input	D_4440: 'Cogito, ergo sum' D_4440_2: 'Ego sum, qui sum'
Function	<xsl:value-of select="compare($nodes_in/D_4440, $nodes_in/D_4440_2)"/>
Output	-1

Example 2

Like shown in the following figure, the value of the first leaf node in the function is higher than the value of the second leaf node in the function in the alphabetical order.

Figure 2: First value is higher than second value

Example input values, function and output:

Input	D_4440_2: 'Ego sum, qui sum' D_4440_3: 'Cogito, ergo sum'
Function	<xsl:value-of select="compare($nodes_in/D_4440_2, $nodes_in/D_4440_3)"/>
Output	1

Example 3

The third example displays that both values are equal. Shown in the following figure, the result is 0.

Figure 3: First value is equal to second value

Example input values, function and output:

Input	D_4440: 'Cogito, ergo sum' D_4440_3: 'Cogito, ergo sum'
Function	<xsl:value-of select="compare($nodes_in/D_4440, $nodes_in/D_4440_2)"/>
Output	0

Example 4 and 5

The two examples show the difference, if you use the @collation attribute. Shown in Figure 4, the fourth example does not have the @collation attribute. This leads to -1, because the sum of the codepoint order of the first value is lower than the second value.

Figure 4: Comparison without @collation

The two examples show the difference, if you use the @collation attribute. Shown in Figure 4, the fourth example does not have the @collation attribute. This leads to -1, because the sum of the codepoint order of the first value is lower than the second value.

Figure 5: Comparison with @collation

The fifth example in Figure 5 uses the @collation attribute with the reference to UCA (Unicode Collation Algorithm) collation: http://www.w3.org/2013/collation/UCA?lang=de;strength=primary. The aim of UCA is to compare strings considering the variations of locals and languages such as the German specific character map (see also: https://www.saxonica.com/documentation/#!extensibility/config-extend/collation/UCA and https://unicode.org/reports/tr10/ ). By using the German locale, the comparison result is 0, because the character “ß” is the same as “ss” in German.

Example 4 input values, function and output:

Input	D_4440_4: 'Grosse Latinum Strasse' D_4440_5: 'Große Latinum Straße'
Function	<xsl:value-of select="compare($nodes_in/D_4440_4, $nodes_in/D_4440_5)"/>
Output	-1

Example 5 input values, function and output:

Input	D_4440_4: 'Grosse Latinum Strasse' D_4440_5: 'Große Latinum Straße'
Function	<xsl:value-of select="compare($nodes_in/D_4440_4, $nodes_in/D_4440_5, 'http://www.w3.org/2013/collation/UCA?lang=de;strength=primary')"/>
Output	0

contains

contains($arg as string?, $arg2 as string?[, $collation as sting]?)

The contains function can be used for searching a substring in a longer input string. The substring could be anywhere in the longer input string. It returns a Boolean true, if the substring exists in any place of the longer input string.

Remark: The use of $collation is already explained in the chapter of function compare.

Input	Occur.	Base type	Description
$arg	1..1	string?	First string-based comparand
$arg2	1..1	string?	Second substring, which should be shorter than first string.
$collation	0..1	string	Defines the collation of a character map such as the German character ß might count as equal to ss.
Output		boolean	true|false

Example

The following example shows two mapping elements with the function contains. Based on the set input text, first mapping element returns a true because the text of node D_4440_2 is in the input text of node D_4440. The second mapping element returns a false because the input text of node D_4440_3 is not a part of the text in node D_4440.

Figure 6: Function compare with true and false result.

Example input values, function and output:

Input	D_4440: 'Hic tu qua laetitia perfruere' D_4440_2: 'laetitia'
Function	<xsl:value-of select="contains($nodes_in/D_4440, $nodes_in/D_4440_2)"/>
Output	true

 

Input	D_4440: 'Hic tu qua laetitia perfruere' D_4440_3: 'caligo'
Function	<xsl:value-of select="contains($nodes_in/D_4440, $nodes_in/D_4440_3)"/>
Output	false

deep-equal

deep-equal($arg as item()*, $arg2 as item()*[, $collation as sting]?)

The function deep-equal compares the sequences of two input nodes for a deep equality. It also includes the substructures of the two input nodes. This function returns a boolean 'true', if the comparing sequences contain the same values in same order.

The use of deep-equal in Integration Advisor is limited, since Integration Advisor just allow the mapping and comparison of leaf nodes. Like the following example shows, it is possible to compare the content of a set of different source leaf nodes.

Remark: The use of $collation is already explained in the chapter of function compare.

Input	Occur.	Base type	Description
$arg	1..1	string?	First sequence comparand
$arg2	1..1	string?	Second sequence comparand
$collation	0..1	string	Defines the collation of a character map such as the German character ß might count as equal to ss.
Output		boolean	true|false

Example

Like in the following figure shown, the deep-equal can be used of the comparison of a number of source leaf nodes, which exists in different qualified groups. For example the first two leaf nodes of the first qualified group will be compared with the first two leaf nodes of the second qualified group. The first case shows the "true" case and the second case is the "false" case in where the example text of the last leaf node is different.

Figure 07: Possible use of deep-equal

Example input values, function and output of case 1:

Input	Group 1 D_4440[1]: 'Hic tu qua laetitia perfruere' D_4440_2[1]: 'Similis simili gaudet.' Group 2 D_4440[2]: 'Hic tu qua laetitia perfruere' D_4440_2[2]: 'Similis simili gaudet.'
Function	<xsl:value-of select="deep-equal(($nodes_in/D_4440[1], $nodes_in/D_4440_2[1]), ($nodes_in/D_4440[2], $nodes_in/D_4440_2[2]))"/>
Output	true

Example input values, function and output of case 2:

Input	Group 1 D_4440_3[1]: 'Quaere et invenies' D_4440_4[1]: 'Quaere et invenies?' Group 2 D_4440[_32]: 'Quaere et invenies' D_4440_4[2]: 'Ne discere cessa'
Function	<xsl:value-of select="deep-equal(($nodes_in/D_4440_3[1], $nodes_in/D_4440_3[1]), ($nodes_in/D_4440_4[2], $nodes_in/D_4440_4[2]))"/>
Output	false

ends-with

ends-with($arg as string?, $arg2 as string?[, $collation as sting]?)

The function ends-with returs a boolean 'true', if the input string of the first argument ($arg1) has at the end the same sting like the input string of the second argument ($arg2).

Remark: The use of $collation is already explained in the chapter of function compare.

Input	Occur.	Base type	Description
$arg	1..1	string?	First, longer string in which the second substring $arg should be at the end
$arg2	1..1	string?	Second substring, which should be at the end of the first string  of first argument ($arg)
$collation	0..1	string	Defines the collation of a character map such as the German character ß might count as equal to ss.
Output		boolean	true|false

Example

The following example displays two cases of the use of ends-with. The first case is the true case in where the string of second argument 'tenebat' matches to the end of the input string and the second case is the the false case in where this string does not match to the end of the input string.

Figure 8: Use of function ends-with

Example input values, function and output of case 1:

Input	D_4440: 'Omnia norat, omnium aditus tenebat'
Function	<xsl:value-of select="ends-with($nodes_in/D_4440, 'tenebat')"/>
Output	true

Example input values, function and output of case 2:

Input	D_4440_2: 'Atque ego, ut vidi, quos maximo furore’
Function	<xsl:value-of select="ends-with($nodes_in/D_4440, 'tenebat')"/>
Output	false

matches

matches($input as string?, $pattern as string)

The matches function is more comprehensive than starts-with and ends-with. It compares the input string of the first argument ($arg) with a regular expression ($pattern) and returns “true”, if the string matches the given regular expression. The regular expression is a very powerful feature in the context of XPath functions. It allows to define patterns of characters or spaces, which can be searched in specific positions of the input string. The blog ###BLOG### gives you further details of how to use the regular expression in Integration Advisor. This function supports collations, but it has an additional $flags argument, which optionally enforces the interpretation of a regular expression.

Input	Occur.	Base type	Description
$arg	1..1	string?	The input value string, which is matched against the regular expression
$pattern	1..1	string?	The regular expression, which expresses the matching pattern
$flags	0..1	string	This argument might have one or more values for controlling the further interpretation of the regular expression. It is possible to set several flags between single quotation marks. The values should be separated by a comma. The following values are supported: i – for ignoring the lower and upper cases in the input string m – for consideration of the line feeds in the input string s – it sets to the so-called “dot-all” mode x – it deactivates the consideration of whitespace characters in the input string, such as #x9, #xA, #xD und #x20 .
Output		integer?

Example

The example considers two cases. The first case can be compared with the ends-with function, because the $ character in the regular expression argument marks the end of a string and there is the string “tenebat” in front of this $ character. The second case gives an example about how the starts-with function can be expressed in a more powerful way.

Figure 9: Definitions of regular expressions in matches function

Example input values, function and output for case 1:

Input	D_4440: 'Omnia norat, omnium aditus tenebat'
Function	<xsl:value-of select="matches($nodes_in/D_4440, 'tenebat$')"/>
Output	true

Example input values, function and output for case 2:

Input	D_4440_2: 'Atque ego, ut vidi, quos maximo furore’
Function	<xsl:value-of select="matches($nodes_in/D_4440_2, '^[a-z]*', 'i')"/>
Output	true

starts-with

starts-with($arg as string?, $arg2 as string?[, $collation as sting]?)

The function can be used for testing, if an input string $arg1 starts with a specific substring $arg2. It returns a Boolean “true”, if this is the case.

Input	Occur.	Base type	Description
$arg	1..1	string?	First, longer string in which the substring of the second argument ($arg2) should be at the beginning
$arg2	1..1	string?	Second substring, which should be at the beginning in the string of the first argument ($arg)
$collation	0..1	string	Defines the collation of a character map such as the German character ß might count as equal to ss.
Output		integer?

Example

The following example displays two cases of the use of starts-with. The first case is the true case in where the string of second argument 'Omnia' matches to the beginning of the input string and the second case is the the false case in where this string does not match to the beginning of the input string.

Figure 9: Use of starts-with function

Example input values, function and output of case 1:

Input	D_4440: 'Omnia norat, omnium aditus tenebat'
Function	<xsl:value-of select="starts-with($nodes_in/D_4440, 'Omnia')"/>
Output	true

Example input values, function and output of case 2:

Input	D_4440_2: 'Atque ego, ut vidi, quos maximo furore'
Function	<xsl:value-of select="starts-with($nodes_in/D_4440_2, 'Omnia')"/>
Output	false

Summary

There are a number of functions for comparing two different input values. As I said, the use of the function "deep-equal" is limited while creating mapping element functions in a Mapping Guideline. But once, I will find further use cases I'm going to provide it to use via a further best-practice blog. Additionally, the function "matches" is very powerful, especially if you are familiar with the regular expression. A further blog ###BLOG### will give you some further details regarding the use of regular expressions in Integration Advisor. We also have concepts on our backlog, which allows a kind of comparison of input values without any coding. This works similar "String Processing" in where you have just give some comparison instructions via check boxes. If you like that the priority of this feature will be increased in the backlog, please go to the  influence campaign of Integration Suite (https://influence.sap.com/sap/ino/#/campaign/2282) and either make a new improvement request or vote for it, if already exists.

Further Reading

Read the following blog posts for more information related to the MAG editor and the functions:

• Integration Advisor – List of support XSLT elements and XPath functions


• integration content advisor: Create a mapping using MAG editor


• Integration Advisor – Quickly create your individual code value mappings in MAGs


• Integration Advisor: Functions at target side – Ordinal number for line items and segment count