Use Mapper to define transformation
Testing the Interaction Configurations
The XSLT component allows user to configure source and target document structures using Fiorano Mapper and create a XSL used for transforming documents. Alternatively, it allows users to define XSL created using external tools. Documents passed to the component are transformed using the XSL defined.
The configuration for XSLT is defined in the Interactions Configurations panel as shown in Figure 1.
Figure 1: Interaction Configurations panel with expert view enabled
Click on the ellipsis button against Error Handling Configuration property to configure Error Handling properties.
Figure 2: Error Handling Configuration
The remedial actions to be taken when a particular error occurs can be configured here.
The default actions configured are:
Log to error logs
Send to error port
This property determines the means of defining XSL that is used for transformation.
● yes
When this value is selected property Mappings is visible and property XSL is made expert. Fiorano Mapper is used to define transformation.
● no
When this value is selected property Mappings is not visible and property XSL is visible as a normal property. Fiorano Mapper cannot be used to define transformation and XSL for transformation has to be manually provided.
Note:
Changing this value from yes to no does the following changes
Removes value defined for property Mappings
Changes the value of Transformation source data to Body, if this value is not changed explicitly by the user even once after the CPS is opened.
Any mappings previously defined using Fiorano Mapper will have to be redone. However the XSL(s) computed from mappings and set against properties XSL and JMS-Message XSL will still be present and can be used for transformation if the property value for property Transformation source data is not changed. If the value for property Transformation source data is automatically changed it should be reverted back manually.
Changing the value back to yes does not restore the value of property Mappings and removes values for properties XSL and JMS-Message XSL. These XSL(s) have to be redefined.
This property determines the source for XML instance(s) from the input message on which XSL transformation should be applied for generating output XML. The source for XML instance(s) can be:
● Body
The transformation is applied to XML instance that is taken from the message body of the input message. Input structure in Fiorano Mapper contains the XSD/DTD defined for message body (same as structure on the input port of the component).
● Context
The transformation is applied to XML instance that is taken from the application context property of input message. Input structure in Fiorano Mapper contains the XSD/DTD defined for application context.
● Context-Body
The transformation is applied to XML instances that are taken from both message body and application context property of input message. Input structure in Fiorano Mapper contains XSD/DTD defined for application context as well as XSD/DTD for input body.
Note: In this case, XML instance of application context is treated as primary source. Elements in primary source can be referenced directly in XSL, where as elements of other structure should be referenced as document (<StructureName>)/<ElementName>.
This property determines where the result of transformation of source data using XSL is set in the output message.
● Body
The result of the transformation is set as message body on the output message.
● Context
The result of the transformation is set as the application context property of the output message.
The property defines the Fiorano Mapper project (contents of .tmf file)
that can be created using Fiorano Mapper. XSL required for transformation
is created automatically based on the mappings defined in Fiorano Mapper.
Click the ellipsis button 
to open the Fiorano Mapper
tool for visually defining the XSL.
Figure 2: Launching Fiorano Mapper
Every time the Fiorano Mapper is closed after saving the mappings defined, XSL(s) computed using the mappings defined are set against the properties XSL and JMS-Message XSL. Any previously set XSL(s) content against these properties are overwritten.
Loading input and output structures in Fiorano Mapper
Maximum number of structures that can loaded in the Input Structure of Fiorano Mapper is determined by the value for property Transformation source data.
Body – one input structure that describes the XML instance present in message body of input message.
Context – one input structure that describes the XML instance present in application context of input message.
Context-Body – Two input structures, first structure that describes the XML instance present in application context of input message and second structure that describes the XML instance present in message body of input message. The order of these structures should strictly be as described.
Maximum of two structures can be loaded in the Output Structure of Fiorano Mapper. First structure that describes output XML instance which is the result of transformation and second structure is JMS-Message structure available from Import Output Structure... The order of these structures should strictly be as described and the second structure should only be JMS-Message structure, any other structure results in erroneous behavior at component's runtime.
When the Fiorano Mapper is launched, input structures are loaded as described below.
If value for property Transformation source data is set to Body, Input Structure in Fiorano Mapper will be loaded with structure as described below.
- Previously configured structure, if the component is already configured using Fiorano Mapper. If the structure defined on the output port of other component connected to input port of this component is changed, it is logged in the Messages window in Fiorano Mapper, but the previously configured structure is retained.
- One of the structures on other component's output port which is connected to this component's input port, if the component is not previously configured using Fiorano Mapper.
- No structures, if the component is not previously configured and the component's input port is not connected to any other component's output port which has a structure defined. In such a case, structure can be loaded manually either by typing in/copying the structure or from a file system.
If value for property Transformation source data is set to Context, Input Structure in Fiorano Mapper will be loaded with structure as described below.
- Structure defined for application context in Event Process. If application context structure is changed after the previous configuration, then the new structure is loaded.
- Default application context structure (<!ELEMENT Context (#PCDATA)>) if application context structure is not defined.
If value for property Transformation source data is set to Context-Body, Input Structure in Fiorano Mapper will be loaded with structures in order as described below.
- Structure for application context as described for the case where Transformation source data is set to Context.
- Structure for message body as described for the case where Transformation source data is set to Body.
When the Fiorano Mapper is launched, output structures are loaded as described below.
If value for property Set transformation result as is set to Body, Output Structure in Fiorano Mapper will be loaded with structure as described below
- Previously configured structure, if the component is already configured using Fiorano Mapper. If the structure defined on the input port of other component connected to output port of this component is changed, it is logged in the Messages window in Fiorano Mapper, but the previously configured structure is retained.
- One of the structures on other component's input port which is connected to this component's output port, if the component is not previously configured using Fiorano Mapper.
- No structures, if the component is not previously configured and the component's output port is not connected to any other component's input port which has a structure defined. In such a case, structure can be loaded manually either by typing in/copying the structure or from a file system.
If value for property Set transformation result as is set to Context, Output Structure in Fiorano Mapper will be loaded with structure as described below.
- Structure defined for application context in Event Process. If application context structure is changed after the previous configuration, then the new structure is loaded.
- Default application context structure (<!ELEMENT Context (#PCDATA)>) if application context structure is not defined.
If the JMS-Message structure is loaded during previous configuration, then it is loaded as second structure.
When structure of connected component's output or input port is changed, but previously configured structure is restored, to update the structure right-click the structure that should be changed and click Update with imported structure... and select IN_PORT or OUT_PORT respectively.
Note: When the structure is changed, mappings for nodes that are not at same Xpath location before and after the change is discarded.
When the Fiorano Mapper is closed structures defined for message body, if any, in Input Structure or Output Structure is set on the input port or the output port of the component respectively.
This property defines the XSL that is used to transform source data from source defined against property Transformation source data to required output that is set on target defined against property Set transformation result as. When the value for property Use Mapper to define transformation is set to yes this value is automatically populated after defining mappings in Fiorano Mapper. When the value for property Use Mapper to define transformation is set to no, XSL should be manually provided here.
Note: If the XSL contains any custom java functions, jar files containing such functions should be added as resources to XSLT component.
This property defines the XSL that is used to transform source data from source defined against property Transformation source data to required interim XML which defines JMS message properties and text that has to be set. The component parses this interim XML and sets the required JMS properties and their values on the output message. When the value for property Use Mapper to define transformation is set to yes this value is automatically populated after defining mappings in Fiorano Mapper. When the value for property Use Mapper to define transformation is set to no, XSL which generates XML corresponding to structure shown in Figure 3 should be manually provided here.
Figure 4: Structure of XML which is result of applying JMS-Message XSL
Note: JMS properties can be set alternatively using JMS Message Functions in Funclet tab of Fiorano Mapper.
Defining JMS-Message XSL using Fiorano Mapper
Define first output structure which represents the structure of message body or application context that has to be set on output message based on property Set transformation result as
Click Import Output Structure and choose JMS-Message as shown in Figure 5.
Figure 5: Loading JMS-Message structure on output
An output structure JMS-Message is added in the Output Structure as shown in figure Figure 6.
Figure 6: JMS-Message Structure loaded on output
For the property that has to be set on the output message, the name and type of the property should be mapped to the attributes name and type respectively. The value of the property should be mapped to the element Property. Figure 7 shows the mappings for name, type, and Property respectively.
Note: type can values Byte, Short, Integer, Long, Float, Double, Boolean. Any other value defined for type is treated as String type.
Figure 7: Mappings for defining a String property with name "FileName" and value "samplefile.txt"
Multiple properties can be added by duplicating the element Property as
Figure 8: Duplicating Property node
To set the content of message body on the output message, required content should be mapped to Text as shown in Figure 8.
Figure 9: Setting message body
Note: When content is mapped to Text element of JMS-Message structure and Set transformation result as property is set to Body, content mapped to Text element of JMS-Message structure takes precedence of result of transformation and the body of output message contains content mapped to Text element of JMS-Message structure.
This property along with Transformer factory class property when this property's value is Other determines the transformer implementation that should be used to perform the transformation.
Xalan (2.7.0) and Saxon (8.4) transformer implementations are bundled with Fiorano environment for performing transformations.
Xalan
Xalan implementation (org.apache.xalan.processor.TransformerFactoryImpl) is used to perform transformation.
Note: Xalan (2.7.0) does not support XSLT 2.0
Saxon
Saxon implementation (net.sf.saxon.TransformerFactoryImpl) is used to perform transformation.
Note: Saxon implementation does not support custom functions
Other
This option should be used when a custom transformer implementation has to be used. Selecting this option shows property Transformer factory class which can be used to provide the transformation factory implementation that should be used.
Transformer factory class
This property determines the fully qualified name of the class which should be used to perform transformation when the transformer implementation other than that is provided by Saxon or Xalan has to be used. The class provided should be an implementation of javax.xml.transform.TransformerFactory.
Resources (jar files) containing the java class specified against this property should be added as resources to XSLT component.
This property determines whether elements in input XML which have only whitespace content should be stripped of the content unconditionally before the transformation is done.
Note: This property works only with Saxon.
None
Attribute to strip whitespace is not set at all. Behavior dependents on the transformer's implementation. For Saxon implementation shipped with Fiorano the behavior is same as that of False.
True
Whitespace content is stripped from input XML before the transformation is done.
False
Whitespace content is retained as it is.
Example: Figure 10 shows a sample transformation defined.
Figure 10: Sample transformation
Xslt Engine is chosen as Saxon and Strip White Spaces property is set to True as shown in Figure 10. Input XML in Figure 10 contains Title element which has whitespace.
Figure 11: Saxon engine with Strip White Spaces set to True
Input XML, shown in Figure 12, contains only whitespace for element Title. After the transformation train element of output XML does not whitespace though there is a simple mapping from input XML's Title element.
Figure 12: Input XML with whitespace in element Title and output XML without whitespace for train
This property determines how the problems that occur during the transformation have to be handled. There are three levels of problems that can occur during the transformation. Warnings, errors, and fatal errors
no
Transformer warnings are only logged at log level WARNING
Transformer errors are only logged at log level WARNING
Transformer fatal errors are reported as errors in component
yes
Transformer warnings are logged at level WARNING and are also treated as errors in component if Throw fault on warnings remedial action is enabled under Request Processing Error in Error Handling panel (Figure 12)
Transformer errors are reported as errors in component and remedial actions, if any, defined in Error Handling panel are taken.
Transformer fatal error are reported as errors in component
This property determines whether some internal structures can be cleared so as to make some additional memory available for transformation.
When property Set transformation result as is set to Body, message body is cleared from input message after message body is loaded into input for transformer and before transformation begins. In this case, Text-Content and Byte-Content functions of JMS Message functions in Fiorano Mapper (shown in Figure 13) cannot be used.
Figure 13: JMS Message functions in Fiorano Mapper
When property Set transformation result as is set to Context, content in application context is cleared from input message after content in application context is loaded into input for transformer and before transformation begins.
Note: This property comes into effect only when there is no JMS-Message XSL defined.
The scenario demonstrates a simple XSLT mapping. In this mapping,
The String Hello is appended before the Name in the Input message
Element Message is mapped to Message
Email is ignored
The response is sent to the output port
Configure the XSLT component as described in Configuration and Testing section and use feeder and display component to send sample input and check the response respectively.
Figure 14: Mapping used
Figure 15: Demonstrating scenario 1 with sample input and sample output
In EAI Demo sample, XSLT is used in extracting the Email ID, Order ID from the input XML and some mappings are defined between them with the POP3 schema elements and to construct the message body.
Figure 16: Sample use-case scenario
The Event Process demonstrating this scenario is bundled with the installer.
Documentation of the scenario and instructions to run the flow can be found in the Help tab of flow when open in Studio.
Suitable JDBC drivers required for Lookup functions have to be added as Service Dependencies or as Resources to XSLTFunctions System Lib.
Copyright © 1999-2008, Fiorano Software Technologies Pvt. Ltd. All rights reserved.
Copyright © 2008-2009, Fiorano Software Pty. Ltd. All rights reserved.
This software is the confidential and proprietary information of Fiorano Software ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement enclosed with this product or entered into with Fiorano.