SPE Transform node

Use the SPE Transform node in IBM Integration Bus message flows when you want to transform documents.

This topic contains the following sections:
  • Purpose
  • Using this node in a message flow
  • Terminals
  • Properties
  • Local environment data

Purpose

The SPE Transform node uses the SPE transform() function to transform a document. It supports any of the map types currently supported by SPE: WTX, SI, or XSLT.

The SPE Transform node is contained in the Standards Processing Engine section of the IBM® Integration Toolkit palette.

Using this node in a message flow

Look at the SPE Transform sample to see how to use this node.

Terminals

Terminals used by the SPE Transform node are described in the following table.

Restriction: Dynamic output terminals are not supported for this node.
Table 1. SPE Transform node input and output terminals
Terminal type Terminal Description
Input In

The input terminal. This terminal handles single inputs and collections.

If the input is a single input, it is passed to SPE with the resource name PrimaryDocument.

Restriction: The input terminal can be used for WTX maps if the only data to be passed in is the data for the first input card. In this case, the PrimaryDocument is used as the first input card.

If the input is a collection, each input is passed to SPE with the resource name specified in the collection.

For SI and XSLT map types, only the input named PrimaryDocument is used, and others are ignored.

For WTX maps, each input card to be overridden should be passed with a resource name that matches the card name in the map. For example, to override an input card named MyInputData, include a document named MyInputData in the collection. Not all input cards need to be overridden. The resource name PrimaryDocument can be used in place of the first input card for WTX maps.

Output Out1 The output terminal. The single output for SI and XSLT map types, or the first output card for WTX maps.
Note: For WTX maps, if you do not want to override the first output card, leave this terminal unattached.
Failure The Failure terminal. If Standards Processing Engine throws an exception or returns a nonzero status, the failing input message is propagated to this terminal with the corresponding status and report information.
Dynamic output terminals

For WTX maps, the user creates dynamic output terminals named out2, out3 ...outn. For each output terminal that is defined and attached, the output from the corresponding output card in the WTX map is written to the terminal.

For example, if the dynamic terminals out1, out3, and out5 are defined and attached, the node writes the output from the WTX output cards 1, 3, and 5 to those terminals. Output from other cards such as 2 or 4 is not overridden and is handled based on the map settings.

Restriction: Dynamic output terminals are not used for SI or XSLT maps, as they do not support multiple output cards.

Properties

The Transform node takes the properties described in this section.

The SPE Transform node Description properties are described in the following table:
Table 2. SPE Transform node Description properties
Property Mandatory property? Description
Node name Yes The name of the node. Default is Transform.
Short description No A brief description of the node.
Long description No Text that describes the purpose of the node in the message flow.
The SPE Transform node Basic properties are described in the following table.
Table 3. SPE Transform node Basic properties
Property Mandatory property? Default Description
Map Name No  

The name of the map to be run.

If this is specified, the map and map type are read from the SPE database. You may also specify a dynamic map, as described in the Local Environment section.

The SPE Transform node Advanced properties are described in the following table.
Table 4. SPE Transform node Advanced properties
Property Mandatory property? Default Description
Payload Threshold No 1000 (kb) Specifies the threshold (in kb) at which output data will be passed as a storage ID rather than inline:
  • If the threshold is 0, or the data length is greater than the threshold, the data is passed as a file. The file is identified by the StorageID value in the local environment of the output message.
  • If the length of the data is less than the Payload Threshold value, the data is passed as the message body.

Local environment data

Standards Processing Engine takes some of its input data for input documents and envelope trigger messages from the local environment.

For a dynamic map, map type is determined by examining the first bytes of the map. For maps read from the repository, the map type is included in the repository information.

For input documents, the following input (if specified) is read from the local environment and used in processing:
SPE.MapName
The name of the map to use. If specified, SPE.MapName overrides the Map Name property for the node.

If DynamicMap is also set, this assigns a name to the dynamic map. If DynamicMap is not set, SPE.MapName must specify a map that is in the SPE repository.

SPE.MapServerLocation
The filename (with full path) of a map to use as a dynamic map. If specified, SPE.MapServerLocation overrides the Map Name property for the node.
Restriction: SPE.MapServerLocation may not be specified with either MapName or DynamicMap.
SPE.DocumentType
The document type returned byStandards Processing Engine for this data.

Valid values: UNASSIGNED, INPUT, INTERMEDIATE, and FINAL

SPE.DynamicMap
A byte array containing the dynamic map. If specified, this overrides the Map Name property for the node.
SPE.StorageID

A string that specifies the filename containing the input data. If SPE.StorageID is not specified, then the message body is interpreted as the data.

Message collections: For message collections, the filename specified by SPE.StorageID is ignored since the one local environment applies to all messages in the collection.
Dynamic map type: The map type is determined for a dynamic map by examining the first bytes of the map. For maps read from the SPE repository, the map type is included in the repository information.

Local environment data is used with output as follows:

The local environment from the input message (or from the first input message of a collection) is copied to all output messages.

For output messages where the data length is greater than the specified Payload Threshold, the following are included in the local environment:

SPE.StorageID
A string that specifies the filename containing the output data. If not specified, then the output data is in the message body.
Note: This is not copied from the input message

The following are copied from the translation response to the local environment, and included with all messages propagated to the output or error terminals:

SPE.Correlations
The correlations returned with the response.
SPE.ProcessData
The process data returned with the response.
SPE.DocumentName
The document name returned by SPE for this data.
SPE.Status
The status returned from the SPE call:
  • The value 0 indicates success.
  • Anything other value indicates an error.
SPE.AdvancedStatus
If an error occurred, this contains a short text message to describe the error. Otherwise, it is omitted.
SPE.StatusReport
If an error occurs, the status report is added to the local environment. Otherwise, this is omitted.