eiConsole v.24R1
Tutorial & Interface

eiConsole – Data Mapping & Transformation

How to Create a Simple Mapping

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

Overview

This tutorial will guide you through using the PilotFish Data Mapper and creating XSLT to map between different XML formats effectively. Prior knowledge from the Using Transformers tutorial is assumed, as this tutorial builds upon those concepts.

Synopsis

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 the tutorial – Creating a Simple Route is modified to transform a “PeopleA” XML format to a “PeopleB” XML format.

Core Concepts:

• Routes
• Formats
• XSLT Transformer
• Data Mapper
• Format Readers
• XML Format Reader

Before You Begin

Creating a Simple Mapping
Working Directory

Download the Creating-a-Simple-Mapping-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\Creating a Simple Mapping where {USER_NAME} is the user’s name.

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

Next, follow the tutorial step-by-step. Finally, you may check your work against the Route Sample Data provided in the /data directory.

Double-click on Data Mapping – Creating a Simple Mapping.

Creating & Configuring a New Format

You can configure XSLT at either the Source or Target Transform. The reasons for choosing one or the other are usually due to topographical concerns. For this tutorial, it does not matter which we use, so we’ll arbitrarily choose the Target Transform.

Select the Target Transform stage and add a new Format. We’ll call this PeopleB XML to PeopleA XML:

To use XSLT, uncheck the Use Direct Relay option:

You now have a variety of options available to you. For example, you can type in the name of an existing XSLT file, browse to an XSLT file, edit an XSLT file, specify if you wish to cache the XSLT, and even select which XSLT engine to use. Using the defaults for these options is usually more than sufficient for most transformations, regardless of complexity.

Editing a New Mapping

As we have no existing XSLT document to edit, simply clicking the New button with no document selected and it will open the Data Mapper to allow you to edit the new mapping:

This will open the Data Mapper.

The Data Mapper makes use of 3 main panels. On the left side of the screen is a tree representing the Source format. On the right side of the screen is a tree representing the Target format. The middle panel represents the mapping logic, also organized into a tree. Finally, at the bottom-center of the screen are tabs for switching between Mapping, XSLT View and Testing modes.

Loading in the Source and Target Formats

The first thing you’ll typically do when creating a new mapping is load in the Source and Target formats you’ll be working with. To do this for each panel, click the Open Source Format button at the top. We’ll start by loading the Source format:

This will raise a dialog allowing you to pick from a list of Format Readers. Format Readers are components that generate a format structure from some source, be it an XML file, schema file, File Specification, database, etc. For this tutorial, we’ll use XML, which allows us to use an XML sample file to infer a structure from:

Next, we’ll need to add our sample file. Click Add and browse to PeopleB.xml. You can find it in c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Creating a Simple Mapping\data:

Next, click Read Format. You’ll be asked if you want to use the sample file loaded for testing. Select Yes. You should now have a Source panel that resembles this:

Reading the Target Format

Next, we will read our Target format. Select the same button on the Target panel at the right side of the screen and select the XML again. You should see the previous sample listed; click Remove to remove it. Next, click Add, and this time, browse to PeopleA.xml. You can find it in c:\Users\{USER _NAME}\PilotFish eiConsole Working Directories\Creating a Simple Mapping\data.

Note: Remove the file PeopleB.xml from the select format screen before adding PeopleA.xml.

Click Read Format, select Yes, and then review the Target format panel:

For this mapping, there’s no significant difference between the two formats except for one detail: the Target format has a People root element, and the Person elements underneath it repeat. Our Source has only one Person. So we’ll be directly mapping the only Person in the Source to the first Person in the Target.

Constructing the Mapping

The first thing to do in constructing the mapping is to provide a “template” match. These are some elements from the Source that we’ll match against and take some set of actions against. Select the Person element from the Source and drag & drop it onto the stylesheet element in the center:

This will create a Person template in the center:

Creating People from the Target

In XSLT, this creates an instruction called a “template” with an attribute called “match” containing the XPath expression for the Person element in the Source. It effectively means, “when I encounter a Person element, run these instructions.” The action we want to take is to create a People from the Target; effectively, we want to say, “When I encounter a Person element, I want to create a People element.” To do this, drag People from the Target format onto Person in the center:

If we were to test this mapping against our Source sample, we would get an XML output with only a People element. We’ll now create the various elements shown in the Target format.

First, drag & drop the Person child element onto People.

Then, drag & drop each child from the format onto the Person in the center. Note those child elements will need to be dragged onto the respective parents. For example, First should be dragged onto Name instead of onto Person:

The center mapping should look exactly like this:

Providing Values

If we were to run this transformation now, we’d get a single People element, with a single Person element and lots of empty child elements. What we need to do now is to provide each of these with values. To populate the @id attribute, drag the corresponding @id attribute from the Source format onto it:

Continue this for each of the values. Note that you will not drag Name onto the center Name – only its child elements (so First onto First). When you’re finished, it should look something like this:

We have two other sections to investigate now. First, click the XSLT View tab at the bottom of the screen:

This will change the mapping panel to show the underlying XSLT:

Making Changes Directly to the XSLT View

You can make changes directly to the XSLT view and they will show up in the Mapping (GUI) view. In addition, this particular editor features auto-completion, auto-formatting, and a few other useful features for manual editing. Next, click the Testing tab:

This will open the Testing mode for the Data Mapper:

This is made up of 3 panels. The first is the Source sample which, if you used the XML Format Builder, should already have our PeopleB.xml file loaded for testing. The second panel is the Results panel, which shows the transformation results. Finally, the Output panel shows any messages from the XSLT engine, such as errors or warnings.

Executing the Transformation

To execute the transformation, click the Execute Transformation button:

The Results panel will change to show the results of the transformation:

You have now completed your basic mapping. Save the mapping using the Save button or menu item, we’ll name ours “Simple Mapping” and close the Data Mapper to return to the eiConsole.

Reviewing the XML Before and After

From the eiConsole, switch to the Testing Mode.

Set the beginning and end of testing, and click on Execute Test. We’ll need to pick our sample file peopleB.xml. 

Review the XML before.

Our XML “before”:

And review the XML after.

And our resulting XML “after”:

As you can see, performing mappings is simply a matter of dragging & dropping between the Source and Target formats. Continue to the next tutorial Using Iteration to review the complexity and functionality through iteration.