Clarifications on Data Mapping

Table of Contents

• Does mapping change the schema?
• Why is the XSLT statement created with formula builder different from the one created by editing (i.e. via drag and drop, or copy/paste) the node?
• Known Issues
• Document References

The Input tab of the activity allows you to supply the data that an activity expects as input. The interface is a GUI editor of Extensible Stylesheet Language Transformation (XSLT), also called Data Mapper. TIBCO ActiveMatrix BusinessWorks? implements the transformation logic into XSLT code and executes it at runtime using the result as the activity input.

ActiveMatrix BusinessWorks documentation gives a good explanation of the mapper interface. For detailed information, please refer to ActiveMatrix BusinessWorks Process Design Guide, Chapter 8 -- Mapping and Transforming Data: Overview of Mapping and Transformation. In this article, we will address common confusion regarding the data mapper.

Does mapping change the schema?

More specifically, does mapping make an optional element required??

The answer is no. ActiveMatrix BusinessWorks mapper generates XSLT code based on the user's input, which does not affect the schema definitions. First, we highlight a couple of points explained in the referenced documentation:

1. Before a mapping or formula is specified, the activity's input elements are displayed as "hints". These hints show the data the activity expects as input, which is essentially a GUI representation of the schema definition.
2. After a mapping or formula is specified, a hint becomes an XSLT statement. In another words, the representation of the schema definition of the activity input is replaced by the representation of some XSLT statements.

In the following example, the root element of the activity input has two child elements, "parent1" and "parent2", each has one optional child element, "node1". One upstream activity (Mapper1) has output with a "root" element and one optional child element, "node1", which becomes available for the current mapping as input data. Note that "node1" in all three occurrences is displayed with a question mark (?) before the element name, which gives a hint that the element is optional in all three model groups according to the schemas. On the other hand, the elements "test", "parent1", "parent2" and "root" are all required, hence neither is displayed with a question mark.

Step 1: the user drags and drops "node1" from the "Process Data" pane to "node1" under "parent1" to create the mapping below.

If you right click the "test" node and then copy/paste to a text editor, you will see the following XSLT statements:

Note that the question mark before "node1" now corresponds to the "if" statement around "node1" (and the XPath expression of the "if test" must equal to the value of the node) whereas "parent1" without a question mark now means there is no "if" statement around "parent1". Therefore, there is no sense of preserving element cardinality after mapping because the question mark simply means different things before and after the mapping.

Moreover, whether or not the mapper surrounds an element in XSLT with an "if" statement logic is not dictated by any standard. Rather, ActiveMatrix BusinessWorks chooses to do so to better accommodate the common use cases. When a user maps one optional element to another optional element, ActiveMatrix BusinessWorks expects most users to desire a logic whereby the mapper creates the mapping output only if the mapping input element exists. Therefore ActiveMatrix BusinessWorks creates an "if" statement logic automatically to facilitate the mapping task.

Step 2: the user drags and drops the "root" element from the Process Data pane to "parent2". This will prompt the user with the Mapping Wizard. The user then would choose the selection "For each '$Mapper1/root' create a 'parent2'" followed by the Next and then the Finish buttons to create the mapping below.

This will create the following mapping:

Note that the mapper does not display a question mark at "node1" under "parent2".

Now we take a look at the XSLT statements:

We now understand the following:

1. The question mark before "node1" under "parent1" represents the "if" statement around the node in XSLT. The absence of a question mark before "node1" under "parent2" indicates that there is no "if" statement around the node in XSLT; it does not mean the node is no longer optional.
2. Whether the mapper creates an "if" statement in one scenario but not the other simply means that we see prevailing use cases in need of an "if" statement in one scenario, but not the other.

In ActiveMatrix BusinessWorks versions later than 5.3.3 with HF7 or 5.4.0 with HF3, when you add the following property to designer.tra and follow Step 2 above again, "node1" under "parent2" will be surrounded with an "if" statement.

java.property.automatic_mapper_if_surround=true

This gives the user the option to create an "if" statement automatically in our second scenario, thereby keeping the question mark icon at "node1" unchanged. However, there are other scenarios whereby after mapping, the question mark icon associated with the node in the Activity Input pane does get changed, for example, when you map an optional element to an optional nillable element. Please remember that such a change means a representation of the created XSLT statement is different from the representation of the schema, rather than any change in the schema. ActiveMatrix BusinessWorks creates such XSLT statements based on the common use cases.

Why is the XSLT statement created with formula builder different from the one created by editing (i.e. via drag and drop, or copy/paste) the node?

Let's start with the mapping created in Step 1. Once Step 1 mapping is completed, proceed with either drag and drop "node1" under "root" from the Process Data pane to "node1" under "parent2" in the Activity Input pane, or right-click on "node1" under "parent1" in the Input Activity then copy/paste to "node1" under "parent2" in the same pane.

The end result of the mapping above should yield the following XSLT statements:

Alternatively, you can try either one of the following:

1. Select the value field of "node1" under "parent1", then copy and paste "$Mapper1/root/pfx:node1" into the value field of "node1" under "parent2".
2. Select the value field of "node1" under "parent2", open the "formula builder", and then drag and drop "node1" from the left pane to XPath formula pane.

Either of the above should result in the following XSLT statements:

Note that in the first case "node1" under "parent2" is surrounded with an "if" statement whereas in the second case the "if" statement is not being created and that is because when you work on the value field of an element, ActiveMatrix BusinessWorks assumes you are creating the XPath expression in the "xsl:value-of" statement alone. Therefore, ActiveMatrix BusinessWorks does not create XSLT statements beyond those that satisfy the schema definitions.

We should mention that in rare cases where the user wants to create an optional element regardless of whether "node1" appears in the Process Data pane, the user can do so simply by editing the value field of the optional element.

Known Issues

An enhancement request has been created for ActiveMatrix BusinessWorks to surround optional-to-optional mapping with "xsl:if" when mapping an ancestor element of the optional input element to an ancestor element of the optional output element. The feature has been implemented in ActiveMatrix BusinessWorks 5.3.3 HF7 and ActiveMatrix BusinessWorks 5.4.0 HF3. In order to turn on the feature, the user must set the following property in designer.tra:

java.property.automatic_mapper_if_surround=true

Document References

• Please refer to ActiveMatrix BusinessWorks Process Design Guide, Chapter 8 -- Mapping and Transforming Data: Overview of Mapping and Transformation.

Information to be sent to TIBCO Support

If you see unexpected Mapper behavior, either creating undesired XSLT statements or unexpected GUI representations, please open a Support Request (SR) with TIBCO Support and provide the following:

• Create a simplified ActiveMatrix BusinessWorks project that demonstrates the problem. In most cases you can reproduce such an issue by creating a simple process with one or two "Mapper" activities, the first one can define the Process Data to be used by the second one.
• Provide detailed steps to reproduce the problem. Screenshots can be particularly helpful in demonstrating the unexpected behavior.