Integration Advisor – Mapping element functions, the use of xsl:copy, xsl:copy-of, xsl:sequence, or xsl:value-of
Once you start the creation of a mapping function, you find the XSLT element xsl:sequence as the default in the function editor box. This element writes sequences of nodes and/or atomic values into the output. XSLT connoisseurs know that XSLT offers further elements that you can use to write values into the output nodes. Apart from xsl:sequence, usable elements are xsl:copy-of, or xsl:value-of in the Integration Advisor. To use the elements, it is quite helpful to understand the behaviour of the XSLT elements in the context of a mapping element. The elements have a significant different behaviour. This blog especially describes the behaviour and output of the XSLT elements, if you use them in mapping functions of a mapping element.
Usual Behaviour of xsl:sequence, xsl:copy-of, xls:value-of and xsl:copy
If you use the XSLT elements xsl:sequence, xsl:copy-of, or xsl:value-of in a XSLT script that is not generated by Integration Advisor, you get the following differences:
- xsl:sequence – is a reference to the input object and returns the input without any changes as a sequence and/or atomic values to the output.
- xsl:copy-of – returns a complete copy of the input and writes it to the output.
- xsl:value-of – returns an atomic value of the selected node and may all descendant text-based nodes. The values of the nodes are joined.
- xsl:copy – creates a copy from the current node in the input into the output.
Both, xsl:sequence and xsl:copy-of have a similar behavior and can replace each other in most cases. The main difference between xsl:sequence and xsl:copy-of can be expressed by the following example that clearly shows the referencing character of xsl:sequence.
<?xml version="1.0" encoding="UTF-8"?> <OrderRequest_In> <Order> <Text> <TextElementLanguage>Latin</TextElementLanguage> <TextElementText>Sed ut perspiciatis unde omnis iste natus error si</TextElementText> </Text> </Order> </OrderRequest_In>
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:output indent="yes"/> <xsl:template match="/OrderRequest_In/Order"> <xsl:variable name="vSeq" as="element()"> <xsl:sequence select="./Text/TextElementText"/> </xsl:variable> <xsl:variable name="vCopy" as="element()"> <xsl:copy-of select="./Text/TextElementText"/> </xsl:variable> <Languages> <Language> <xsl:value-of select="$vSeq/../TextElementLanguage"/> </Language> <Language> <xsl:value-of select="$vCopy/../TextElementLanguage"/> </Language> </Languages> </xsl:template> </xsl:stylesheet>
Both variables, $vSeq and $vCopy, contain the element and value of TextElementText. But the TextElementText in variable $vSeq is just a reference and the input object is still known. The variable $vCopy keeps a copy of TextElementText. The output displayed below shows that using the variable $vSeq leads to a non-empty Language element and using the $vCopy variable leaves us with an empty Language element.
<?xml version="1.0" encoding="UTF-8"?> <Languages xmlns:xs="http://www.w3.org/2001/XMLSchema"> <Language>Latin</Language> <Language/> </Languages>
How is this behaviour in the Integration Advisor?
One of the main intentions of the Integration Advisor is to generate transformation scripts that write values from a structured source payload to a structured target payload. The structures always follow predefined interfaces schemes of business messages. The generated XSLTs of the Integration Advisor implicitly atomize the input values by an xsl:value-of, because these mapping functions are used to write the results to the mapped target leaf nodes. This eliminates the differences of other XSLT elements xsl:sequence and xsl:copy-of, because the focus of these elements is the writing or copying of sequences and complex structures.
As shown in the following illustration, no matter whether using xsl:sequence or xsl:copy-of, you finally get the same kind of atomized string value from several source nodes as you get it when using xsl:value-of. Therefore, it is usually not necessary to use another XSLT element than xsl:value-of.
But why is xsl:sequence the default XSLT element in the mapping element function?
It mainly has historic reasons, because xsl:sequence is more performant than xsl:copy-of, and it keeps the node-related types while processing the input into the output. This is also the motivation for XSLT 2.0 developers to primarily use xsd:sequence. Originally, our development started with the return of several nodes while processing complex structures, which should be used for the kind of triggering of the target instances. But this kind of triggering is changed yet. It is now possible to set conditional mappings with its specific triggering behavior. The blog ###BLOG### gives you more details about it.
How can I use xsl:copy
The element xsl:copy is usually used for copying the current input node to the output. The actual effect depends on whether the node is an element, an attribute, or a text node. Since Integration Advisor already consider the predefined nodes at the source and target side, it makes no sense to use a xsl:copy with a selection of just nodes. The following figure shows the consequences oft he different use of xsl:copy. The first example is a xsl:copy of the value using text(), which locates the value of the context node. The select of the xsl:copy in the second example ends just with the leaf-node itself. This returns nothing, because the structure of nodes is not considered by the Integration Advisor.
What is the recommendation yet?
You can either keep xsl:sequence or you can substitute it with the XSLT element xsl:value-of. Furthermore, it makes no sense to use xsl:copy-of since the trigger behavior is more optimized.
I recommend using XSLT elements xsl:sequence, xsl:value-of and other supported XSLT elements by following order:
- Keep xsl:sequence, if you just create a mapping element without any intention to further manipulate the output values by additional mapping expressions.
- Switch to xsl:value-of, if you want to further manipulate the output values using XPath 2.0 functions (see blog Integration Advisor – List of support XSLT elements and XPath functions).
- Switch to xsl:value-of, if you want to further separate the input values by a separation sign. This is simple using the attribute @separator of the xsl:value-of element. The figure 02 shows you how simple it is compared to doing the same separation by using xsl:sequence.
- Switch to another supported XSLT element, if you need further mapping expressions. The blog Integration Advisor – Conditions and statements in mapping element functions and Integration Advisor – Mapping element functions for looping and sorting provides you more details.
xsl:copy is in comparison to the other XSL elements not very useful, because it covers a limited scope which already supported by xsl:value-of and xsl:sequence.
The intention of this blog is to give you a clear guidance on how you can start writing a mapping function of a mapping element by using the XSLT elements xsl:value-of, xsl:sequence or another supported XSLT element. This definition of mapping expressions still needs some knowledge of the XSLT programming language. Our aim is to significantly increase the usability by mostly get rid of all programming efforts. But this is just iteratively possible during our evolving process of the Integration Advisor. We can’t do all the improvements at the same time; therefore, we need your help. Related to a more efficient expression of the mapping functions, we already have several improvement concepts in our backlog. Please let us know which of them should be implemented next. If you see any urgency to improve this area, you can create or vote (if already exists) for the following function-related improvements at Customer Influence campaign Integration Suite
Special thanks to Nico Kutscherauer (data2type), who gave me a very valuable input to this blog and to Annemarie Kiefer for the excellent review of this blog.
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