Working With the Mapping Builder

Right-click an input node in the workspace to display the menu options that are available for the nodes in the Input pane. You can expand or collapse various nodes within the structure tree, copy a node, and show or hide mappings between input and output nodes.

The following image shows the options available on the Input Node menu.

The following table describes the Input Node menu options.

Right-click an output node in the workspace to display the menu options that are available for the nodes in the Output pane. The following image shows the options available on the Output Node menu.

The options that are available on the Output Node menu depend on which node is currently selected in the Output pane.

You can disable certain options, depending on the type and position of the output node in the structure (for example, group, element, or attribute) or the data format (for example, XML or EDI X12).

The Add and Change Type option lists are dynamic. They also depend on the type of the output node and the output data format.

The following table describes the options available on the Output Node menu.

The input structure contains the input, which represents the groups, elements, and attributes encoded in the input document. Each node in this tree has exactly one parent, and can have more than one child.

The following table describes the various components provided in iWay Transformer to represent input nodes. Definitions of basic terms commonly used for nodes within an input document tree are also provided.

Input Document The incoming document or message to which transformations apply. The following formats are supported: CSV. For more information, see CSV Input Properties. EDI HIPAA. For more information, see EDI Input Properties. EDI X12. For more information, see EDI Input Properties. EDIFACT. For more information, see EDI Input Properties. Fixed Width. For more information, see Fixed Width Input Properties. IDOC. For more information, see IDOC Input Properties. SWIFT. For more information, see SWIFT Input Properties. XML. For more information, see XML and iWay XML Response Input Properties. iWay XML Response. For more information, see XML and iWay XML Response Input Properties. CDF. For more information, see CDF Input Properties. Note: CDF format is deprecated. iWay Software recommends that you use Fixed Width format instead. The input document is displayed on the input pane as a visual representation of the input document tree. It maintains a logical order of component nodes, such as groups or elements, in relation to the underlying document, wrapping the nodes that are contained within other nodes. For more information, see the Input Document Tree Example that follows. Each input node contains a name that identifies the type of the node, optionally a number of attributes, or content.

Group Block of data that has a group element as its root. It can contain other groups or elements nested within, as children. Multiple groups can also exist on the same level. A group was formerly called a parent. iWay Transformer does not support mixed content group nodes containing data values. However, the group node for XML and HTML data formats can have any number of attribute nodes inside, if applicable.

Element Usually belongs to the group as a leaf, which cannot have any other nested groups or elements. It typically stores a data value. In XML and HTML data formats, it can contain attribute nodes or CDATA.

Attribute Value associated with a group or element, consisting of a name, and an associated textual value. Attributes are used for XML and HTML data formats only. Each group or element can have zero to many attributes.

Example of Input Document Tree Sample document tree of groups, elements, and attributes encoded in the input message. Each node in this tree has exactly one parent, and may have more than one child. The following is a section of an XML input document: The following is a tree structure representation of the preceding XML: In iWay Transformer, the resulting input document tree is as follows: You can collapse or expand the document tree from the given node to its deepest descendant. iWay Transformer supports a set of different relationships that link nodes together.

The common types of document tree relationships are described in the following table.

The output structure contains the output document tree, which represents the completed structure of groups, elements, and other supported node types, such as attributes or CDATA, encoded in the output document.

Each node in this tree has exactly one parent group. It can have one or more sibling nodes, unless it is the root node in the tree, which has to be unique according to the mapping rules in iWay Transformer. You can adjust the properties of the given node, such as visibility or namespace, to affect its appearance in the actual output document.

This topic examines the output document tree in the XML to HTML table example, which is included as a sample Transform component.

The output structure is represented as follows:

In iWay Transformer, the output document tree is visualized as follows in the Output pane of the Mappings tab:

One of the efficient methods for adding new output nodes is structure mapping. For more information about structure mapping, see Group. Another method of adding new output nodes is by building your document output tree from scratch, which is achieved by right-clicking an existing output node and selecting Add followed by the type of node you wish to add.

The supported types of the output nodes you may insert will depend on the type of the parent node to which you want to add your data nodes and can be driven by the context menu. For example, if you right-click an XML element node in your output structure, you may discover that the only possible type of nodes which can be added to that element node is an attribute node. By following these restrictions, the integrity of the output structure is maintained.

You can review the available options for the output node type by right-clicking the parent node and selecting the Add submenu.

A group is a block of data that has a group node as its root. It can contain other group or element nodes nested within, and other node types if supported (for example, attribute or CDATA for XML data format). Multiple groups can also exist on the same level. The nodes contained within a certain group are also called children of this particular group, sometimes referred to as a parent group in relation to the nodes nested within it.

Every output structure, regardless of the output data format, has at least one group node at its root. A group marks the start of an output block by specifying the start of an output loop. The first node in your output structure, referred to as a Root, is created automatically by iIT Transformer when you create your initial output structure. You can then build your structure from the root group node by adding the nodes of supported type one by one, or by copying the blocks of data from existing input or output structures. The output is produced by looping through the entire output structure (starting from the root group), one or more times (iterations), depending on your settings, while reading the mapped values from the input file.

Consider the CDF output structure displayed in the following image.

The first output node, CDF_FILE, is the first group node and is also called the Root. The presence of the Root node ensures that iIT Transformer loops over the entire output structure if needed. The next node in the output tree is a HEADER node, which is also a group type of node. Appearance of the HEADER node marks an output block of data, which includes the child element nodes Name and Title. The node, 20, is also a group node, which contains an output block of data to include the next ten child element nodes (RecordType to ts_time). Group nodes are distinguished by the Group icon, which has a blue diamond shape with a double border. Element nodes are distinguished by the Element icon, which has a blue diamond shape.

The following list contains the visual variations of the group node when a specific property is configured for it.

• Invisible

  A group node that has its visible property set to false. This means that even though the group node is present in the output structure during design time, the invisible node’s value or the whole block of its children nodes will not be displayed in the run-time output produced by the project. For more information on hiding a group, see Filter Tab.

• Context

  A group that has a context applied. The context property is the explicitly defined reference of the output group node to the particular input group node. It helps to control looping, and to resolve challenges and opportunities in the area of data structure searching. It is especially useful for nested multi-level repeated structures. It operates on the logical structure of the message (similar to XPath). It is available for use by any data format supported by iIT Transformer.

  To set the context property, right-click the group node b in the Output pane and select Properties. The Properties tab opens and displays the General tab by default.

  In the Context field, specify the path value for the looping node on the input side. Click the ellipses button, which opens the Input Fields pane. Select an input node to be mapped from the hierarchy tree and click OK.

  For more information on setting a context for a group, see General Tab.

• Filter

  A group that has a filter applied. The filter property is useful when your incoming document data may contain loop iterations that should not appear in your output, according to your requirements. The filter property is designed to help you remove unnecessary blocks of data. For more information on specifying a filter for a group, see Filter Tab.

Depending on the group properties (loop, context, and filter) that are specified in the Properties tab for the selected output node, the group icon changes in the Output pane to reflect these settings. The following table lists all of these variations for your reference.

Group Setting	Visible Icon	Invisible Icon
Loop is set to true
Loop is set to false
Loop is set to aggregate
Context is applied and loop is true
Context is applied and loop is false
Context is applied and loop is aggregate
Filter is applied and loop is true
Filter is applied and loop is false
Filter is applied and loop is aggregate
Context and filter are applied and loop is true
Context and filter are applied and loop is false
Context and filter are applied and loop is aggregate

Additional XML Output Structures

In iIT Transformer, it is easy to create complex output structures for your output file. The way you arrange the nested components in the Output pane of the Mapping window is exactly how your output will be structured.

You can use parent nodes to create complex output structures with nested parent nodes and output loops for the XML output formats (XML and e-business). EDI (X12, HIPAA, EDIFACT, and SWIFT) output is treated as XML output due to the use of the e-business metadata by the Transformation Engine.

In addition to indicating the possible start of an output loop, a group node can also play an important role in building the following structures depending on the output data format:

• XML output document - The first parent node value is defined as the root node of your XML output document. Other group nodes are defined as XML parent node names; they can be used to create nested loops for complex XML structures.
• EDI (X12, HIPAA, EDIFACT, and SWIFT) output document - The group node for complex EDI messages can be used to create nested loops.

An element node is used to represent a basic data item in iIT Transformer. Element nodes are typically found inside the group node. Sometimes it is referred to as a leaf of the output tree because it cannot have any other child nodes, such as the nested groups or elements within it, except for the attribute nodes (for XML data format only).

An attribute node contains a value associated with a specific group or element. It consists of a name, and an associated (textual) value. Attribute nodes are supported for XML format data only.

In the following example, name and type are attributes for the Company element:

<Company name="Video and Sound Card Express" type="Computer Parts">

Input node represents a value from an input structure. Mapping to an Input node can be done using Input pane. This pane is typically located in the lower-left corner of the Mapping Builder. It allows you to select the location of the input node on which to base the value of the current output node.

You can drag and drop the input node into the working area of the Mapping Builder. Depending on where in your workspace you drop the node, you can overwrite or update the existing mapping tree.

The Mapping Builder uses the following notation as the context property to define the location of the input node in the mapping formula:

Sales/Company/Year/Quarter/Product/Item@sold

This is the same notation that is used in the Mapping Values pane, as shown in the following image.

Function value can be from predefined or custom algorithm of calculation. Mapping to a Function can be done using Function pane. This pane is typically located in the upper-left corner of the Mapping Builder. It allows you to select predefined functions or custom functions that you defined to associate with an output node.

You can drag and drop the function into the working area of the Mapping Builder.

Note: In this version of iIT Transformer, you have an option to insert functions below the current function in the existing mapping tree or replace the current function.

Allows you to type in a fixed value for a function or input node, by right-clicking the node and selecting Set Constant or double-clicking the node.

Make sure the Set Constant option is selected.

The Constant Builder dialog box opens, as shown in the following image.

Type your value in the Constant field and click OK.

An expression is a logical statement where two or more input node values are combined into one output value using the basic operators and functions. In Mapping Builder, expressions are typically used for concatenation where input fields are joined by a plus sign "+" operator.

To set an expression, right-click the node and select Set Expression or double-click the node.

Make sure the Set Expression option is selected.

The Expression Builder dialog box opens, as shown in the following image.

Type your value in the Expression field and click OK.

You can also use the buttons that are available to build your expression graphically.

An expression can contain a concatenation of any number of input nodes and constant values in any order, in the following format:

<input item>+'constant'+...

For example:

'For '+tree/fruit+tree/fruit/year+': '+tree/fruit/
apple/yield+
' bushels, '+tree/fruit/apple/avgweight+' grams avg.'

Note: It is strongly encouraged to use the @CONCAT function instead of an expression to concatenate strings. For more information on using the @CONCAT function and its properties, see Working With Functions.

For more information on how to use the Mapping Builder, see Using the Mapping Builder.