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:

Category	Description
System Name	SOAPOutbound
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
Related services	Related services: SOAP Inbound service HTTP Server adapter HTTP Client adapter 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.
Application requirements	None
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: Success – The output document was created successfully. Error – Errors were encountered somewhere during the creation of the SOAP request or response.
Restrictions	None
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.

When the service runs in send mode, the application does the following:

Adds SOAP enveloping, including header blocks, if necessary
Generates the necessary HTTP headers
Sets some values to be used by the HTTP Client adapter

When the service runs in respond mode, the application does the following:

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.

Additional Functions

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:

Parameter	Description
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.

When the application sends a SOAP message, SendSOAPRequest completes the following process:

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.

Before you use the SendSOAPRequest business process, you must complete the following tasks:

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 address`,`port` `number`,`username`,`password`. 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.

The following are required:

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.

Note: If you force a 500 HTTP error status to be returned, a default Jetty error message is returned instead of the SOAP fault document.

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:

<assign to=""></assign>

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>