eiConsole v.24R1
Tutorial & Interface

eiConsole – Data Mapping & Transformation

Using Tabular Mappings

Note: The Quick Start, Foundation, and Topology tutorials should be completed before proceeding with the Data Mapping & Transformation Tutorials.

Overview

This interface and related tutorials demonstrate the use of the Data Mapper in Route configurations to transform between XML Formats. In this particular exercise, an existing Route (from “Data Mapping – Using Functions”) is modified to transform a “PeopleA” XML format to the “PeopleE” XML format, which makes use of the Tabular Mapping tool to convert between Gender code sets. In the tutorial, we’ll cover using the “Tabular Mappings” feature of the Data Mapper to convert between Source and Target code sets. This tutorial expands on concepts covered in “Data Mapping Using Functions”, so users are expected to be familiar with that content.

Before You Begin

Using Tabular Mappings
Working Directory

Download the Using-Tabular-Mappings-Working-Directory.zip file with the sample Working Directory and unzip it on your computer to a convenient place. In our case, it’s c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Tabular Mappings where {USER_NAME} is the user’s name.

Open the eiConsole, browse to your Using Tabular Mappings directory, and open it. The fully configured Data Mapping – Using Tabular Mappings route is included in the Working Directory. Your Route File Management screen will open, as shown below.

Next, follow the tutorial and walk through it step-by-step. You may check your work against the provided Route (Sample Data).

Double-click on the Data Mapping – Using Tabular Mappings

Creating and Configuring a New Format

Start by creating and configuring a new format. Name it “PeopleA XML to PeopleE XML”.

Uncheck “Use Direct Relay” and click “New” to open the Data Mapper.

Then, using the XML Format Reader, read “PeopleA.xml” as the Source. You can find it in c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Using Tabular Mappings\data. The “PeopleE.xml” is also here.

Click the Read Format button.

Then read the “PeopleE.xml” as the Target.

Click the Read Format button.

Now your Data Mapper should look like below.

Mapping Exercise

Repeat the mapping exercise from the previous tutorial, or copy the XSLT using the “XSLT View” tab:

This mapping is pretty much identical to the last except for one detail: in the Source format, Gender is represented by “Male” or “Female,” while in the Target format, Gender is represented by “M” or “F.” Most formats that make use of similar, coded values do not share entry values. For example, one format might represent marital status with “Single” or “Divorced,” while in another format, those respective values could be “1” and “6.” While you can build out these conversions using the choose / when / otherwise instructions, there’s a much simpler way: Tabular Mappings.

Scroll down to the Gender mapping in the panel:

Adding Tabular Mapping

You can see that Gender gets its value from Gender in the Source. To apply a Tabular Mapping to this mapping, drag “Tabular Mapping” from Custom → Uncategorized onto it:

This will open the Tabular Mapping dialog, where you can select from a list of existing mappings:

Of course, we have no such mappings defined yet, so click “Define New” to open a dialog to create a new Tabular Mapping:

This dialog provides a field to name the mapping as well as a table of currently mapped values. If the Source or Target formats loaded in provide enumerations (such as from an XSD or specific industry-specific standards), then the Source and/or Target value columns will have rows pre-populated. As this is not the case for our sample, we’ll have to add rows manually. So we’ll start by naming our mapping.

Naming our Mapping

Next, click the “Add” button to define a new row:

The raised dialog will provide fields to enter the Source and Target values. Since we’re converting between “Male” / “Female” and “M” / “F” codings, provide “Male” and M” for the first row:

Click “OK,” then click “Add” again and do the same for “Female” and “F.” You should now have a table with two rows:

Next, we’ll need to define a “Default Value” – the value that is chosen if the Source “Gender” is neither “Female” nor “Male.” We’ll default to “Unknown”:

Finally, click “OK,” select the new mapping in the previous dialog, and click “Select”:

The resulting mapping element should now look like this:

Finally, drop into the XSLT view to see how the Tabular Mapping is handled:

If you scroll further down, you can see the implementation of the “template,” which is called here to see the choose / when / otherwise logic that the Tabular Mapping tool generated automatically:

Now add the tabular mapping to the Male Node.

Since we already have desired tabular mapping, we just select it.

Your mapping should look like below.

Testing the Mapping

Go to the Testing tab.

And click the Green arrow to test.

XSLT and XPath provide numerous other functions, all of which are available in the tool palette at the top of the Data Mapper screen.

Click on the View Results button for more convenient checking results. Test the mapping and you should see the following for output. Here Female and Male data are replaced with F and M letters accordingly.

As you can see, Tabular Mappings are a powerful tool for handling conversions between code lists and values and can save you considerable amounts of time as you tackle more extensive mappings.

This concludes the tutorial.