XMLTransformation node

This topic contains the following sections:

Purpose

Use the XMLTransformation node to transform an XML message to another form of XML message, according to the rules provided by an XSL (eXtensible Stylesheet Language) style sheet.

You can specify the location of the style sheet to apply to this transformation in one of three ways:

  1. You can use node properties. This ensures that the transformation defined by this single style sheet is applied to every message processed by this node.
  2. You can use the content of the XML data within the message itself. This transforms the message according to a style sheet that the message itself defines.This behavior is only available for XSL and XML files that are located within a Message Flow project.
  3. You can set a value within the LocalEnvironment folder associated with the message. This provides a dynamic choice of style sheet, because you must set this value (in a Compute node) within the message flow after receipt of the message. You can therefore use a variety of inputs to determine which style sheet to use for this message, such as the content of the message data or a value in a database.

An XSLT (eXtensible Stylesheet Language for Transformations) compiler is used for the transformation if the style sheet is not embedded within the message and the node cache level (node property Stylesheet Cache Level) is greater than 0.

The XMLTransformation node is represented in the workbench by the following icon:

XMLTransformation node icon

Using this node in a message flow

For an example of how to use this node, consider two news organizations that exchange information on a regular basis. One might be a television station, the other a newspaper. Although the information is similar, the vocabulary used by the two is different. This node can transform one format to the other by applying the rules of the specified style sheet. If you specify the style sheet in the message (either the XML data or the LocalEnvironment), the same node can perform both transformations.

Configuring the XMLTransformation node

When you have put an instance of the XMLTransformation node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.

Configure the XMLTransformation node as follows:

  1. Select values for the XML Embedded Selection Priority, Message Environment Selection Priority, and Broker Node Attribute Selection Priority properties. The values that you set determine the order in which alternative locations are searched for the stylesheet information. The highest priority setting is 1. The default order is:
    1. XML Embedded Selection Priority, which therefore has a default value of 1. The node searches the XML data for stylesheet location information. For example, the XML data might contain:
      <?xml-stylesheet type="text/xsl" href="foo.xsl"?>
    2. Message Environment Selection Priority, which therefore has a default value of 2. The node searches the LocalEnvironment associated with the current message for the stylesheet information stored in an element called ComIbmXslXmltStylesheetname.

      Because this node was available in a SupportPac for Version 2.1, and element ComIbmXslMqsiStylesheetname was used for the name of the style sheet, the current node checks both elements. If both are present, the value in ComIbmXslXmltStylesheetname takes precedence.

    3. Broker Node Attribute Selection Priority, which therefore has a default value of 3. The node uses the node properties Stylesheet Name and Stylesheet Directory to determine the correct values.

    You can set more than one property to the same value, although this is not recommended. If you do, the order of priority set by the node is the default order indicated above.

    If you set a value of ignore, the node does not search the corresponding location for the stylesheet identification. If you set all three properties to ignore, a runtime error is generated.

  2. Start of change

    If you want to specify a non-deployed style sheet using node properties, enter the required value for Stylesheet Name. This value is ignored if stylesheet information is searched for and found in a preferred location (determined by the selection priority values that you have set).

    If you want to specify a principal style sheet, there are two ways of doing this:
    1. Using the Browse button near the Stylesheet Name property field from the workspace. The identified principal style sheet and all its relatively referenced descendant style sheets are automatically added to the bar file when adding a message flow to a .bar file (as long as both they and their parent style sheets are available).
    2. For the identification of an already deployed or to be deployed style sheet, only the Stylesheet Name property can be used, and the Stylesheet Directory property must be left empty.
    End of change
  3. If the stylesheet identification is fully qualified, Stylesheet Directory is ignored; if it is not, the value that you set in this property is added to the beginning of the specification, regardless of where it is found.
  4. In Stylesheet Cache Level, specify the number of compiled or parsed stylesheets that are stored in this instance of the node. The default value is 5. The stylesheet cache is retained for the life of the node. It is cleared when the node is deleted from the flow, or when the flow is deleted, or when the execution group is stopped. If you modify a style sheet, the modified (latest) version is used in preference to the cached version. If you want to refresh the cache, use the mqsireload command.
  5. Select Output Character Set in the properties dialog navigator to specify the order in which the node searches valid locations to find the character set to use for the output message. The highest priority setting is 1. The default order is:
    1. Message Environment Selection Priority, which therefore has a default value of 1. The node searches the LocalEnvironment associated with the current message for the character set information stored in an element called ComIbmXslXmltOutputcharset.

      For example, to encode the output of the transformation as UTF-8, enter the value 1208 as a string in this element.

      Because this node was available in a SupportPac for Version 2.1, and element ComIbmXslMqsiOutputcharset was used for the output character set, the current node checks both elements. If both are present, the value in ComIbmXslXmltOutputcharset takes precedence.

    2. Broker Node Attribute Selection Priority, which therefore has a default value of 2. The node uses the property Output Character Set to determine the correct value.

      If you set a value for Output Character Set, the value that you enter must be numeric. For example, to encode the output of the transformation as UTF-16, enter 1200.

    You can set more than one property to the same value, although this is not recommended. If you do, the order of priority set by the node is the default order indicated above.

    If you set a value of 0, the node does not search the corresponding location for the character set identification.

    If the node cannot determine the output character set from either of these two sources, either because no value is set or because the selection priorities are set to 0, the default value 1208 (UTF8) is used. (The XSL specification indicates that the output character set can be specified in the style sheet; however, the XMLTransformation node ignores this value.)

  6. Select Detail Trace in the properties dialog navigator to trace the actions of the XMLTransformation node. The default value for the Detail Trace property is Off. To activate trace, set the property to On.

    The trace information is written to a trace file XMLTTrace.log:

    • On z/OS systems, the file is located in <broker_dir>/output, where <broker_dir> is the directory in which you have installed the broker
    • On Windows systems, the file is located in <install_dir>\bin
    • On UNIX systems, the file is located in the directory in which your message broker has been started.

    where <install_dir> is the directory in which you have installed WebSphere Business Integration Message Broker.

    If you set detailed trace on for one XMLTransformation node, it is on for all nodes in the execution group.

  7. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  8. Click Apply to make the changes to the XMLTransformation node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Start of changeIf you are dealing with large XML messages and receive an 'out of memory' error, you can use the mqsireportproperties command to see the current value of the Java Heap size for the XSLT engine, and the mqsichangeproperties command to increase it:
mqsireportproperties brokerName -e executionGroupLabel -o ComIbmJVMManager -n jvmMaxHeapSize
mqsichangeproperties brokerName -e executionGroupLabel -o ComIbmJVMManager -n jvmMaxHeapSize -v newSize
replacing brokerName, executionGroupLabel, and newSize with the appropriate values.

The value that you should choose for newSize is dependent upon the amount of physical memory that your computer has and how much you are using Java. A value in the range 512 MB to 1 GB is suggested.

End of change

Terminals and properties

The XMLTransformation node terminals are described in the following table.

Terminal Description
In The input terminal that accepts the message for processing by the node.
Failure The output terminal to which the original message is routed if an error is detected during transformation.
Out The output terminal to which the successfully transformed message is routed.

The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog if you must enter a value when no default is defined), the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The XMLTransformation node Stylesheet properties are described in the following table.

Property M C Default Description
XML Embedded Selection Priority Yes No 1 The priority value for searching for stylesheet location information in the XML data.
Message Environment Selection Priority Yes No 2 The priority value for searching for stylesheet location information in the LocalEnvironment folder of the current message.
Broker Node Attribute Selection Priority Yes No 3 The priority value for searching for stylesheet location information as a property of the node
Stylesheet Name No Yes   The name of the style sheet, used if the stylesheet specification is searched for in node properties.
Stylesheet Directory No Yes   The path where the style sheet is located. Used by all location methods.
Stylesheet Cache Level No No 5 The number of compiled or parsed stylesheets that are stored in this instance of the node.

The XMLTransformation node Output Character Set properties are described in the following table.

Property M C Default Description
Message Environment Selection Priority Yes No 1 The priority value for searching for the Output Character Set ID in the LocalEnvironment folder of the current message.
Broker Node Attribute Selection Priority Yes No 2 The priority value for searching for the Output Character Set ID as a property of the node.
Output Character Set No No   The numeric value of the Output Character Set

The XMLTransformation node Detail Trace properties are described in the following table.

Property M C Default Description
Trace Setting Yes No Off Whether tracing is on or off. If tracing is on, low level tracing is recorded in a file.

The XMLTransformation node Description properties are described in the following table.

Property M C Default Description
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.
Start of change

Deployment of deployed style sheets or XML files

In order to use deployed style sheets or XML files, you must do the following:
  1. Make sure the files have the correct file name extensions: Style sheets to be deployed must have either .xsl or .xslt as their file extension and XML files to be deployed must have .xml as their file extension.
  2. Import the files into the Eclipse workspace: All style sheets and XML files that are to be deployed must be imported into an Eclipse workspace project. Location dependent descendant style sheets or XML files that are to be deployed must be placed in the correct directory structure relative to their parent style sheets. You should not put in the Eclipse workspace Location dependent descendants that you do not want to deploy.
  3. Make sure all references to the files are relative: Generally speaking, all references to a principal style sheet that can appear in a flow's local environment, in an input XML document, in the XMLTransformation node Stylesheet Name property, or in a parent style sheet, must be made relative. A reference to a principal style sheet should be made relative to the root of the relevant Eclipse workspace project. For example, a reference to a principal style sheet in the Eclipse workspace, C:\\project1\a\b.xsl must be specified as a/b.xsl (or ./a/b.xsl). The only exception is, when you specify a principal style sheet as the Stylesheet Name property on an XMLTransformation node, you can also use an absolute path that points to the correct directory structure in the Eclipse workspace. If the principal style sheet is found, the system automatically resets the node property to the correct relative value (and performs an automatic deployment of the principal style sheet, together with all its location dependent descendant style sheets that are available in the relevant Eclipse workspace project). All references to the location dependent descendant style sheets (or XML files) of a principal style sheet must be made relative to the location of their parent style sheets. For example, if style sheet, //project1/a/b.xsl references style sheet, //project1/a/c/d.xsl the reference must be changed to c/d.xsl (or ./c/d.xsl).
  4. Deal with non-deployed child style sheets or XML files: If you have a relatively referenced child style sheet (or XML file) that is not to be deployed yet its parent is, make sure it is placed in the right place under /XSL/external (/XML/external). A broker automatically associates the execution group deployed storage tree, /XSL/external, and /XML/external tree, together. That means, for example, that the broker automatically performs a search in /XML/external/a/b directory for a reference of document (b/c.xml) in the deployed principal style sheet a/style.xsl if b/c.xml is not found in the broker’s deployed storage. Relative path references must also be used for files that are known to have been deployed but which are not available in the workspace.
  5. Deploy the files: You only need to manually deploy style sheets or XML files that are not picked up by the system (the tooling provides warnings about these files). To manually deploy, add the files to be deployed to a broker archive (refer to Adding files to a broker archive) and deploy the broker archive. You need only deploy a style sheet or XML file once for all message flows that belong to the same execution group and at least once for each execution group. It is not necessary to deploy style sheets or XML files in the same .bar file which contains the flows referencing them. Also, style sheets and XML files in a .bar file do not have to be referenced by any flows. However, when a flow is saved to a .bar file, warnings are given if any child style sheets or XML files are not found in the .bar file. It is your responsibility to ensure that these child style sheets or XML files are available on the broker. A broker is not Eclipse-project aware. Therefore, a deployed style sheet that belongs to one project can be overwritten by another if they share the same directory path and file name, even if they belonged to different projects. A deployment overwrites, without warning, all existing old versions of the files that are being deployed. This applies to automatically deployed style sheets as well.
End of change
Related reference
mqsireload command
Compute node