Building a Mapping Flow in the Graphical Mapping Editor

When preparing to map elements from input to output, whether a specific element is mappable depends upon the currently selected element mapping in the editor view. For multiply nested structures, you may have to map parent elements from input to output before you can map their descendants.

Once you select a current element mapping, those elements that are available to be mapped in source and target are presented in bold. For example, consider a DataMapper for constructing a contact phone list from lists of employees and managers.

The employee and manager collections of elements are bold to indicate that they can be mapped to the output pane. Selecting the element mapping "Foreach 'manager' → 'contact'" shows a different set of mappable elements.

In the input and output panes, the nodes and attributes available for mapping are highlighted in bold:

In some cases, mapping individual fields may require writing an expression that defines the value of the output fields with the available input fields. In this cases, you need to understand which fields are available at the current mapping level.

You can toggle the display of input and output elements not eligible for mapping using the Eye (Hide/Show unrelated elements) button in the input or output pane.

You can create an element mapping one of two ways:

The new element mapping appears in the Current Element Mapping control.

The Element Mapping Control expresses the idea that element mappings iterate over the inputs by inserting "Foreach" into the generated name of each element mapping. This label is meant as a reminder, but you can edit the name to remove this.

To edit an element mapping, select the mapping in the Element Mapping dropdown, then click the Edit Mapping icon. The Edit Mapping dialog appears:

Enter the desired values for Name and, for structured data, an XPath filter Condition here.

For structured data, you can define an XPath expression that evaluates to a Boolean to select only inputs where the expression is true. (This capability provides something like a WHERE clause in a SQL expression.)

XPath syntax is available for all types of structured data (including POJO, JSON, and key-value maps). In general, supported XPath includes any XPath condition that can be used in a selector. For example:

Filtering can be used to provide some basic data validation, or to define separate element mappings on the same input data to process individual records differently depending on which filters they match.

In either case, DataMapper creates an expression, called an assigned script, for the output field.

To view an output field’s assigned script, click the field name in the DataMapper’s Output pane. The expression is displayed in the textbox under the Output pane.

In the example above, the value of output field name is a string composed of the following:

The resulting value is the string Larson, Larry (mgr), which you can see next to the name field.

Writing assigned script expressions directly allows you to manually map fields or to modify an existing mapping. If you are doing more than basic copying and concatenation of data fields, you will probably need to write or modify the assigned script for an output field.

One practical technique is to drag the input fields to the output to get the code that references the input, and then write the rest of the expression using familiar operators and an extensive set of built-in functions in the selected expression language. For example, after dragging an input field to the output, you can edit the assigned script box at the bottom of the output pane, as shown in the example above.

You can also select the Script view to edit the script for the entire mapping:

Like the graphical view, the script view allows you to use the Element Mapping drop-down to view the desired mapping level.

The editor provides several types of support:

Effects of Editing in Script View

Rules in DataMapper allow you to apply XPath selectors to structured input data and make the results accessible for use in transformation outputs.

The most common use case for rules is extracting data from a tree structure, such as a particularly complex XML or JSON document, to a flat structure like a CSV. Most use cases for mapping structured input data to structured targets are more easily handled by mapping nested structures with element mappings. However, a rule can be used to sidestep the need to map multiple mapping levels to extract only a few nodes from a structure.

To define an input or output argument for a mapping, use the following steps:

In the Mule expression field, type the Mule Expression Language expression that will provide the value for the input argument. You can use any Mule expression that is logically valid within the context of the flow and that matches with the selected type. For Class, if applicable, browse to or type the name of the object class.

Click OK when finished.

The input argument is then available as an input for mapping and transformation, as shown in the following screenshot: