SPE Enveloping service

The SPE Enveloping service applies a standard-specific envelope to the transaction set messages that it receives as input.

In addition, Sterling B2B Integrator users can pass any parameters into SPE, and therefore benefit from the Sterling B2B Integrator visibility functionality. This visibility functionality includes information on what SPE is attempting to do (envelope, deenvelope, transform, or run a driver), and whether the action succeeded or failed. Also, every event includes tracking information that can be passed in by the application that hosts SPE.

Category	Description
Service name	SPE Enveloping Service
Type	Service. Implementation type: Java™ class.
System name	User supplied.
Graphical Process Modeler (GPM) categories	All Services
Description	The SPE Enveloping Service applies a standard-specific envelope to the transaction set messages that it receives as input. Use of the service requires that supporting resources such as envelopes and maps are loaded into SPE. Enveloping can be done in immediate or in deferred mode: Immediate mode Immediate mode takes input documents, encodes the data, and envelopes it. Deferred mode Deferred enveloping takes place in 2 steps. The first step is the same as enveloping in immediate mode: the service takes input documents, encodes the data, and stores it in the database. The second step takes the documents that were encoded (without passing them as input) and envelopes them. This step can be filtered by senderID, receiverID, or AccepterLookupAlias.
Business usage	Allows Sterling B2B Integrator users to run EDIFACT, X12, and HIPAA enveloping operations by using SPE, whose translator strongly supports WebSphere® Transformation Extender maps and provides HIPAA support.
Usage example	A Sterling B2B Integrator customer wants to process healthcare data. They purchase SPE for its HIPAA support and use the SPE Enveloping service to perform HIPAA enveloping by using their existing SPE business processes.
Pre-configured?	No
Requires third-party files?	The database driver for the SPE database is required if the default Derby database is not used. Other required third-party files are obtained from the SPE installation during the installation and integration process.
Platform availability	Available on platforms that are supported by both SPE and Sterling B2B Integrator. See detailed system requirements at http://www-947.ibm.com/support/entry/portal/.
Related services	None.
Application requirements	Installation and setup of SPE and integration with SPE. WebSphere Transformation Extender is required to use the WebSphere Transformation Extender map type.
Initiates business processes?	Yes, SPE can call back into Sterling B2B Integrator and start business processes if configured to do so. This initiation is set in the business process.
Invocation	Event driven. You explicitly start the SPE Enveloping Service in a business process and it proceeds to run one enveloping operation.
Business process context considerations	An input document can be the primary document, or a document in the process data document tree under DOC/DOC-1, DOC/DOC-2...DOC/DOC-`n`. An output document is put in process data under the name INT-1, INT-2,...INT-`n`. If there is a translation error, it goes to the translation report.
Returned status values	Status is on a per-document basis. Success Enveloping completed with no errors. Error One or more errors occurred during the enveloping process. Whether the enveloping process completes depends upon the setting for the HaltOnTransError parameter.
Restrictions	None
Persistence level	System default
Testing considerations	Logs from SPE appear in these locations: In speservices.log As separate log files in your `SI_INSTALL`/logs directory In the Status Report, unless turned off with the AppendLogsToStatusReport parameter

Configuration parameters

Set the properties to connect to the SPE database in the spe_install_dir/dbprops.cfg file.

Parameters passed from business process to service

Parameter name (display name)	Element value (BPML)	Type	Description	Possible values	Configure in GPM or in UI?	Default value	Required or optional?
Mode	Mode	String	Enveloping mode	IMMEDIATE DEFERRED	GPM	None; it must be set each time.	Required
SenderId	SenderId	String	The sender ID that is used to look up the envelope.	User specified	GPM	None	Optional
AccepterLook upAlias	AccepterLook upAlias	String	The accepter lookup alias that is used to look up the envelope.	User specified	GPM	None	Optional
InterchangeId	InterchangeId	String	Used to filter documents that are selected for deferred enveloping.	See Specifying the InterchangeId for deferred enveloping.	GPM	None	Optional
Type	Type	String	The standard to use to envelope the data.	X12 EDIFACT HIPAA	GPM	None. Values depend on which SPEpacks are installed.	Optional
HaltOnTrans Error	HaltOnTrans Error	Boolean	Whether processing continues after a translation error.	True Processing stops after the encoding process if an error occurs. False Processing proceeds after error.	GPM	False	Optional
OutputReport To Process Data	OutputReport ToProcess Data	Boolean	Whether a translation report is output to process data in the case of an unsuccessful translation.	True Translation report is output to process data. No translation report is output to process data if translation is successful. False Translation report is output to the status report.	GPM	False	Optional
DeferredEncode	DeferredEncode	Boolean	In DEFERRED enveloping mode only, whether the encode step of the deferred enveloping process is run.	True Encode step of the deferred enveloping process if run. False Encode step is not run.	GPM	False	Optional
AppendLogsToStatusReport	AppendLogsToStatusReport	string	Whether to append the SPE logs to the status report.	True SPE logs are appended to the status report. If debug is off and the process runs successfully, there are generally no logs. False Turns off the appending of SPElogs to the status report.	GPM	True	Optional
PersistIntermediateDoc	PersistIntermediateDoc	String	Whether to persist intermediate document	True Persist intermediate document for correlation tracking. False Do not persist intermediate documents. Improves performance.	GPM Note on precedence: Business process setting in GPM overrides the global value, if one is set in SPE.properties for this property.	False	Optional

Specifying the InterchangeId for deferred enveloping

Deferred enveloping takes place in two steps:

The service takes input documents, encodes the data, and stores it in the database. (This is the same as enveloping in immediate mode.)
The documents that were encoded in step 1 are taken (without passing them as input) and enveloped. This step can be filtered by senderID, receiverID, or AccepterLookupAlias.

If the InterchangeId is specified for deferred enveloping, only documents that are encoded with the matching InterchangeId are selected. Example: You specify the following InterchangeID in step 2 of the deferred enveloping process:

<assign to="InterchangeID">XYZ</assign>

SPE then only selects documents where the matching InterchangeId is also specified when encoding the documents for deferred enveloping (step 1).

Parameters passed from service to business process

None.

Business process example: IMMEDIATE enveloping mode

In IMMEDIATE enveloping mode, one business process encodes and envelopes the document. This sample business process is used for IMMEDIATE mode:

<process name="SPEtestenv">
  <operation name="Spetest">
     <participant name="SPEEnveloping"/>
           <output message="SPEEnvInputMessage">
        	    <assign to="." from="*"></assign>
         	  <assign to="Mode">IMMEDIATE</assign>
         	  <assign to="SenderId">PETTEST3</assign>
         	  <assign to="ReceiverId">PETTEST3</assign>
         	  <assign to="AccepterLookupAlias">810</assign>
     <assign to="OutputReportToProcessData">true</assign>
          </output>
          <input message="inmsg">
              	 <assign to="." from="*"></assign>
          </input>
   </operation>
</process>

Business process example: DEFERRED enveloping mode

In DEFERRED enveloping mode, two business processes are required, one to submit the documents for encoding and another to finalize the process and envelope the submitted documents.

This sample business process is used for DEFERRED enveloping mode, step 1:

<process name="SPEtestenv">
  <operation name="Spetest">
     <participant name="SPEEnveloping"/>
           <output message="SPEEnvInputMessage">
        	    <assign to="." from="*"></assign>
         	  <assign to="Mode">DEFERRED</assign>
         	  <assign to="SenderId">PETTEST3</assign>
         	  <assign to="ReceiverId">PETTEST3</assign>
         	  <assign to="AccepterLookupAlias">810</assign>
             <assign to="OutputReportToProcessData">true</assign>
             <assign to="DeferredEncode>true</assign>
           </output>
           <input message="inmsg">
             <assign to="." from="*"></assign>
           </input>
   </operation>
</process>

This sample business process for DEFERRED enveloping mode illustrates step 2:

<process name="SPEtestenv">
  <operation name="Spetest">
     <participant name="SPEEnveloping"/>
           <output message="SPEEnvInputMessage">
        	    <assign to="." from="*"></assign>
         	  <assign to="Mode">DEFERRED</assign>
     <assign to="OutputReportToProcessData">true</assign>
          </output>
          <input message="inmsg">
              	 <assign to="." from="*"></assign>
          </input>
   </operation>
</process>

Business process example: passing parameters

In addition to the parameters previously defined, the SPEContextParms.name=value is the mechanism by which Sterling B2B Integrator users can pass any parameters into SPE.

This sample business process is used to add process data parameters in a name/value comma delimited string named SPEContextParms.

<process name="SPEEnvelopeX12">
 <operation name="EnvelopeX12">
  <participant name="SPEEnvelopingService"/>
   <output message="SPEEnvInputMessage">
         <assign to="." from="*"></assign>
         <assign to="Mode">IMMEDIATE</assign>
         <assign to="Type">X12</assign>
         <assign to="SenderId">PETTEST3</assign>
         <assign to="ReceiverId">PETTEST3</assign>
         <assign to="AccepterLookupAlias">810</assign>
         <assign to="EncodeInSPE">true</assign>
         <assign to="OutputReportToProcessData">true</assign>
         <assign to="SPEContextParms.Boston">Bruins</assign>
         <assign to="SPEContextParms.Philadelphia">Phillies</assign>
         <assign to="SPEContextParms.Columbus">Blue_Jackets</assign>
         <assign to="SPEContextParms.Detroit">Red_Wings</assign>
       </output>
       <input message="inmsg">
         <assign to="." from="*"></assign>
       </input>
  </operation>
</process></p>

In this way, these options get added as strings the SPEOptions map and passed into the SPE methods (envelope, de-envelope, and transform).

Boston->Bruins
Philadelphia->Phillies
Columbus->Blue_Jackets
Detroit->Red_Wings

XPathToCopyPDToSPE service parameter

This service parameter assigns the xpath that is used to select all or part of the process data tree in Sterling B2B Integrator and copy it into the SPE service. The XML fragment is then parsed and stored into the SPE process data tree. For example:

To select the entire process data tree in Sterling B2B Integrator, use one of these xpaths.

<assign to="XPathToCopyPDToSPE">/*</assign>

<assign to="XPathToCopyPDToSPE">/ProcessData</assign>

To select all elements under a specific element in the process data tree, use one of these xpaths.

<assign to="XPathToCopyPDToSPE">/ProcessData/SubElementName/*</assign>

<assign to="XPathToCopyPDToSPE">/ProcessData/SubElementName1/SubElementName2/*</assign>

The Process Data tree elements returned by SPE are not automatically copied to the Sterling B2B Integrator Process Data tree. To copy all of the process data elements from SPE into the B2Bi process data tree, use the CopyPDFromSPEToElement option.

CopyPDFromSPEToElement service parameter

This service parameter takes the process data tree returned from SPE and copies it into a subelement in the process data tree in Sterling B2B Integrator. This step is necessary to avoid duplicates that may occur if the contents of the SPE process data tree is copied to the root of the Sterling B2B Integrator process data tree. For example:

<assign to="CopyPDFromSPEToElement">SPE1</assign>