SPE Envelope node

Use the SPE Envelope node in IBM® Integration Bus message flows to encode and envelope documents.

This node supports the following enveloping modes:
  • Envelope data immediately
  • Prepare data for enveloping, and save it in the database for later enveloping
  • Envelope previously prepared data

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

Purpose

The SPE Envelope node uses the Standards Processing Engine encode() and envelope() functions to envelope a document. The node supports any of the standards that are enabled for your Standards Processing Engine installation.

The SPE Envelope node can be configured to perform either immediate or deferred enveloping. Depending on an enveloping activity property setting, it can envelope data immediately, prepare data and save it in the database for later enveloping, or envelope previously prepared data.

Using this node in a message flow

Look at the following samples to see how to use this node:
  • SPE Enveloping

Terminals

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

Restriction: Dynamic output terminals are not supported for this node.
Table 1. SPE Envelope node input and output terminals

Table containing the terminal type, terminal name, and a description for the input and output terminals of the SPE Envelope node.
Terminal type Terminal Description
Input In

The input terminal. If the enveloping activity is immediate or in preparation for later enveloping, input data is passed to this terminal.

The input terminal handles both single inputs and collections. If a collection is passed, input transactions are enveloped together (where applicable) in the same interchange.

If the activity is to envelope previously prepared documents, then the local environment of the message is used to identify which documents to envelope. The body of the message is ignored.
Output Out The output terminal to which data is routed when processing is completed. All output documents not identified by SPE as errors are written to this terminal.
Error The error terminal. If SPE returns a nonzero status, the failing input transactions, groups, or interchanges are propagated to this terminal along with corresponding status and report information.
Failure The failure terminal. If SPE throws an exception, the input message is propagated to this terminal.

Local environment data used with input

Standards Processing Engine takes some of its processing information from the local environment.

If the Enveloping Activity property is set to Envelope input immediately or Prepare documents for later enveloping, the following local environment parameters are used. Many of these inputs are used to look up the envelope definition in the trading partner database.

You need to specify only the envelope lookup parameters that are required to uniquely identify the correct envelope to be used in processing the data.

SPE.DocumentType
The document type returned byStandards Processing Engine for this data.

Valid values: UNASSIGNED, INPUT, INTERMEDIATE, and FINAL

SPE.EDIStandard
Standard that is used for the message. It is used as part of the envelope lookup.

If you specify SPE.EDIStandard, SPE.EDISenderQual and SPE.ReceiverQual are optional: that is, you can specify SPE.SenderQual, SPE.ReceiverQual, both, or neither.

SPE.SenderID
Sender ID for the message. It is used as part of the envelope lookup.
SPE.SenderQual
Sender ID qualifier for the message. If SPE.EDIStandard and SPE.SenderQual are specified, SPE.SenderQual is used as part of the envelope lookup. SPE.SenderQual can be specified with, or independently of, SPE.ReceiverQual.
SPE.ReceiverID
Receiver ID for the message. It is used as part of the envelope lookup.
SPE.ReceiverQual
Receiver ID qualifier for the message. If SPE.EDIStandard and SPE.ReceiverQual are specified, SPE.ReceiverQual is used as part of the envelope lookup. SPE.ReceiverQual can be specified with, or independently of, SPE.SenderQual.
SPE.AccepterLookupAlias
Accepter Lookup Alias for the message. It is used as part of the envelope lookup.
SPE.InterchangeID
A user-defined identifier for the message. If specified, it can be used later to select only those documents that were prepared with this particular identifier.
SPE.StorageID
A string that specifies the file name that contains the input data. If not specified, the message body is interpreted as the data.

For message collections, this string is ignored since the one local environment applies to all messages in the collection.

If the Enveloping Activity property is set to Envelope previously prepared documents, the following local environment parameters are used to select which of the previously prepared documents to retrieve from the trading partner database.

SPE.SenderID
Sender ID for the message. It is used to select previously prepared documents.
SPE.ReceiverID
Receiver ID for the message. It is used to select previously prepared documents.
SPE.InterchangeID
A user-defined identifier for the message. It can be used to select only those documents that were prepared with this particular identifier.

Local environment data used with output

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 input is included in the local environment:

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

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

SPE.Correlations
The correlations returned with the response.
SPE.ProcessData
Process data that is returned with the response.
SPE.DocumentName
Document name that is returned by SPE for this data.
SPE.Status
The status that is returned from the SPE call:
  • The value 0 indicates success.
  • Any other value than 0 indicates an error.
SPE.AdvancedStatus
If an error occurred, SPE.AdvancedStatus contains a short text message to describe the error. Otherwise, it is omitted.
SPE.TranslationReport
If an error occurs and the data is propagated to the error terminal, the translation report is added to the local environment. Otherwise, this string is omitted.

Properties

The following tables describe the node properties.

The SPE Envelope node Description properties are described in the following table.
Table 2. SPE Envelope node Description properties
Property Mandatory property? Default Description
Node name No The node type The name of the node. Default is Envelope.
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 Envelope node Basic properties are described in the following table.
Table 3. SPE Envelope node Basic properties
Property Mandatory property? Default Description
Enveloping activity Yes Envelope input immediately
Specifies the type of enveloping activity that this node is to perform:
Envelope input immediately (IMMEDIATE or mode 0)
The input is immediately enveloped, and the output is sent to the output terminal.
Prepare documents for later enveloping (DEFERRED or mode 1)

The documents are translated, prepared for later enveloping, and saved in the SPE database.

No enveloped data is sent to the output terminal except for intermediate documents, if requested.

Envelope previously prepared documents (GETDEFERRED or mode 2)
Documents that were previously prepared and held in the database are enveloped and sent to the output terminal. A special trigger message identifies which documents to retrieve and envelope. This action replaces passing input documents to the input terminal.
The SPE Envelope node Advanced properties are described in the following table.
Table 4. SPE Envelope node Advanced properties
Property Mandatory Property? Default Description
Output intermediate documents Yes No Specifies whether intermediate documents are to be sent to the output terminal.
YES
Send all documents, including intermediate documents, to the output terminal.
NO
Send only those documents that are identified as "FINAL” to the output terminals.
Note: FINAL documents can include generated acknowledgments.
Payload Threshold No 1000 KB Specifies the threshold in KB at which output data is 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
Halt on translation error No Yes Specifies whether documents are to be EDI enveloped or not if translation errors occur.
YES
Documents are not enveloped if the translation ended with errors.
NO
Documents are enveloped regardless of any translation errors.
Note: If the property value is YES and translation errors are present, the SPE transaction is rolled back and none of the documents are sent to the out terminal
Draft comment:
Related topics--These will be added and will include MB Information Center topics such as the following.

Related concepts:

Message flows overview,

Related tasks:

Deciding which nodes to use, Configuring transactionality for message flows, Editing configurable properties

Related reference:

None identified at this time.