This tutorial shows you how to convert data between two XML files, while helping you learn the basics of the MapForce development environment. Both XML files store a list of books, but their elements are named and organized in a slightly different way (that is, the two files have different schemas).
Abstract model of the data transformation
The code listing below shows sample data from the file that will be used as data source (for the sake of simplicity, the XML and the namespace declarations are omitted).
This is how data should look in the target (destination) file:
As you may have noticed, some element names in the source and target XML are not the same. Our goal is to populate the <author>, <title>, <genre> and <publish_year> elements of the target file from the equivalent elements in the source file (<author>, <title>, <category>, <year>). The attribute id in the source XML file must be mapped to the <id> element in the target XML file. Finally, we must populate the <last_updated> element of the target XML file with the date and time when the file was last updated.
To achieve the required data transformation, let's take the following steps.
Step 1: Select XSLT2 as transformation language
You can do this in one of the following ways:
•Click the XSLT2 ( ) toolbar button.
•On the Output menu, click XSLT 2.0.
Step 2: Add the source XML file to the mapping
The source XML file for this mapping is located at the following path: <Documents>\Altova\MapForce2020\MapForceExamples\Tutorial\books.xml. You can add it to the mapping in one of the following ways:
•Click the Insert XML Schema/File ( ) toolbar button.
•On the Insert menu, click XML Schema/File.
•Drag the XML file from Windows Explorer into the mapping area.
Now that the file has been added to the mapping area, you can see its structure at a glance. In MapForce, this structure is known as a mapping component, or simply component. You can expand elements in the component either by clicking the collapse ( ) and expand icons ( ), or by pressing the + and - keys on the numeric keypad.
To move the component inside the mapping pane, click the component header and drag the mouse to a new position. To resize the component, drag the corner of the component . You can also double-click the corner so that MapForce adjusts the size automatically.
The top level node represents the file name; in this particular case, its title displays the name of the XML instance file. The XML elements in the structure are represented by the icon, while XML attributes are represented by the icon.
The small triangles displayed on both sides of the component represent data inputs (if they are on the left side) or outputs (when they are on the right side). In MapForce, they are called input connectors and output connectors, respectively.
Step 3: Add the target XML schema to the mapping
To generate the target XML, we will use an existing XML schema file. In a real-life scenario, this file may have been provided to you by a third party, or you can create it yourself with a tool such as XMLSpy. If you don't have a schema file for your XML data, MapForce prompts you to generate it whenever you add to the mapping an XML file without an accompanying schema or schema reference.
For this particular example, we are using an existing schema file available at: <Documents>\Altova\MapForce2020\MapForceExamples\Tutorial\library.xsd. To add it to the mapping, follow the same steps as with the source XML file (that is, click the Insert XML Schema/File ( ) toolbar button). Click Skip when prompted by MapForce to supply an instance file.
At this stage, the mapping design looks as follows:
Step 4: Make the connections
For each <book> in the source XML file, we want to create a new <publication> in the target XML file. We will therefore create a mapping connection between the <book> element in the source component and the <publication> element in the target component. To create the mapping connection, click the output connector (the small triangle) to the right of the <book> element and drag it to the input connector of the <publication> element in the target.
When you do this, MapForce may automatically connect all elements which are children of <book> in the source file to elements having the same name in the target file; therefore, four connections are being created simultaneously. This behavior is called "Auto Connect Matching Children" and it can be disabled and customized if necessary.
You can enable or disable the "Auto Connect Matching Children" behavior in one of the following ways:
•Click the Toggle auto connect of children ( ) toolbar button.
•On the Connection menu, click Auto Connect Matching Children.
Notice that some of the input connectors on the target component have been highlighted by MapForce in orange, which indicates that these items are mandatory. To ensure the validity of the target XML file, provide values for the mandatory items as follows:
•Connect the <category> element in the source with the <genre> element in the target
•Connect the <year> element in the source with the <publish_year> element in the target
Finally, you need to supply a value to the <last_updated> element. If you move the mouse over its input connector, you can see that the element is of type xs:dateTime. Note that, for tips to be displayed, the Show tips ( ) toolbar button must be enabled.
You can also make the data type of each item visible at all times, by clicking the Show Data Types ( ) toolbar button.
You can get the current date and time (that is, the xs:dateTime value) by means of a date and time XSLT function. To find the XSLT function to the mapping, start typing "date" in the text box located in the lower part of the Libraries window. Alternatively, double-click an empty area on the mapping and start typing "current-date".
As shown above, if you move the mouse over the "result" part of the function, you can see its description. For tips to be displayed, make sure that the Show tips ( ) toolbar button is enabled.
To add the function to the mapping, drag the function into the mapping pane, and connect its output to the input of the <last_updated> element.
You have now created a MapForce mapping design (or simply a "mapping") which converts data from the books.xml instance file (having the books.xsd schema) to the new library.xml file (having the library.xsd schema). If you double-click the header of each component, you can view these and other settings in the Component Settings dialog box, as shown below.
Component settings for the source
Component settings for the target
Step 5: Validate and save the mapping
Validating a mapping is an optional step that enables you to see and correct potential mapping errors and warnings before you run the mapping. To check whether the mapping is valid, do one of the following:
•On the File menu, click Validate Mapping.
•Click the Validate ( ) toolbar button.
The Messages window displays the validation results:
At this point, you might also want to save the mapping to a file. To save the mapping, do one of the following:
•On the File menu, click Save.
•Click the Save ( ) toolbar button.
For your convenience, the mapping created in this tutorial is available at the following path: <Documents>\Altova\MapForce2020\MapForceExamples\Tutorial\\BooksToLibrary.mfd. Therefore, from this point onwards, you can either continue with the mapping file you created, or with the BooksToLibrary.mfd file.
Step 6: Preview the mapping result
You can preview the result of the mapping directly in MapForce. To do this, click the Output button located in the lower part of the mapping pane. MapForce runs the transformation and displays the result of the mapping in the Output pane.
You can now see the result of the transformation in MapForce.
By default, the files displayed for preview in the Output pane are not written to the disk. Instead, MapForce creates temporary files. To save the file displayed in the Output pane to the disk, select the menu command Output | Save Output File, or click the Save generated output ( ) toolbar button.
To configure MapForce to write the output directly to final files instead of temporary, go to Tools | Options | General, and then select the Write directly to final output files check box. Note that enabling this option is not recommended while you follow this tutorial, because you may unintentionally overwrite the original tutorial files.
You can also preview the generated XSLT code that performs the transformation. To preview the code, click the XSLT2 button located in the lower area of the mapping pane.
To generate and save the XSLT2 code to a file, select the menu item File | Generate Code in | XSLT 2.0. When prompted, select a folder where the generated code must be saved. After code generation completes, the destination folder includes the following two files:
1.An XSLT transformation file, named after the target schema (in this example, MappingMaptolibrary.xslt).
2.A DoTransform.bat file. The DoTransform.bat file enables you to run the XSLT transformation in RaptorXML Server (for more information, see https://www.altova.com/raptorxml.html ).