eiConsole v.24R1
Tutorial & Interface

eiConsole – Data Mapping & Transformation

Using Identity Transforms

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

Overview

This Interface, along with its associated tutorials, demonstrates the effective utilization of the Data Mapper in Route configurations to transform between XML Formats. In this exercise, we take an existing Route (as introduced in the tutorial Data Mapping – Using Templates) and modify it to perform an XML transformation from the “PeopleA” format to the “PeopleH” format using an “Identity Transform.” Identity transforms allow users to make discrete changes to a document without remapping it in its entirety. It is important to note that this tutorial expands on concepts from “Data Mapping Using Templates,” so familiarity with that content is assumed.

Before You Begin

Using Identity Transforms
Working Directory

Download the Using-Identity-Transforms-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 Identity Transforms where {USER_NAME} is the user’s name.

Open the eiConsole, browse to your Using Identity Transforms directory, and open it. The fully configured Data Mapping – Using Identity Transforms 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 Identity Transforms

Creating & Configuring a New Format

Start by creating and configuring a new Format. Name it “Using Identity Transforms”.

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 Identity Transforms\data. The “PeopleH.xml” is also here.

Click the Read Format button.

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

Click the Read Format button.

Now your Data Mapper should look like below.

Our Source and Target formats are very similar in this case. The only difference is that the Target format’s “Vehicle” element is condensed into a single tag, which is a concatenation of Make and Model. In previous tutorials, we handled such mappings by completely mapping the Source and Target formats along with all of their elements. However, there’s a concept in XSLT called an “identity transform”, which is a template that matches and copies all elements, attributes, and text recursively, as-is. Any templates added in addition to this template are the “exceptions to the rule”; their elements are handled according to those added templates.

Identity Transform

Start by dragging Custom → Uncategorized → “Identity Template” onto the “stylesheet” element:

This template’s expression matches all attributes (@), all child elements (*), and all Nodes (node()). The “|” part of the expression is a “join” between the two halves (@* and node()).

The “copy” element under the template copies the current Node, while the “apply-templates” and expression underneath recursively evaluate all child nodes of the current node.

If you were to run the transform now, you would see that the result document is identical to the source document; the identity transform creates a perfect copy.

Making Changes to the Mapping

To make changes to the mapping, we need only create templates for the elements we wish to alter. To change the handling of Vehicle, drag it from the Source onto the stylesheet:

If you were to run the transform now, you would see that the result document is identical except that the “Vehicle” elements are all missing; we’ve given “Vehicle” special handling, but have not created a new Vehicle element in its stead. Drag “Vehicle” from the Target format onto the “Vehicle” template:

Our mapping will now create a copy of the document with an empty Vehicle element. We are copying all nodes which are not Vehicle.

Concatenating Our Make and Model

Now we just need to concatenate our Make and Model. Drag the “concat” function from the tool palette onto the Vehicle element setting 2 numbers of concat elements.

Modify the expression to combine the Make and Model (separated by a space, of course). You can use this expression to do it manually: concat(Make,' ',Model)“. Don’t forget hit enter.

Now 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.

If we now execute our transform, we should see only the Vehicle element altered:

Identity transforms are an extremely useful tool in transformation. They allow you to make discrete, tactical modifications to a document without needlessly replicating mapping. In the eiConsole, they are most frequently used on the Target Transform stage to “tweak” a previously transformed document so that it conforms to minor changes required by a particular target system.

This concludes this tutorial. Move on to the next tutorial Using Keys for Deduplication.