Transform Builder

Transform Builder

In this topic ...

How do I...
Specifying Inputs
Using Parent Node Mappings
Objects this Builder Creates

Use this Builder to copy or merge the contents of one schema-typed XML Variable into another Variable. The major advantage this Builder provides is that it can perform the copy/merge operation without requiring you to write any XSLT or IXml code.
The default behavior of this Builder is to leave the original content of the target variable in tact during a copy/merge action. This means that we can perform complex modifications of target variable content by applying a sequence of these Builders to the target variable, with each additional Builder instance adding its changes to existing content.
A typical use of this Builder is to take the result of calls to integration Builders (View and Form Builders) and merge these results into a common result format returned by a wrapper service.

How do I...

Set up XML node mapping between two schema-typed variables in a model?

Place a Transform Builder in a model that contains schema-typed variables. In the Builder, select the target and the source variable. Once the variables have been selected, select a target XPath and Source XPath to define the nodes the Builder will operate on.
Once the XPaths have been selected, use the Child and Parent Node mapping tables to specify the exact node mappings you want to make from the source variable to the target variable.
Add an action to an Action List that calls the <TransformName>CallCopy method and initiates the transform operation.

Specifying Inputs

This Builder takes the inputs described in the table below. For help on inputs common to many or all Builders such as those in the Properties group, see "Using the Builder Call Editor"

Input Name Description
Name Enter a name for this Builder call. The Designer displays this name in the Builder Call List.
The name you provide is used as the name of the Java class that is added to the WebApp and which supplies the "invoke" method that invoked to execute the copy/merge operation.
Source Variable Use the picker to select the variable that is to be operated upon.
All schema typed Variables known in the WebApp are displayed.
Source XPath Select the "deepest parent node" that is to be copied. The selected node is the node that is to match up with the node chosen for the target XPath above.
For example:
To copy the dateOfBirth and SSN nodes in the following:
<a><c><DateOfBirth/><SSN/></c></a> to <w><x><y><z><dob/></z></y></x></w>
Specify a/b/c as the target XPath and w/x/y/z as the source XPath.
Clear Target Value First Enable to the empty target variable content before start of the copy/merge operation.
Default behaviour is disabled (unchecked) This allows the copy/merge operation to merge data into the existing variable s content.
Target Variable Select the variable that is to be the target of the data being copied across.
All schema typed Variables known in the WebApp are displayed
Target XPath Select the "deepest parent node" that is to be targeted.
For simple schema types this will simply be the name of the top-level element ("Imports") that has all the child elements beneath it that will be updated by the content from the source variable.
In more complex schema types, the target XPath might be:
response/output/rows/row
The source XPath will map an element such as "AppMessage/ListOfStuff/Asset" to it.
In this case, the children of "Asset" will be mapped across to the children of "row", and additional matching of the parent nodes will take place also.
Child-Node Mappings
Copy Non-Matching Source Nodes Enable to copy non-matching source nodes.
Disable to ignore non-matching source nodes.
Example:
<a><c><DateOfBirth/><SSN/></c></a> to <w><x><y><z><dob/></z></y></x></w>
In the above code, you could choose that DataOfBirth be mapped to dob.
If this check box is checked, the SSN node will also be copied across to be a child of <x>.
Doing this will produce XML not compliant with the schema of the target variable, but it is allowed since it can be a useful feature and you might have other transforms yet to be performed.
Clear all Child Mappings Press this button to clear the columns of the Child/Leaf Node Mapping.
Selecting the source or target XPaths will repopulate source node/target node columns respectively.
Child / Leaf Node Mapping Once you select the target and source XPaths, the Builder will populate the Target Node and Source Node columns with the known children of those nodes. Use the pickers to selection nodes or change the position of entries in the table. Your selections will determine which source child elements map to which target child elements.
The pickers in the "target node" and "source node" columns are populated with the child element list to allow you to choose which source nodes map to which target nodes.

Target Node - Select a child element of the target node to map to
Source Node - Select a child element of the source node to map from
Custom Copy Action - Select an action. The custom copy action lists any WebApp methods that take two IXML arguments. When specified for a node, after the source node is copied across to the target that custom method will be invoked and the source node and target node will be passed as arguments. This allows you to do some custom modification of the target xml, such as converting text to lower case, concatenating a value from another XML node in the source/target tree, etc.
Merge Duplicates - Enable to merge source elements with existing target child elements. When copying across a source child element, if a matching target child element already exists, this setting determines if the source element is merged, or copied across as a new "duplicate" instance in the target element.

The source and target XPaths specify which parent source node is being mapped to which parent target node. This section is automatically populated with children from those 2 nodes and an attempt is made to match up the nodes based on their names.
Parent Node Mappings
Parent Node Mapping This section allows you to specify the mapping between the ancestor nodes in the parent lineage, and is especially useful (necessary) if the target and source have a different number of parent nodes. This mapping allows you to specify which mappings are kept or ignored. Click here for a mapping example.
The source and target XPaths specify which source node is being mapped to which target node. When the target and source XPaths are selected, the target/source columns are populated with the known ancestors of those nodes.
The table lists each ancestor node of the target and source nodes, allowing you to pick which node will maps to which. For each mapped pair, we can also specify additional matching parameters.

Target Node - Select a target parent node to map to.
Source Node - Select a source parent node to map from.
Match Empty Text - The "match empty text" column influences node matching as follows: Normally a node will be determined to "match" a node <x> (using our example from earlier) if the text of node <x> is the same as the text of node . Selecting the "match empty text" column for a row designates that a node <x> with no text will be considered to match a node with no text. Usually this behaviour is not needed, hence the default of not selected, but sometimes it is useful.
Remove Attributes - Enable the check box to suppresses the copying across of the attributes of a source parent node. When the parent node instances are being evaluated or copied across, default behavior is to copy across attributes from the source node to the target node, even if strictly speaking it is not conformant with the target schema. Removing attributes allows subsequent transforms to rename, remove or modify those attributes.
Match Nodes By - Specify how each parent source node should be compared to corresponding target parent node, to determine whether to merge the source node into the target node, or to create a new target node to copy the source node into. We can choose:

Parent Node Text - To compare text of source parent node to text of target parent node.
Child Node Text - To compare the text of the specified source parent node sub-element to the text of the specified target parent node sub-element.
Custom Method - To use a custom method, which takes two IXml elements, the source parent node and a target parent node, and return true if the nodes should be merged, and false otherwise.

Source to Match - Available enabled if" Match Nodes by Child Node Text" is specified. Select a sub-element of the Source Parent node. The text of the sub-element will be compared to the Target to Match sub-element text to determine whether or not to merge the specified source parent node into the target parent node.
Target to Match - Available if "Match Nodes by Child Node Text" is specified. Select a sub-element of the Target Parent node. The text of the sub-element will be compared to the Source to Match sub-element text to determine whether or not to merge the specified source parent node into the target parent node.
Custom Method - Available if "Match Nodes by Custom Method" is specified. Select a custom method which will be used to determine whether or not to merge a source parent node into a target parent node. Drop down will be populated will all methods in the WebApp that take two IXml argument and return boolean.

Using Parent Node Mappings

This input is useful when working with documents that are nested deeply, and particularly when the source and target have different levels of nesting. For example, suppose you have a source variable that looks like the following:
<PERSONALDATA>
 <BAPIP0002L >
 ....
 </BAPIP0002L >
 <BAPIP0002L>
 ....
 </BAPIP0002L >
</PERSONALDATA>
and the target looked like
<FUNCTION>
 <IMPORTS >
 ....
 </IMPORTS >
 <IMPORTS>
 ....
 </IMPORTS >
</PERSONALDATA>
Your parent mappings could specify that you wanted to map PERSONALDATA to FUNCTION and BAPIP0002L to IMPORTS. For each BAPIP0002L element, the Transform builder needs to decide if it should create a new IMPORTS element and add it as a new child of FUNCTION, or if it should merge it into an existing IMPORTS element.
That is where the "Match Nodes By" input comes into play. if you specify Parent Node Text, the Builder compares the text value of BAPIP0002L and all of the IMPORTS elements to look for a match. (We can specify whether or not to consider empty text as a match with the check box).
If you specify Child Node Text and specify some child elements of BAPIP0002L and IMPORTS, the Builder compares the values of the specified sub-elements to decide if it can match the BAPIP0002L element to any existing IMPORTS elements. In the case of a custom method, the Builder wants a method that takes two IXml objects and returns boolean. For each BAPIP0002L element, it will pass in that BAPIP0002L and each IMPORTS element until it gets a true result (which means the elements should be merged) or until it runs out of IMPORTS elements, which means there was no match, so a new element is created.

Objects this Builder Creates

Linked Java Objects

<builder_name> - A com.bowstreet.builders.webapp.TransformCopyDataHelper instance is added as a Linked Java Object with the name specified as the builder name. This class has an invoke method which is the method that should be called to invoke the copy/merge operation.

Variables

<buildername>_Transforms> - This hidden variable is added to the WebApp. The variable stores details of the transform that is to be applied at runtime. When the invoke method is called, this transforms variable is examined and the directives it contains are carried out using the current contents of the source and target variables.

Input Name	Description
Name	Enter a name for this Builder call. The Designer displays this name in the Builder Call List. The name you provide is used as the name of the Java class that is added to the WebApp and which supplies the "invoke" method that invoked to execute the copy/merge operation.
Source Variable	Use the picker to select the variable that is to be operated upon. All schema typed Variables known in the WebApp are displayed.
Source XPath	Select the "deepest parent node" that is to be copied. The selected node is the node that is to match up with the node chosen for the target XPath above. For example: To copy the dateOfBirth and SSN nodes in the following: <a><b><c><DateOfBirth/><SSN/></c></b></a> to <w><x><y><z><dob/></z></y></x></w> Specify a/b/c as the target XPath and w/x/y/z as the source XPath.
Clear Target Value First	Enable to the empty target variable content before start of the copy/merge operation. Default behaviour is disabled (unchecked) This allows the copy/merge operation to merge data into the existing variable s content.
Target Variable	Select the variable that is to be the target of the data being copied across. All schema typed Variables known in the WebApp are displayed
Target XPath	Select the "deepest parent node" that is to be targeted. For simple schema types this will simply be the name of the top-level element ("Imports") that has all the child elements beneath it that will be updated by the content from the source variable. In more complex schema types, the target XPath might be: response/output/rows/row The source XPath will map an element such as "AppMessage/ListOfStuff/Asset" to it. In this case, the children of "Asset" will be mapped across to the children of "row", and additional matching of the parent nodes will take place also.
Child-Node Mappings
Copy Non-Matching Source Nodes	Enable to copy non-matching source nodes. Disable to ignore non-matching source nodes. Example: <a><b><c><DateOfBirth/><SSN/></c></b></a> to <w><x><y><z><dob/></z></y></x></w> In the above code, you could choose that DataOfBirth be mapped to dob. If this check box is checked, the SSN node will also be copied across to be a child of <x>. Doing this will produce XML not compliant with the schema of the target variable, but it is allowed since it can be a useful feature and you might have other transforms yet to be performed.
Clear all Child Mappings	Press this button to clear the columns of the Child/Leaf Node Mapping. Selecting the source or target XPaths will repopulate source node/target node columns respectively.
Child / Leaf Node Mapping	Once you select the target and source XPaths, the Builder will populate the Target Node and Source Node columns with the known children of those nodes. Use the pickers to selection nodes or change the position of entries in the table. Your selections will determine which source child elements map to which target child elements. The pickers in the "target node" and "source node" columns are populated with the child element list to allow you to choose which source nodes map to which target nodes. Target Node - Select a child element of the target node to map to Source Node - Select a child element of the source node to map from Custom Copy Action - Select an action. The custom copy action lists any WebApp methods that take two IXML arguments. When specified for a node, after the source node is copied across to the target that custom method will be invoked and the source node and target node will be passed as arguments. This allows you to do some custom modification of the target xml, such as converting text to lower case, concatenating a value from another XML node in the source/target tree, etc. Merge Duplicates - Enable to merge source elements with existing target child elements. When copying across a source child element, if a matching target child element already exists, this setting determines if the source element is merged, or copied across as a new "duplicate" instance in the target element. The source and target XPaths specify which parent source node is being mapped to which parent target node. This section is automatically populated with children from those 2 nodes and an attempt is made to match up the nodes based on their names.
Parent Node Mappings
Parent Node Mapping	This section allows you to specify the mapping between the ancestor nodes in the parent lineage, and is especially useful (necessary) if the target and source have a different number of parent nodes. This mapping allows you to specify which mappings are kept or ignored. Click here for a mapping example. The source and target XPaths specify which source node is being mapped to which target node. When the target and source XPaths are selected, the target/source columns are populated with the known ancestors of those nodes. The table lists each ancestor node of the target and source nodes, allowing you to pick which node will maps to which. For each mapped pair, we can also specify additional matching parameters. Target Node - Select a target parent node to map to. Source Node - Select a source parent node to map from. Match Empty Text - The "match empty text" column influences node matching as follows: Normally a node <b> will be determined to "match" a node <x> (using our example from earlier) if the text of node <x> is the same as the text of node <b>. Selecting the "match empty text" column for a row designates that a node <x> with no text will be considered to match a node <b> with no text. Usually this behaviour is not needed, hence the default of not selected, but sometimes it is useful. Remove Attributes - Enable the check box to suppresses the copying across of the attributes of a source parent node. When the parent node instances are being evaluated or copied across, default behavior is to copy across attributes from the source node to the target node, even if strictly speaking it is not conformant with the target schema. Removing attributes allows subsequent transforms to rename, remove or modify those attributes. Match Nodes By - Specify how each parent source node should be compared to corresponding target parent node, to determine whether to merge the source node into the target node, or to create a new target node to copy the source node into. We can choose: Parent Node Text - To compare text of source parent node to text of target parent node. Child Node Text - To compare the text of the specified source parent node sub-element to the text of the specified target parent node sub-element. Custom Method - To use a custom method, which takes two IXml elements, the source parent node and a target parent node, and return true if the nodes should be merged, and false otherwise. Source to Match - Available enabled if" Match Nodes by Child Node Text" is specified. Select a sub-element of the Source Parent node. The text of the sub-element will be compared to the Target to Match sub-element text to determine whether or not to merge the specified source parent node into the target parent node. Target to Match - Available if "Match Nodes by Child Node Text" is specified. Select a sub-element of the Target Parent node. The text of the sub-element will be compared to the Source to Match sub-element text to determine whether or not to merge the specified source parent node into the target parent node. Custom Method - Available if "Match Nodes by Custom Method" is specified. Select a custom method which will be used to determine whether or not to merge a source parent node into a target parent node. Drop down will be populated will all methods in the WebApp that take two IXml argument and return boolean.