© Bluestone Software, Inc. 2000

Transformation Mapping Explained


The transformation mapping functions, Transformation Mapping and Transform Documents, allow you to create a mapping between two XML documents that are based on different document type definitions (DTDs) and transform XML documents based on one DTD to another. The XTransGen engine from IBM alphaWorks does the mapping and transformations.

This is just one transformation used in Bluestone Visual-XML. The Process Wizard uses a different form of transformation, XSL transformation (XSLT).

Why Transformation?

It is not uncommon to have the same data described in different DTDs. Sometimes the differences are simply the names of tags, but other times the differences are more profound. The example below shows two XML documents based on different DTDs, but containing the same weather information (with the second document having a little extra information):

DOCUMENT A
<?xml version = "1.0"?>
 <weather>
   <area city = "Mt. Laurel">
     <temp>92</temp>
     <humid>87</humid>
     <precip>.03</precip>
  </area>
</weather>

 
DOCUMENT B
<?xml version = "1.0"?>
<City>Mt. Laurel
 <CurrentConditions>
   <Temperature>92</Temperature>
   <Humidity>87</Humidity>
   <Wind>
     <mph>8</mph>
     <Direction>SW</Direction>
   <Precipitation>.03</Precipitation>
 </CurrentCondtions>
</City>
In this example, the data values Mt. Laurel, 92, 87 and .03 are common to both, but their tags are different, except for Mt. Laurel, which is the attribute of a tag in one document and the value of a tag in the other. In addition, it is not just the tag names that are different, but also the locations within each document. Receiving a weather report in document A and transmitting it in document B would take a measure of work to determine where the related information is in each document, and then how to transform one into the other, not to mention writing an application to do the transformation.

What would be really helpful is a tool to easily associate items in one document with items in another, produce a conversion template, and use the template to convert any document based on the first document to the second document. This is exactly what the Transformation Mapping and Transform Documents facility is all about: Transformation Mapping maps the items of one document to the items of the other, and creates a conversion file that Transform Documents uses to perform the transformation.

The Transformation Mapping interface consists of three panes: the left one for the first document (input template), the middle one to list the mapping, and the right pane for the second document (output template). The mapping is a drag-and-drop of items from the first document onto the target items of the second document. In this example, the mapping of temp to Temperature is performed by dragging temp from the left pane onto Temperature in the right pane, with the center pane displaying the mapped pair.

The conversion file is created when you click the Generate Conversion Files button. This is where XTransGen comes in. It takes the mappings and creates the conversion file containing the mapped items, and also creates an extras files that contains the items of the output template that were not mapped. The conversion file can be applied against any document based on the input template to produce a document based on the output template. This assumes that XTransGen is used to perform the conversion, which is the case if you use Transform Documents.

The output of the mapping is a conversion file (.cnv) that is used to transform XML documents of DTD A to XML documents of DTD B. The unmapped items are written to an extras file (.xtr). Both are used by Transform Documents.

The table below lists the elements that make up the .cnv file and the elements that make up the .xtr file based on mapping the common weather elements between Document A and Document B:

.cnv (mapped elements) .xtr (unmapped elements)
<City> <Wind>
<CurrentConditions> <mph>
<Temperature> <Direction>
<Humidity>  
<Precipitation>  

Transform Documents uses two panes to display its operation: the left pane holds the input document, the pre-transformed document based on DTD A, and the right pane holds the output document, the transformed document based on DTD B that is created when the user clicks the Transform button.

Having created a conversion file and an extras file based on the documents above, you can now transform a different XML document (Document C) based on DTD A to one based on DTD B (Document D). The result will be:

DOCUMENT C
<?xml version = "1.0"?>
 <weather>
   <area city = "Albany">
     <temp>85</temp>
     <humid>64</humid>
     <precip>1.27</precip>
   </area>
 </weather>
 
 
DOCUMENT D
<?xml version="1.0"?>
<City>Albany
 <CurrentConditions>
   <Temperature>85</Temperature>
   <Humidity>64</Humidity>
   <Precipitation>1.27</Precipitation>
 </CurrentConditions>
</City>
Sample XML and DTD documents are included in the distribution in config/xfiles. They are listed below:

Ours.xml is the result of transforming a document based on partner1.dtd, i.e., partner1.xml, into a document based on ours.dtd. This is shown below.

partner1.xml
<?xml version="1.0"?>
<Employees>
   <Person>
      <FirstName>Scott</FirstName>
      <LastName>Pennell</LastName>
      <DOB value="11-15-61"/>
      <Position started="08-11-92">
         <title>Design Officer</title>
         <department name="Development"></department>
      </Position>
   </Person>
</Employees>
 
 
ours.xml
<?xml version="1.0"?>
<Emp>
   <Worker fname="Scott" lname="Pennell">
      <Birthdate>11-15-61</Birthdate>
      <Position>Design Officer</Position>
      <Startdate>08-11-92</Startdate>
      <Division>Development</Division>
   </Worker>
</Emp>
You can practice transforming the remaining documents based on partner1.dtd into documents based on ours.dtd to get accustomed to how the transformation process works.

Important: The input document for Transform Documents must always be of the same DTD family as the original input document used by Transformation Mapping to create the mapping.


A few notes to finish this discussion:
  1. Transformation is an evolving feature of Bluestone Visual-XML that will be added to as the product progresses. In fact, you will note that both Transformation Mapping and Transform Documents have a list for Transformation Engine even though there is only one item. This is an indication that others will probably be added.
  2. If you have used XTransGen outside of Bluestone Visual-XML, you should note that the mapping implementation used here is different than XTransGen's implementation. XTransGen when run as a standalone application is strictly data-based, that is, only items with the same value in each document will be mapped. No manual mapping is allowed.