Mapping Structured Data with Enhanced Node Functions

We’ve reported previously on support for node functions that simplify mapping structured data by eliminating need to copy-paste a function multiple times into a mapping. Repeating the same function unnecessarily clutters the mapping layout and makes the data mapping more difficult to understand or revise.

MapForce also includes additional filters are available for defining node functions. These parameters allow developers to apply functions and default values to specific nodes based on custom-defined criteria. For example, you can apply a node function based on node metadata such as the node name, node length, precision of the node’s data type, customized node annotations, and more.

Let’s look at a mapping with enhanced node functions.

The data mapping shown below is the PriceCalculation.mfd node function example installed with MapForc. This example calculates the final sale price for a list of items based on their original cost and a markup factor. The source data is a text file in CSV format and the output is an XML file.

In this mapping, a node function is defined and applied to the Articles element in the output file and its child elements. Double-clicking the bold function icon to the left of the Articles element opens the node function definition.

The Apply to drop down menu at the top left indicates the function is intended to apply to all child elements of Article. The Function description section tells us this function uses node metadata element node_fractionDigits as a parameter for the round-precision function. If node_fractionDigits is not defined for any child element, zero will be substituted instead.

We can dig deeper for another view of the node function by clicking the Edit button shown at the top center in the image above. This opens the function in its own data mapping window, in a view similar to a user-defined function:

The mapping item node_fractionDigits at the lower left provides an input value to the function, based on the structure of the target data. Let’s look a little deeper at the node metadata to locate node_fractionDigits.

Definition of Node Metadata

The node metadata available for any structured data file comes from the data structure definition itself. In our example, the mapping target component is an XML document. Therefore, the metadata available for any node is defined in the XML Schema.

The image below shows the PriceCalculation XML Schema in XMLSpy graphical schema view:

The SalePrice XML element highlighted in the diagram is defined as an instance of the Amount type, which is itself a decimal number with a maximum of 2 fractional digits, as seen in the Facets window in the lower right. Therefore, the node_fractionDigits metadata for the SalePrice node is 2.

The node function parameters available for any structured data file will always depend on the data type – XML, relational database, CSV file, etc. and the level of detail included in the schema definition.

Mapping Structured Data with Node Function Parameters

When you create a new node function, you will first be presented with a raw value and a result value that are not connected. Click the blue Add Node Specifics button to insert a node function parameter. This opens the Node Specifics dialog where you select a node parameter:

Note the option for instances where a particular node does not support the selected metadata type. In the price calculation mapping, this behavior is handled directly in the node function definition. The node function is only applied to numeric datatypes, and for any node where fractionDigits is not specified, the substitute-missing function supplies zero instead.

Watching the Node Function Execute

We can set a breakpoint from the right-click context menu on any node of the output component and use the built-in MapForce debugger to watch the function execute.

In the partial view below, the breakpoint is set on SalePrice. We executed the mapping from the Debug menu and execution paused at the breakpoint with intermediate values added to the main mapping window.

We can see the last value for SalePrice calculated by the mapping was 49.183323875. The node function rounded the final value to 49.18.

The actual node function execution isn’t displayed in the debugging result in the main mapping window, but clicking in the Messages window opens the node function with all intermediate values:

The examples installed with MapForce include several other node function data mappings. The MapForce integrated help system even includes a step-by-step tutorial to build a node function mapping from scratch.

You can even modify the example mapping described here to see for yourself how the output changes. For instance, you could edit the XML Schema to allow three fractionalDigits, or change the mapping to allow the node function to execute on the Number node, the first child of Article, and examine the new result.

To see node functions in action, check out this MapForce demo video.