SPE Transformation service

The SPE Transformation service takes document input from the primary document and uses a provided map to transform the document into another format.

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, de-envelope, 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 Transformation Service
Type	Service. Implementation type: Java™ class.
System name	User supplied.
Graphical Process Modeler (GPM) categories	All Services
Description	The SPE Transformation Service uses a provided map to transform an input document into another format. Use of the service requires that maps are loaded into SPE.
Business usage	Allows Sterling B2B Integrator users to process documents by using SPE, whose translation capability support includes 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 Transformation Service to translate HIPAA documents, and utilize their existing Sterling B2B Integrator 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 Sterling B2B Integration. WebSphere Transformation Extender is required to use the WTX map type.
Initiates business processes?	No
Invocation	Event driven. You explicitly start it in the business process.
Business process context considerations	Input documents can be the primary document, or documents in the process data document tree under DOC/DOC-1, DOC/DOC-2...DOC/DOC-`n`. The input document can also be null if the map is a Sterling B2B Integration map and the input side is SQL. When maps of type WTX are used, input documents need to be named with a specific syntax in order to override WebSphere Transformation Extender input cards. Name documents in1, in2, ..in`n` in order to override those input cards. The first output document replaces the primary document. All other documents are returned as `Translated-1, Translated-2, ...Translated-n`. In other words, Output terminal 1 becomes Primary Document, Output terminal 2 becomes `Translated-1`, Output terminal 3 becomes `Translated-2`, and so on. If there is a translation error, it goes to the translation report. Any translation reports are sent to status and are logged. The translation report is returned in the same way as when the Sterling B2B Integration Translation service is executed.
Returned Status Values	Status is on a per-document basis. Success Transformation completed with no errors. Error One or more errors occurred during the transformation process.
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 SPE 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?
Maptype	MapType	string	Type of map that is being used for document processing.	SI WTX XSLT If a map of the WTX type is used, see also the Number Of Output Cards parameter and the "Business process context considerations" entry.	GPM	None	Required if MapServerLocation or DynamicMap are used.
Mapname	MapName	string	Name of a map that is in the SPE database. One of three methods that are used to provide a map for use with this service.	User specified.	GPM	None	Required unless MapServerLocation or DynamicMap is specified. If you include one of those parameters, do not use MapName.
Mapserverlocation	MapServerLocation	string	The server location of a map. One of three methods that is used to provide a map for use with this service.	User specified.	GPM	None	Required unless or MapName or DynamicMap is specified. If you include one of those parameters, do not use MapServerLocation.
DynamicMap	DynamicMap	string	The map object in base 64 encoded, passed in the business process. One of three methods that are used to provide a map for use with this service.	User specified.	GPM	None	Required unless MapName or MapServerLocation is specified. If you include one of those parameters, do not use DynamicMap. For large WTX maps, use MapName or MapServerLocation as service parameters instead of DynamicMap.
NumberOfOutputCards	NumberOfOutputCards	string	The number of output cards to override when a map of type WTX is used. The service overrides cards 1 through the number specified.	An integer `n` where the value of `n` depends on the map.	GPM	None	Required if you are using a map of type WTX, in order to override any SPE output cards. Not used with other map types.
AppendLogsToStatusReport	AppendLogsToStatusReport		Whether to append the SPE logs to the status report.	True SPElogs 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 SPE logs to the status report.	GPM	True	Optional
PersistIntermediateDoc	PersistIntermediateDoc	String	Whether to persist the intermediate document.	True Persist intermediate document for correlation reporting. 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

Parameters passed from service to business process

None

Business process example

<process name="SPETransformation">
   <operation name="SPETransformationService">
      <participant name="SPETransformation"/>
      <output message="SPEMessage">
         <assign to="." from="*"></assign>
         <assign to="MapServerLocation">/home/user/PET_EINV.txo</assign>
         <assign to="MapType">SI</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="SPETransformX12">
 <operation name="TransformX12">
  <participant name="SPETransformService"/>
   <output message="SPETransInputMessage">
         <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>

WebSphere Transformation Extender map example

<process name="SPETransform_WTX">
  <sequence name="Sequence Start">
    <operation name="SPETransformationType">
      <participant name="SPETransformationService"/>
      <output message="SPETransformationTypeInputMessage">
        <assign to="MapName">hipaa_837i_5010_to_medClaim</assign>
        <assign to="MapType">WTX</assign>
        <assign to="NumberOfOutputCards">1</assign>
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
  </sequence>
  </process>