Oakland Data Transformer - Map Editor

A map is the set of rules of transformation from one structure to another. Note that for simplicity maps work only with one input structure and one output structure. Since structures can be easily composed, and since IO operations can occur at multiple levels in a structure, this allows complete flexibility for multiple document support.

The map elements are based on the underlying structure elements, but they are separate objects. This allows for easy migration and detection of changes in the underlying structure elements. To migrate a map from one version of EDI to another for example is simply a matter of changing which structure it refers to. The map editor will then indicate the portions of the map that need attention based on the change.

The upper portion of the map editor consists of an input and output panel showing the map elements. These elements correspond to the structures associated with the map. In the middle, the current representation (XML) for each structure is shown.

The lower portion of the map editor contains expression trees for the selected map element. Different expression trees are available depending on the type of the map element.

Most mapping is done by simply dragging an input element to an output element (which automatically creates a simple Copy expression, and automatically calculates the necessary looping). Alternatively, you can create an expression explicitly by dragging functions and map elements to the expression tree panel.


The map editor provides extensive support for navigation between map elements and the expressions where they appear. So it is easy to find from an input map element which output elements are mapped, or from an output element to which inputs are referred.

You can quickly see the structure element that is associated with the map element by double-clicking on the map element.

You can also go to the structure element in the structure editor with a right-click.

Functions and Map Expressions

An extensive function library is provided for mapping. Each function is just that in the mathematical sense, it takes multiple arguments and returns a single result. In addition to the basic functions of copying and manipulating data, there are various special purpose functions to make it easier to deal with certain types of commonly used constructs. An example of this is the CopyFirstPresentValue function which is used in cases where a value from an inner loop is preferred over one in an outer loop.

Both Java methods and XPath functions can be directly invoked.

Type conversion between different datatypes is automatically provided where necessary, and type checking is performed at runtime.

There is also a user defined function capability.

Here is an example of a more sophisticated expression that defines a value for an output element. In this mapping, each of the components of the name in the input is in repeating elements. This value expression concatenates all of these elements by looping through them.

This illustrates that expressions always execute on a single element in some (looping) context, which is defined by a loop expression. In cases (like the one shown) where additional looping is desired to form an element's value, the aggregate functions (Agxxx) are used).


Looping for a map element is explicitly defined using a loop expression. For most simple cases, the loop expression is automatically provided based on the value mapping, because the normal case is to have an occurrence in an output loop for each occurrence in the corresponding input loop.

For more complex cases, there are a number of functions to control the production of output elements. This includes filtering and sorting.

For XML, there is full support for mapping recursive elements, both staticly (creating an instance of the recursive element at design time), and dynamically (creating instances of recursive elements based on corresponding input recursive elements at runtime).

There are also special-purpose looping functions to facilitate things like the X12 EDI HL loop.

Incremental Map Execution/Data Viewing

You can incrementally view either the input data or output data associated with a map at any element level.

This shows the output of the execution of a map in EDI format; note that you can dynamically select to view the output with another representation (XML in this case).

Map/Structure Migration

Migrating from one version of a standard to another is highly automated, thanks to structure inheritance. Here we show the process of migrating from an EDI X12 4010 856 to version 4030.

In this case, a custom structure has been defined which inherits from the standard 4010 856 structure. The migration is simply changing the custom structure to inherit from the version 4030 structure.

Here we show the results that happen when a map using the custom structure is opened. These indicate that the underlying structure changed so you can correct the problems.

This is what the map looks like when it is missing structure elements that correspond to the map elements. Note that all of the mapping data is preserved so that it may be moved to the right place if necessary. Should the elements reappear in the structure, they will automatically become valid in the map.

This validation of structures against maps happens automatically whenever a map is opened, or even if a structure changes and it is in another open window.

Map Inheritance

With today's complex XML documents and the amount of reuse that both XSD and EDI provide, there are often cases where the same mapping from one subset of an input document to a subset of an output document is necessary. One common case for this is an address. The address is represented in a single way in EDI and also in most XML standards. It is possible to create a map which maps this address from EDI to the desired XML format and then to inherit from this map anytime an address mapping is required. This greatly reduces the maintenance burden if something in the address mapping changes.

Sample/Test Documents

There is extensive support for maintaining and creating sample documents for use in map development. These documents are associated with the structure. You can use any number of example documents and quickly switch between them.

Sample documents can be provided for both sides of the map, so you can see what the output is expected to be. You can also execute the map to generate a new sample document which can be saved for use with other maps associated with that structure.

All of this works with multi-document support that uses I/O expressions.

Map Automated Testing

You can specify any number of test scenarios at any level of a map for automatic regression testing. These are easily automatically created when you are manually testing a map during development (simple hit the "Create Test Case" button as shown above).