The XSLT component allows user to configure source and target document structures using Fiorano Mapper and create an 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.

Configuration and Testing

Component Configuration

The Component Configuration for XSLT is defined in the Configuration Property Sheet panel as shown in Figure 1.

Figure 1: CPS Expert Property view enabled

Attributes

Validate Input

Please refer the respective section Common Configurations page for information.

Error handling configuration

The remedial actions to be taken when a particular error occurs can be configured here.

Click on the ellipsis button against Error Handling Configuration property to configure Error Handling properties.

Please refer the following subsections under Error Handling section in Common Configurations page for more details.

• JMS Error
• Response Generation Error
• Request Processing Error
• Invalid Request Error

The remedial actions to be taken when a particular error occurs can be configured in Response Generator Error section.

Figure 2: Response Generator Error section in Error Handling Configuration

The default actions configured are:

• Log to Error logs
• Send to error port

Use Mapper to define transformation

This property determines the means of defining XSL that will be used for transformation.

Fiorano Mapper can be used to define transformation if this property is enabled.

• If enabled, another property called Mappings will be visible and property XSL is made expert.

• If disabled:
  • Mappings property will not be 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.
  • Removes value defined for Mappings property.

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.

Expert Properties

Mappings

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.

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 will be overwritten.

Figure 3: Launching Fiorano Mapper

Loading Input and Output Structures in Fiorano Mapper

• A maximum of two structures can be loaded in the Input Structures panel of Fiorano Mapper: Application Context of the Event Process, structure of the XML instance present in the body of input message or both. The Application Context, if loaded, will always be the first structure.
• A maximum of two structures can be loaded in the Output Structures panel of Fiorano Mapper.
  • First structure describes output XML instance which is the result of transformation: Application Context of the Event Process or the structure of the XML instance present in the body of input message

  • Second structure is JMS-Message structure available from Import Structure From.. (click button to get the option).

    Icon

    Any other structure than JMS Message structure will result in erroneous behavior at component's runtime.

• When the Fiorano Mapper is launched, input structures are loaded as described below:
  
  • If the component is already configured, previously configured structures will be loaded in Input Structures panel.
    
    • If the Input Structure has Application-Context, and if the application context schema for the Event Process is modified after the previous configuration, the new structure is loaded.
    • If the Input Structure has input message structure, the modified structure is retained even if the structure defined on the output port of component connected to input port of this component is changed.
  • If the component was not previously configured, application context structure defined in the Event Process or default application context structure (<!ELEMENT Context (#PCDATA)>), if no structure is defined, will be loaded as the first structure. One of the structures on other components' output port which is connected to this component's input port is loaded as the second structure. If the component's input port is not connected to any other component's output port which has a structure, the second structure will not be loaded automatically. A Structure can be loaded manually either by typing-in or by copying the structure from the file system.
    
    
• When the Fiorano Mapper is launched, output structures are loaded as described below:
  • If the component is already configured, previously configured structures will be loaded in Output Structures panel.
    • If the Output Structure has Application Context, and if the application context schema for the Event Process is modified after the previous configuration, the new Structure is loaded.
    • If the Output Structure has output message structure, the modified structure is retained even if the structure defined on the input port of component connected to output port of this component is changed.
    • If the JMS Message structure is loaded during previous configuration, then it will be loaded as the second structure.

  • If the component was not previously configured, one of the structures on other component's input port which is connected to this component's output port is loaded as the only structure. If the component's output port is not connected to any other component's input port which has a structure, the Output Structure will be empty. A structure can be loaded manually either by typing-in or by copying the structure from the file system. Application Context can be loaded to the Output Structures panel by using the Import Structure From.. (click ) button and selecting Application-Context option.

    Icon

    Only one of Application-Context or output message structure can be loaded to the Output Structures panel in a given mapping.

• When structure of connected component's input port or output is changed but previously configured structure is restored, to update the structure right-click the structure that should be changed and click on Update with imported structure... and select IN_PORT or OUT_PORT respectively.

  Icon

  When the structure is changed, mappings for nodes that are not at same Xpath location before and after the change will be discarded.

• When the Fiorano Mapper is closed, structures defined for message body, if any, in Input Structure or Output Structure will be set on the input port or the output port of the component respectively.

XSL

When the Use Mapper to define transformation property is

• Enabled: XSL value will be automatically populated after defining mappings in the Fiorano Mapper.
• Disabled: XSL needs to be manually provided here.

JMS-Message XSL

This property defines the XSL that will be used to transform source data from Input Structures 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 Use Mapper to define transformation property is

• Enabled: JMS-MEssage XSL value will be automatically populated after defining mappings in the Fiorano Mapper.
• Disabled: XSL which generates XML corresponding to structure shown in figure 4 should be manually provided here.

Figure 4: Structure of XML which is result of applying JMS-Message XSL

Defining JMS-Message XSL using Fiorano Mapper

To define JMS-Message XML using Fiorano Mapper, perform the following actions:

1. Define first output structure which represents the structure of message body or application context that has to be set on output message.
2. Click on Import Structure From..  button and choose JMS-Message option as shown in the figure below.
   
   
   Figure 5: Loading JMS-Message structure on output
   
   An output structure JMS-Message is added in the Output Structure as shown in figure 6.
   
   
   Figure 6: JMS-Message Structure loaded on output
   
   

3. 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. Figures 6 shows the mappings for name, type and Property respectively.

   Icon

   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"
   
   

4. Multiple properties can be added by duplicating the element Property.
   
   

   Figure 8: Duplicating Property node
   
   

5. To set the content of message body on the output message, required content should be mapped to Text as shown in figure 9.
   
   
   Figure 9: Setting message body

   Icon

   When content is mapped to Text element of JMS-Message structure and the structure of the output message body XML is loaded in the mapping, 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.

Xslt Engine

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.

  Icon

  Xalan(2.7.0) does not support XSLT 2.0

• Saxon
  Saxon implementation (net.sf.saxon.TransformerFactoryImpl) is used to perform transformation.

  Icon

  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 Saxon or Xalan provided by Xslt Engine has to be used.

Figure 10: Setting message body

Resources (jar files) containing the java class specified against this property should be added as resources to XSLT component.

Strip White Spaces

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.

• None
  Attribute to strip whitespace is not set at all. Behavior will be dependent 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 11: Sample transformation

Xslt Engine is chosen as Saxon and Strip White Spaces property is set to True as shown in figure 11. Input XML in figure 12 contains Title element which has whitespace.

Figure 12: Saxon engine with Strip White Spaces set to True

Input XML shown in the figure below contains only whitespace for Title element. After the transformation train element of output XML does not whitespace though there is a simple mapping from input XML's Titleelement.

Figure 13: Input XML with whitespace in element Title and output XML without whitespace for train

Fail transformation on error

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

• Enabled
  • 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
• Disabled
  • 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 (figure 2)
  • 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

Optimization

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 the figure below) cannot be used.

Figure 14: 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.

 

Functional Demonstration

Scenario 1

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 15: Mapping used

Figure 16: Demonstrating scenario 1 with sample input and sample output

Use Case Scenario

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 17: 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 present in the eStudio tool.

Useful Tips

• Suitable JDBC drivers required for Lookup functions have to be added as Service Dependencies or as Resources to XSLTFunctions System Lib. Refer Add Resources to a Microservice section for directions to perform this.