Denodo XSLT Mapper - User Manual
You can translate the document:
Introduction
This document focuses on the Denodo XSLT mapper tool, which allows to easily create XSLT templates to transform an input XML schema into an output XML schema. This tool is based on the Jamper (Java XML Mapper) open source project.
Installation
The Denodo XSLT mapper comes bundled as standalone software in a zip file. After unzipping the file the following folder tree will be created:
Installation directory tree
The scripts for executing the XSLT mapper will be located under the bin folder. To start the XSLT mapper on Windows systems the denodomapper.bat must be used, for UNIX like operating systems the script denodomapper.sh after adding execution permissions to the script.
Uninstalling the XSLT Mapper
By deleting the directory created after unzipping the installation file the Denodo XSLT Mapper will be completely removed from the system.
Using the XSLT Mapper
The Denodo XSLT mapper can be used to map an input XML schema into an output XML schema and create the XSLT document corresponding to such mapping, which can then be used for adapting Denodo Web Services output to a different desired schema.
When we first open the XSLT mapper, we will be offered a Mapping panel, divided into three different subpanels:
- The left panel or Source Tree panel will be used to display and work with the input XML schema.
- The central panel or Transformation panel will be used to add and configure the transformations to be applied between the original schema and output schemas.
- The right panel or Destination Tree panel will be used to display and work with the output XML schema.
Main screen - Mapping tab
To start working with the XSLT mapper, an input XML schema and a desired output XML schema have to be loaded.
In order to load the input schema go to File > Source Tree to select an XML file.
Loading source tree
We can load the schema in two different ways:
- Load from file: the XML file can be selected from a file chooser from your local hard disk drive.
- Generate from WSDL: this option can be used to generate request or response SOAP message XMLs directly from its WSDL file. The WSDL file can be imported locally or directly from its URL.
If we are using the second option, once the WSDL is loaded, the following screen will be shown:
From this screen, we have to choose the following:
- Method: the drop down menu will show the different operations available in the WSDL.
- SOAP Message. Request or response. Response can be auto generated with dummy values based on the WSDL defined structure, or obtained by querying the web service for real. In this case, the request and its headers will have to be set accordingly, based on the automatically generated values.
- The values to be filled are specified as question marks (?)
- The headers are specified in the format "<header1>":"<value1>"[;"header2":"value2"]
For example: "SOAPAction":"http://xxx.com/action";"Content-Type":"text/xml"
Once the corresponding option is selected, click on Generate to see the generated XML in a popup screen. This XML can be edited if necessary. Click on Use to load this XML in the mapper, or in Cancel to go back to the previous screen.
Once the source is selected, from file or WSDL, its schema will be loaded into the Source Tree panel and the different elements, nodes and attributes of the XML file loaded will be displayed showing the tree structure of the XML schema:
Source Tree panel
The different nodes of the XML schema will be displayed in a hierarchical way. For each node, in addition to its name we will also have access to its children node and to the text values of the nodes and their attributes.
When a node or leaf element is selected the name of the element and its value will be displayed in the left hand side of the bottom panel.
In order to generate the XSLT transformation we also need to specify an example of the output schema that we want to obtain. To do so go to File > Destination Tree, and follow the same instructions.
The output schema will be loaded into the Destination Tree panel and the different elements, nodes and attributes of the XML loaded file will be displayed showing the tree structure of the XML schema:
Destination tree panel
The different nodes of the output XML will be displayed in a hierarchical way and for each node, in addition to its name, we will have access to its children nodes and to the text values of the nodes and their attributes.
When a node or leaf element is selected the name of the element and its value will be displayed in the right hand side of the bottom panel.
Adding Transformations
Once the input and output schemas have been loaded we can start to add the transformation that will generate the XSLT template.
In order to add a transformation for an input element select the element and draw a line between this input element and the element in the output schema. This will create a link between an input element and an output element. This link will be labeled with the type of transformation that will be applied to the input element to generate the output.
xsl:value-of transformation
If the selected input and output element are complex and have hierarchical elements, the XSLT Mapper will add links relating the children which have similar names. Notice that the automatic link operation is not taking into consideration capital letters, the underscores or other characters such as “:”. This implies that, maybe, the user has to delete or modify some of these links.
By default a transformation of xsl:value-of will be created but three different types of basic transformations can be created this way:
- xsl:value-of: can be used to extract the value of an XML element and add it to the output of the transformation. In addition to the text label you can identify this type of transformation because it will be colored in black.
- xsl:template: contains rules to apply when a specified node is matched. In addition to the text label you can identify this type of transformation because it will be colored in green.
- xsl:for-each: can be used to select every XML element of a specified node-set. In addition to this type of transformation you can identify this transformation because it will be colored in blue.
To switch between the different types of transformations the transformation line must be selected in the central panel. Once the line is selected it will be colored in red and using the contextual menu and then the Line submenu the type of transformation can be changed.
Changing transformation type
From this contextual menu is also possible to delete the transformation by clicking the option Remove.
In addition to these basic transformation options, advanced mapping options can be added to the transformation panel by using the Map option in the contextual menu. The available options are:
- Creation of variables.
- Use of If statements.
- Use of XSLT functions.
- Use of Choose statements.
- Creation of complex expressions.
Map menu
Variables
A newly created variable will be represented with a square icon and it will be created with a default name and a default value. We can rename the variable and set it to a different constant value using the Rename... and Set Value... options in the contextual menu.
If we drag and drop an element from the input tree to the input of the variable component the variable value will be the same as the output and the specified constant value will be ignored.
If we select the Global option the variable will be declared in the XSLT template at the top level and it will be available for its use in any node of the template.
Variable contextual menu
If statements
An If statement will be represented by a triangle icon with two inputs and an output. The inputs of the If statement will be the input itself and a condition. The condition has to be a boolean expression already present in the input tree or it can be created as a variable, a complex expression or a function.
For instance, if we create a variable with the value true and we connect this variable with the condition of the If statement, and then we connect the input of the component with an element of the input tree, the component will be translated into the XSLT template as:
<con:ConferenceId> <xsl:variable name="var_bool_exp" select="'true'"/> <xsl:if test="$var_bool_exp"> <xsl:value-of select= "soapenv:Body/con:getConference/CONFERENCEID/text()"/> </xsl:if> </con:ConferenceId> |
where var_bool_exp is the name of the variable provided as condition and the value selected inside the if is the element in the input XML specified as input of the If statement.
IF statement
IF statement use
XSLT Functions
The use of functions is limited to the XSLT functions Equals, NotEquals, IsEmpty and NotEmpty. The functions will be represented by a triangle icon. They will have two input parameters for the Equals and NotEquals functions and one single input parameter for the isEmpty and isNotEmpty functions, the output of the functions will be a boolean value.
Function component with Equals operator
Choose statements
The Choose statement will not have initially any associated input. To add an input it will be necessary to add a When statement. The When statement will be used in combination with the Choose statement to specify a set of conditions that will define the output. One or more when statements can be added using the contextual menu ChooseBox > Add Parameter. Each different when statement will have the same configuration as an If statement.
CHOOSE statement use
Complex expressions
A complex expression can be used to create a complex transformation without having to include all of the components in the central panel. The complex expression will be represented as a single element that will be possible to edit in a separate window. To edit a complex expression the option Expression > Design… can be used.
From the same contextual menu any number of inputs can be added to the component, when editing the component an element for each component will be created and an output component will already be preconfigured.
As part of a complex expression any of the elements that we have already seen can be used to perform any combination of the input parameters.
Complex expression
Complex expression design
Save Map
You can save the map that you are building to a file using File > Map > Save. The links to the files containing the source and the destination trees, and the transformations of the map will be stored in the file you specify.
Maps can also be loaded from files using File > Map > Load. The source and destination files for the loaded maps have to be in the same location they were when the map was saved, if not you can edit the file of the map, changing the <src> tag and the <dst> tag.
XSLT Transformation tab
Once the needed transformations have been added, the XSLT template generated can be verified using the XSLT Transformation tab. In this window the XSLT template will be displayed along with an example of the output XML that would be generated if this XSLT template was applied to the source XML loaded.
XSLT Transformation tab
In the XSLT Transformation tab the XSLT is displayed in the left panel and the output example is displayed in the right panel of the window.
Once the XSLT template has been created according to our needs, it can be saved to a file using the File > Save XSLT option.
Save XSLT