XSLTransform node

Use the XSLTransform node to transform an XML message to another form of message, according to the rules provided by an XSL (Extensible Stylesheet Language) style sheet, and to set the Message domain, Message model, Message, and PHysical format for the generated message.

The XSLTransform node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale

For more information, see Operation modes.

This node was formerly known as the XMLTransformation node.

This topic contains the following sections:

Purpose

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

Use the content of the XML data within the message itself to transform the message according to a style sheet that the message itself defines.
Set a value in the LocalEnvironment folder. You must set this value in a node that precedes the XSLTransform node (for example, a Compute node). 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.
Use node properties to ensure that the transformation that is defined by this single style sheet is applied to every message that is processed by this node.

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 zero. If the XSLT is cached, the performance is improved because the XSLT is not parsed every time it is used.

If the prologue of the input message body contains an XML encoding declaration, the XSLTransform node ignores the encoding, and always uses the CodedCharSetId in the message property folder to decode the message.

The XSLTransform node is contained in the Transformation drawer of the palette, and is represented in the IBM® Integration Toolkit 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 that is 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.

You cannot use relative path external entities that are defined in the DTD of input messages (for example, <!DOCTYPE note [<!ENTITY chap1 SYSTEM "chap1.xml">]>). Use an absolute path definition.

The XSLTransform node supports a number of local environment message tree variables, which you can use to dynamically alter the values that are set in the node's properties. For more details, see Using local environment variables to set properties.

You can use style sheets in two different ways with the XSLTransform node. For more details, see Deployed and non-deployed style sheets.

If you have large XML messages and receive an out of memory error, use the mqsireportproperties command to see the current value of the Java™ Heap size for the XSLT engine:

mqsireportproperties integrationNodeName -e integrationServerName 
                                 -o ComIbmJVMManager -n jvmMaxHeapSize

Use the mqsichangeproperties command to increase the Java Heap size:

mqsichangeproperties integrationNodeName -e integrationServerName 
                                 -o ComIbmJVMManager -n jvmMaxHeapSize -v newSize

In the previous examples, replace integrationNodeName, integrationServerName, and newSize with the integration node name, integration server name, and the size wanted for the Java Heap.

The value that you choose for newSize depends on the amount of physical memory that your computer has, and how much you are using Java. A value in the range 512 MB (536870912) to 1 GB (1073741824) is typically sufficient.

Configuring the XSLTransform node

When you have put an instance of the XSLTransform node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view.

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

Terminals and properties

The XSLTransform 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 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 XSLTransform node Description properties are described in the following table.

Property	M	C	Default	Description
Node name	No	No	The node type	The name of the node.
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.

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

Property	M	C	Default	Description	mqsiapplybaroverride command property
Stylesheet name	No	Yes		The name of the style sheet, which is used if the style sheet specification is searched for in node properties. To specify a style sheet by using node properties, enter the required value for Stylesheet name. Specify a principal style sheet using one of the following methods: Click Browse next to Stylesheet name. The identified principal style sheet and all its relatively-referenced descendant style sheets are added automatically to the BAR file when you add a message flow to a BAR file (if both they and their parent style sheets are available). To identify an already deployed, or ready to be deployed, style sheet, use the Stylesheet name property, and leave the Stylesheet directory property blank. In the Message Flow editor, drag an .xslt file onto the XSLTransform node; the Stylesheet name is set automatically.	stylesheetName

The XSLTransform node Advanced properties are described in the following table.

Property	M	C	Default	Description	mqsiapplybaroverride command property
Stylesheet directory	No	Yes		The path where the style sheet is located. This path is used by all location methods. If the style sheet identification is fully qualified, the Stylesheet directory property is ignored; otherwise, the value that you set in this property is added to the beginning of the specification, regardless of where it is found.	stylesheetPath
Stylesheet cache level	No	No	5	The number of compiled or parsed style sheets that are stored in this instance of the node. Enter a positive integer between zero (0) and 100. The default value is 5. If you set this property to zero (0), no style sheet is cached, and style sheets are interpreted rather than compiled. If your message flow does not set the style sheet dynamically by using the local environment, the same style sheet is always used, and any value greater than zero ensures that it is compiled. If your message flow does set the style sheet dynamically, you can tune the value to improve performance. If you set this property to a character other than a positive integer, a flow configuration exception error message is issued. The style sheet cache is retained for the life of the node, and is cleared when the node is deleted from the flow, when the flow is deleted, or when the integration server is stopped. If you change a cached style sheet (by redeploying or replacing the file in the file system), the XSLTransform node that is holding the cache replaces the cached version with the modified (latest) version before a new message is processed. If a deployed style sheet is redeployed, or an external style sheet is replaced in the file system, the update is detected but you cannot replace a style sheet that is deployed in a BAR file by changing the deployed style sheet on disk. To change a style sheet that is deployed in a BAR file, you must redeploy the BAR file. If you are changing several style sheets, stop the relevant message flows before you make any changes. If you do not stop the relevant message flows before you make the changes, the order of the changes cannot be guaranteed by running message flows, which might cause an incompatibility between the style sheets that are changed. Use the mqsireload command to reload a style sheet; however, this command does not prevent incompatibility. Consider performance when you set this property. Typically, when you set this property to a number greater than the default value of 5, performance is faster because style sheet re-compilation is less likely. However, cached style sheets use Java virtual machine (JVM) heap space; if you keep too many cached style sheets, the JVM is likely to slow. In addition, if the cached style sheets are not used regularly and you set this property to a large number, performance can be affected because compiling style sheets increases processor usage. Therefore, to decide on the most suitable value for this property, you must balance how many style sheets you use with the size of the style sheets, the size of the JVM heap space, and your usage pattern. For more information about the JVM heap space, see JVM heap sizing.

Property

Default

Description

mqsiapplybaroverride command property

Stylesheet directory

Yes

The path where the style sheet is located. This path is used by all location methods.

If the style sheet identification is fully qualified, the Stylesheet directory property is ignored; otherwise, the value that you set in this property is added to the beginning of the specification, regardless of where it is found.

stylesheetPath

Stylesheet cache level

The number of compiled or parsed style sheets that are stored in this instance of the node.

Enter a positive integer between zero (0) and 100. The default value is 5. If you set this property to zero (0), no style sheet is cached, and style sheets are interpreted rather than compiled. If your message flow does not set the style sheet dynamically by using the local environment, the same style sheet is always used, and any value greater than zero ensures that it is compiled. If your message flow does set the style sheet dynamically, you can tune the value to improve performance. If you set this property to a character other than a positive integer, a flow configuration exception error message is issued.

The style sheet cache is retained for the life of the node, and is cleared when the node is deleted from the flow, when the flow is deleted, or when the integration server is stopped.

If you change a cached style sheet (by redeploying or replacing the file in the file system), the XSLTransform node that is holding the cache replaces the cached version with the modified (latest) version before a new message is processed. If a deployed style sheet is redeployed, or an external style sheet is replaced in the file system, the update is detected but you cannot replace a style sheet that is deployed in a BAR file by changing the deployed style sheet on disk. To change a style sheet that is deployed in a BAR file, you must redeploy the BAR file. If you are changing several style sheets, stop the relevant message flows before you make any changes. If you do not stop the relevant message flows before you make the changes, the order of the changes cannot be guaranteed by running message flows, which might cause an incompatibility between the style sheets that are changed. Use the mqsireload command to reload a style sheet; however, this command does not prevent incompatibility.

Consider performance when you set this property. Typically, when you set this property to a number greater than the default value of 5, performance is faster because style sheet re-compilation is less likely. However, cached style sheets use Java virtual machine (JVM) heap space; if you keep too many cached style sheets, the JVM is likely to slow. In addition, if the cached style sheets are not used regularly and you set this property to a large number, performance can be affected because compiling style sheets increases processor usage. Therefore, to decide on the most suitable value for this property, you must balance how many style sheets you use with the size of the style sheets, the size of the JVM heap space, and your usage pattern. For more information about the JVM heap space, see JVM heap sizing.

The XSLTransform node Output Message Parsing properties are described in the following table.

Property	M	C	Default	Description
Message domain	No	No	BLOB	The message domain that is associated with the output message. To associate a specific parser with the output message, specify the new domain in Message domain. The default value is BLOB. This domain is applied to the output message. Alternatively, use Inherit to associate the parser that owned the input message. XML is deprecated; use XMLNSC instead. You can also specify a user-defined parser if appropriate.
Message model	No	No		The name or location of the message model schema file in which the message is defined. If you are using the XMLNSC parser in validating mode, or the MRM parser, select the Message model that you want to use. When you click Browse, you see a list of available message models schema files when you select XMLNSC or MRM as the domain. If you set this property, then subsequently update the project dependencies to remove this message model reference, a warning is issued. Either update the Message model property, or restore the reference to this message model.
Message	No	No		The message type that is associated with the output message. If you are using the MRM parser, select the correct message from the list in Message. This list is populated with messages that are defined in the Message model that you have selected.
Physical format	No	No		The message format that is associated with the output message. If you are using the MRM parser, select the XML physical format for the output message from the list in Physical format. This list includes all the physical formats that you have defined for this Message model.
Character set	No	No		The numeric value of the character set for the output message. To specify a character set for the output message by using node properties, specify the required value for Character set. The value that you specify must be numeric; for example, specify 1200 to encode the output message as UTF-16.

The XSLTransform node Parser Options are described in the following table.

Property	M	C	Default	Description
Parse timing	No	No	On Demand	This property controls when an output message is parsed. Valid values are On Demand, Immediate, and Complete. Parse timing is, by default, set to On Demand, which causes parsing of the message to be delayed. To cause the message to be parsed immediately, see Parsing on demand.
Build tree using XML schema data types	No	No	Cleared	This property controls whether the XMLNSC parser creates syntax elements in the message tree with data types taken from the XML Schema. You can select this property only if you set the Validate property to Content or Content and Value. For more information, see Manipulating messages in the XMLNSC domain.
Use XMLNSC compact parser for XMLNS domain	No	No	No	This property controls whether the XMLNSC Compact Parser is used for output messages in the XMLNS Domain. If you set this property, the message data appears under XMLNSC in nodes that are connected to the output terminal when the input MQRFH2 header or Domain is XMLNS.

The XSLTransform node Validation properties are described in the following table. Set the validation properties for the parser to validate the body of messages against the Message set. (If a message is propagated to the Failure terminal of the node, it is not validated.) For more details, see Validating messages and Validation properties.

Property	M	C	Default	Description
Validate	No	Yes	None	This property controls whether validation takes place of the output message. Valid values are None, Content, Content and Value, and Inherit.
Failure action	No	No	Exception	This property controls what happens if validation of the output message fails. You can set this property only if you set Validate to Content and Value or Content. Valid values are User Trace, Local Error Log, Exception, and Exception List.

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

Property	M	C	Default	Description
Trace setting	Yes	No	Off	This property is deprecated. Start user trace instead. The user trace contains the same XSL trace information. If you set this property, it does not affect user trace. In previous versions of WebSphere® Message Broker, this property controls whether tracing is on or off. If tracing is on, low level tracing is recorded in a file.

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.