SOAP Outbound Service
The SOAP Outbound service prepares SOAP requests and responses to be sent. This service might include adding SOAP enveloping to an XML document, creating a SOAP fault message, and adding SOAP header blocks from process data.
The following table provides an overview of the Simple Object Access Protocol (SOAP) Outbound service:
|Graphical Process Modeler (GPM) categories)||All Services, Internet B2B > SOAP|
|Description||SOAP is an XML-based protocol that enables the application to access services, objects, and servers in a platform-independent manner. The SOAP Outbound Service is responsible for preparing SOAP requests and responses to be sent. This may include adding SOAP enveloping to an XML document, creating a SOAP fault message, and adding SOAP header blocks from process data. The resulting document will either be the raw SOAP request or raw SOAP response, and an HTTP Client adapter instance sends the document to the necessary location.|
|Business usage||Prepares SOAP requests and responses.|
|Usage example||See the predefined business process, SendSOAPRequest|
|Preconfigured?||Yes. A configuration of the service called SOAPOutbound is installed with the application. No additional setup is needed.|
|Requires third-party files?||No|
|Platform availability||All supported application platforms|
Note: The HTTP Server adapter and the HTTP Client adapter replace the B2B HTTP Server adapter and HTTP Send service, which has entered the retirement process. For more information, see Monitoring Deprecated (Retired) Resources.
|Initiates business processes?||No|
|Invocation||If this service is used to send a SOAP response, the parameter SOAP_MODE should be set to respond. The default value for this parameter is send.|
|Business process context considerations||None|
|Returned status values|| Returned status values:
|Testing considerations||Use the predefined business process, SendSOAPRequest, to test the service.|
How the SOAP Outbound Service Works
The application determines whether the SOAP Outbound service should be run in send or respond mode. The default mode is send.
- Adds SOAP enveloping, including header blocks, if necessary
- Generates the necessary HTTP headers
- Sets some values to be used by the HTTP Client adapter
- Checks for the presence SOAPFault in process data, and if it exists, uses the SOAP fault data to generate a SOAP fault.
- If there is no fault and the application is not in intermediate mode, it adds SOAP enveloping, including header blocks, to the primary document.
- Generates the HTTP response code header.
The SOAP Outbound service supports two additional, optional parameters: SOAPEnvAttribute and SOAPAddXMLDeclaration. Both can be passed to the service in an XML business process. The parameters are described in the following table:
|Add Custom Attributes to the Envelope Element||You can add custom attributes to the Envelope element in a generated outbound SOAP message. The SOAP Outbound service looks for a parameter called SOAPEnvAttribute. The value of this parameter contains the complete attribute specification (of the form attributeName="attributeValue"). You can use this parameter multiple times with append="true" in the Assign statement.|
|Include an XML Declaration in Generated XML Documents||To include an XML declaration in XML documents generated by the SOAP Outbound service, set the parameter "SOAPAddXMLDeclaration" to true or yes.|
SendSOAPRequest Business Process
The SendSOAPRequest business process enables the application to send SOAP messages.
- Applies a SOAP envelope to the data, if requested.
- Adds SOAP headers to an outbound request if the process data contains SOAP headers. The business process takes all subordinate nodes under the SOAPHeaders node in process data and adds them as SOAP header blocks.
- Adds SOAP attachments to an outbound request if the process data contains SOAP outbound attachments. See Sending Multiple Attachments
- Sends the SOAP message to a receiver using HTTP.
- Receives a response.
- Acknowledges a response.
- Provides a response to another business process in the application.
- Create a SOAP Outbound service configuration with a name and description.
- Create a separate business process for each SOAP service you want
the application to call.
The business process must complete the following tasks:
- Assign a value to SOAPRequestURL. The value is the URL to which the pplication should post the SOAP request.
- Perform an operation with InvokeBusinessProcessService as the participant, assigning SendSOAPRequest to the WDF_NAME parameter.
- Depending on your needs, assign values to other parameters before using the SendSOAPRequest business process.
The following table identifies parameters for various SendSOAP functions and the values you may need to specify in your business process:
|Required SOAP Function||SOAP Parameter||Parameter Value|
|SOAPAction HTTP header must be present||SOAP_ACTION||HTTP header|
|SOAP enveloping on primary document before posting||ADD_SOAP_ENVELOPING||true – Add SOAP enveloping (default)
false – No SOAP enveloping
|Digitally sign a SOAP message||SIGN_WITH_KEY||Exact name of the digital certificate.|
|Envelope namespace prefix for SOAP message||SOAPEnvNSPrefix||Envelope namespace prefix. ADD_SOAP_ENVELOPING must also be true. The default is SOAP_ENV.|
|Distinguish whether expected response is a SOAP message||SOAP_RESPONSE_NON_ SOAP||true – Response is not a SOAP message.
false – Response is a SOAP message. Default.
|Verify a SOAP response that has been digitally signed||VERIFY_WITH_KEY||Name of the public key. Specify this value before you use the SendSOAPRequest business process if you expect a signature on the SOAP response.|
|Must use a proxy server||xport-tp-proxyauth||The following information in this format: IP
User name and password may not be required.
|Envelope namespace for SOAP message||SOAPEnvNSURI||Envelope namespace. The default is http://www.w3.org/2001/06/soap-envelope.|
Business Process Example – SendSOAPRequest
The following is the predefined SendSOAPRequest business process, as delivered with the application:
<process name="SendSOAPRequest"> <sequence> <operation name="SoapOut"> <participant name="SOAPOutbound"/> <output message="BPML:output"> <assign to="." from="*"></assign> </output> <input message="input"> <assign to="." from="*"></assign> </input> </operation> <operation name="HTTPSend"> <participant name="SOAP_HTTP_Send"/> <output message="Xout"> <assign to="b2b-raw-response">true</assign> <assign to="." from="*"></assign> </output> <input message="Xin"> <assign to="." from="*"></assign> </input> </operation> <operation name="SoapIn"> <participant name="SOAPInbound"/> <output message="BPML:output"> <assign to="." from="*"></assign> <assign to="bootstrap">false</assign> </output> <input message="input"> <assign to="." from="*"></assign> </input> </operation> </sequence> </process>
The following illustration shows the business process as it appears in the GPM:
Sending Multiple Attachments
The SOAP Outbound service will prepare a SOAP message package (SOAP document with attachments(s)), if desired. It uses the primary document (or the entire SOAP message, depending on configuration) and looks for attachments in the SOAP payload in process data in Pro-cessData under SOAPOutboundAttachments.
- Documents 1 through n must be named SOAPOutboundAttachments/SOAPAttachment1 through SOAPOutboundAttachments/ SOAPAttachmentn
- A unique Content-ID must be set for any attachments. This can be done with an assign statement such as the following:
<assign to="SOAPOutboundAttachments/SOAPAttachment1/ @Content-ID">http://www.stercomm.com/myattachment1.txt</assign>
Sending SOAP Fault Messages
The Web Services Interoperability Organization (WS-I) requires all SOAP faults be sent with a 500 HTTP error status. Sterling B2B Integrator sends SOAP faults with a 200 HTTP error status.
To enable Sterling B2B Integrator to send SOAP faults with 500 HTTP error status, add the following assignment to all the SOAP Outbound services used in the business process workflow:
To communicate automatically the parameters with the HTTP Client adapter, direct access to the process data must be provided in the 'MessageFromService' configuration of SOAP Outbound service. The HTTP Client adapter must be able to access the process data in the 'MessageToService' configuration of SOAP Outbound service to enable the HTTP Client adapter to read the parameters passed from the SOAP Outbound service.
If direct access is not provided to the HTTP Client adapter, you must manually pass the following parameters to the HTTP Client adapter:
<doc-has-headers>true</doc-has-headers> <status-code>500</status-code> <xport-raw-xresponse>true</assign> <xport-doc-on-error>true</assign>