Building a Mapping Flow in the Graphical Mapping Editor

The Data Mapping Editor window contains an Element Mapping control drop-down. Each time you map an input structure to an output structure, the mapping between those elements will be added to this list. When you want to work on mapping child elements within a structure, you must first select the current element mapping that connects the parent elements.

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 multiple 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 this 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' → 'contacts'" shows a different set of mappable elements:

Highlighted are the employee and manager nodes on input, and the contact node on output. Any lower-level descendants of these nodes, such as position (child of manager) are greyed out and unavailable.

Mapping individual fields requires that you write an expression defining the value of the output field in terms of the available input fields, so it is important to understand which fields are available.

You can toggle the display of input and output elements not eligible for mapping use 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.

To edit an element mapping, select the mapping the Element Mapping drop-down, 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. For example, the assigned script for the output field FirstName is the expression input.FirstName; (see image below)

Writing assigned script expressions directly is a must if you are doing more than basic copying and concatenation of data fields. You can still drag the input fields to the output to get the code that references the input, and then write the rest of the expression in terms of familiar operators and an extensive set of build-in functions in the selected expression language.

In the Graphical view, you can select a field and type expressions directly into the assigned script box at the bottom of the Outpane pane.

In the Script view, you can edit the script for the entire element mapping in one place.

The editor provides several types of support:

Create a rule by either:

The New Rule dialog appears.

extracts the phone number attribute from the first/contacts/user node which has a phone number consisting of a series of digitals and spaces.

Note that XPath syntax is used in rules regardless of what type of structured data is used. For other structured data types, the XPath expression will be interpreted in a fashion analogous to that used with XML.

Right-click a Rule from the DataMapper inputs, and choose "Edit". The editing dialog appears:

You can update the definition of the rule here. Note, however, that you cannot change the target output field for the rule.

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

An input argument can be of type string, data, boolean, or any of the numeric types.

If you use the default MEL for scripting, an argument can be a Java object, in which case you are prompted for the class of the object

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: