Configuring the SOAP Adapter

Use

You need to configure the SOAP adapter so that you can exchange SOAP messages between the Integration Engine and remote clients or servers of Web Services.

The SOAP adapter provides a runtime environment that includes various SOAP components for the processing of SOAP messages. You can combine these SOAP components with separate components to satisfy your needs and requirements.

The SOAP adapter uses a helper class to instantiate and control SOAP components. If you want to use your own SOAP processing logic you must make your helper class known to the SOAP adapter.

To configure the SOAP adapter you must specify the following:

The helper class that implements the following interface:
com.sap.aii.messaging.adapter.ModuleBubbleHelper
The parameter values for the specified helper class
For example, you must specify the following parameters for the helper class ModuleBubbleHelperXMBWSImpl (instantiates a BubbleBag to integrate remote Web Services with the Integration Engine):
- Information about the Integration Engine destination (when the Integration Engine is acting as a service provider and therefore the SOAP adapter must be configured as an sender adapter).
- Information about the Web Service provider destination (when the Integration Engine is acting as a service client and therefore the SOAP adapter must be configured as an receiver adapter).
- Various options for controlling the conversion of multi-part Integration Engine SOAP messages and Web Service SOAP messages.

Prerequisites

You have:

Installed the corresponding adapter.
Selected the adapter on the configuration screen.
Called the adapter configuration by choosing Configure.

Procedure

The configuration of the SOAP adapter comprises two functional sub areas:

The version specification for the configuration
version=
```
30
```
This specification is mandatory. If no specification is entered, the configuration is interpreted as an XI 2.0 adapter configuration. Other values are not permitted and trigger an error.
The Java class name for the SOAP adapter
Specify the class name as follows:
classname=
```
com.sap.aii.messaging.adapter.ModuleBubble
```
This specification is mandatory.
The configuration parameters for the specified helper class
For example, you must specify the following parameters for the shipped helper class ModuleBubbleHelperXMBWSImpl:
- Specifications for the Integration Engine as service provider for queries from Web service clients (SOAP sender adapter).
- Specifications for the Web Service provider for queries from the Integration Engine as a Web Service client (SOAP receiver adapter).
You can configure an sender adapter, or an receiver adapter, or both, if required.

Configuring a Helper Class for Sender Processing

Enter the complete address (URL) of the Integration Engine that you want to send the message to:
XI.TargetURL=
```
http://IntegrationEngineHost:port/pipeline-arguments
```
This specification is mandatory when the Integration Engine is acting as a service provider.
Note

The Integration Engine address can also be accessed dynamically from the SAP System Landscape Directory (SLD). The following entry is added to the configuration for this purpose:
XI.SLDConfiguration=
```
SLDaccessor
```
In this case the URL of the corresponding server for the system specified with XI.SenderService is read from the SLD and used instead of the value specified under XI.TargetURL. Therefore, specify the following:
XI.TargetURL=
```
<fromSLD>
```
To be able to access the SLD, the SLDaccessor service must be configured correspondingly and the respective entries must be maintained in the SLD.
Note

If the Integration Server is accessed by means of an HTTP proxy server rather than directly, the following parameters must be set:

XI.ProxyHost=<proxyHostname>

XI.ProxyPort=<proxyPortnumber>
<proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example,
```
8080
```
).
If an authentication was specified for the HTTP proxy server, use the following parameters:

XI.ProxyUser=<proxyUser>

XI.ProxyPassword=<proxyPassword>

If an authentication was specified for the URL (HTTP service) in the Integration Engine, use the following address:

XI.TargetURL=http://<user-name>:<password>@IntegrationEngineHost:port/pipeline-arguments

As an alternative, or if the URL is taken from the System Landscape Directory, you can also specify the logon parameters as follows:
- XI.User=
```
<user-name>
```
- XI.Password=
```
<password>
```
  Note
  
  The specifications must match those that you made in transaction SICF in the Integration Engine. If you do not specify a user and password combination, or the combination is invalid, the system will terminate each attempt to access the Integration Engine with the message Transport Exception: http-Error 401 - Unauthorized.
  
  The user must have the authorizations of group SAP_XI_APPL_SERV_USER on the Integration Server.
For more information on configuring SSL authentication with a certificate, see: Certificate Administration , then Setting Up the Adapter Engine as SSL Client.

If you want to use a different client or language to the default setting in the Integration Engine when logging on, you can also set the following parameters:
- XI.Client=
```
<client-no>
```
- XI.Language=
```
<language-id>
```
The following address arguments are optional. If this information is not contained in the request message of a Web service client, the specifications made here are used to identify the adapter configuration in routing, and mapping in the Integration Engine pipeline. You can also find an explanation about each argument there.
- XI.SenderParty=
```
<sender party name>
```
- XI.SenderService=
```
<sender service name>
```
- XI.InterfaceNamespace=
```
<namespace URI>
```
- XI.Interface=
```
<name>
```
- XI.ReceiverParty=
```
<receiver party name>
```
- XI.ReceiverService=
```
<receiver service name>
```
  If you specify this parameter you do not need to determine a receiver in routing.
The following arguments are mandatory:
- XI.QualityOfService=
```
<QualityOfService>
```
  Specifies how the Integration Engine should process a message. The following values are permitted:
  - XI.QualityOfService=
```
BE
```
    (Best Effort, means synchronous processing)
  - XI.QualityOfService=
```
EO
```
    (Exactly Once, means asynchronous processing)
  - XI.QualityOfService=
```
EOIO
```
    (Exactly Once in Order, means asynchronous processing using queues)
  You must also define a queue name for
```
EOIO
```
  :
- XI.QueueId=
```
<QueueName>
```
  This queue name is used in the Integration Engine to process messages in the same sequence that they arrived in.
- XI.XMLEncoding=
```
<encoding>
```
  Specifies which XML code to use for the Integration Engine. The default value is UTF-8.
Specify the port number and the path for the adapter port for Web Service clients:
- XMBWS.WSPort=<port_no>
  The port number (
```
<port_no>
```
  ) specifies the HTTP server port of the adapter that contains Web Service messages.
- XMBWS.WSPath=<path>
  The path <
```
path
```
  > describes the service part of the adapter URL that receives Web service messages.
Specify how the format of Web Service messages is to be controlled
- XMBWS.KeepHeaders=
```
<boolean>
```
  If you specify
```
true
```
  here, the message headers are copied. Otherwise, all headers are deleted.
- XMBWS.KeepAttachments=
```
<boolean>
```
  If you specify
```
true
```
  here, the message attachments are copied.
- XMBWS.UseEncoded=<boolean>
  If you specify
```
true
```
  here, all Integration Engine message headers are encoded in the HTTP header X-XMB_WS_ENCODED.
- XMBWS.UseQueryString=
```
<boolean>
```
  If you specify
```
true
```
  here, a specification is made in the query string.
The request message is taken into account.

Configuring a Helper Class for Receiver Processing

Enter the complete address (URL) of the Web Service provider that you want to send the message to:
XMBWS.TargetURL=
```
http://WebServiceHost:port/service-arguments
```
This specification is mandatory when the Web Service provider is acting as a service provider.

If an authentication was specified for the URL (HTTP service) entered in the Web Service provider, use the following address:

XMBWS.TargetURL=http://<user-name>:<password>@WebServiceHost:port/ service-arguments

Alternatively, you can also specify the logon parameters as follows:
- XMBWS.User=
```
<user-name>
```
- XMBWS.Password=
```
<password>
```
If the Web Service provider is accessed by means of an HTTP proxy server rather than directly, the following parameters must be set:
- XMBWS.ProxyHost=<proxyHostname>
- XMBWS.ProxyPort=<proxyPortnumber>
<proxyHostname> is the host name of the proxy and <proxyPortnumber> is the port where the proxy receives HTTP requests (for example,
```
8080
```
).
If an authentication was specified for the HTTP proxy server, use the following parameters:
- XMBWS.ProxyUser=
```
<user-name>
```
- XMBWS.ProxyPassword=
```
<password>
```
Specify the value for SOAPAction:
- XMBWS.DefaultSOAPAction=
```
<default_soap_action>
```
```
<default_soap_action>
```
  species the default value for the SOAPAction in Web service messages.
Specify how the format of Web Service messages is to be controlled
- XMBWS.KeepHeaders=
```
<boolean>
```
  If you specify
```
true
```
  here, all Integration Engine message headers are copied to Web Service messages. Otherwise, all headers are deleted.
  Note
  
  Web Service message headers are always copied to Integration Engine messages.
- XMBWS.KeepAttachments=
```
<boolean>
```
  If you specify
```
true
```
  here, all Integration Engine message attachments are copied to Web service messages.
- XMBWS.UseEncoded=
```
<boolean>
```
  If you specify
```
true
```
  here, all Integration Engine message headers are encoded in the HTTP header X-XMB_WS_ENCODED.
  1. XMBWS.EncodingVersion=
```
<2|3>
```
    Specifies which version of the XI message format to use to code the message header in the HTTP header (see XMBWS.UseEncoded). The value
```
233
```
    stands for the XI 2.0 message format and the value stands for the XI 3.0 message format. The default value is .
  2. XMBWS.UseQueryString=
```
<boolean>
```
    If you specify
```
true
```
    here, you can specify query strings.
The response message is taken into account.
Specify the port number and the path for the adapter port for the Integration Engine:
- XMBWS.XMBPort=
```
<port_no>
```
  The port number (
```
<port_no>)
```
  specifies the HTTP server port of the adapter that contains messages from the Integration Engine.
- XMBWS.XMBPath=
```
<path>
```
  The path <
```
path
```
  > describes the service part of the adapter URL that contains messages from the Integration Engine.
Enter the code for the Web service provider:
- XMBWS.XMLEncoding=<encoding>
  Specifies which XML code to use for the Web service provider. The default value is UTF-8.
The adapter can send back a synchronous system acknowledgement if the sender requests it. The acknowledgment confirms that the message was delivered to the receiver.
- If you want to send back a synchronous system acknowledgment, set XI.AckFinal=true. This is the default.
- If you want to prevent a synchronous system acknowledgement from being sent back, even if the sender requests it, set XI.AckFinal=false.

Encoded String Syntax

The structure is as follows:

encheader ::= version '&' token ( '&' token ) *
token ::= name '=' value
name ::= fieldname
value ::= urlencoded fieldvalue
version ::= version number

In XI 3.0, you can use the following field names:

Field Names XI 3.0

Name	Meaning
MessageClass	Message class: ApplicationMessage ApplicationResponse SystemAck ApplicationAck SystemError ApplicationError
ProcessingMode	Synchronous Asynchronous
MessageId	Message ID as GUID with format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RefToMessageId	Reference to message ID, as GUID with format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ConversationId	As string with maximum length of 60
TimeSent	Time stamp (displayed as ISO8601 UTC datetime YYYY-MM-DDThh:mm:ssZ)
Sender.Party	Name of the sender party (displayed as agency:scheme:name)
Sender.Service	Service of the sender
Receiver.Party	Name of the receiver party (displayed as agency:scheme:name)
Receiver.Service	Service of the receiver
Interface	Specified as nsuri ^lcname
QualityOfService	BestEffort ExactlyOnce ExactlyOnceInOrder
QueueId	For ExactlyOnceInOrder

Example

version=3.0&MessageClass=ApplicationMessage&ProcessingMode=synchronous&MessageId=13490851-9aae-11d8-9e93-f28d0a12631c&TimeSent=2004-04-30T13%3A55%3A44Z&Sender.Party=016%3Apattern_33%3AAEG_837654&Sender.Service=SRM1&Receiver.Party=12_55%3A017%3ABASF&Receiver.Service=SALES&Interface=http%3A%2F%2Fsap.com%2Fexample%2Fsrm%5ESRM1

In XI 2.0, you can use the following field names:

Field Names XI 2.0

Name	Meaning
From.Name	Name of the sender business system
From.Interface	Interface name of the sender
To.Name	Name of the receiver business system
To.Interface	Interface name of the receiver
Fault	Fault name (specified as nsuri ^lcname)
MessageId	Message ID as GUID with format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
RefToMessageId	Reference to message ID, as GUID with format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
QualityOfService	BestEffort ExactlyOnce ExactlyOnceInOrder
QueueId	For ExactlyOnceInOrder
TimeSent	Time stamp (displayed as ISO8601 UTC datetime YYYY-MM-DDThh:mm:ssZ)
Direction	Direction of message (request or response)
Document	Name of the main document

Example

version=1.0&From.Name=TravelAgency&From.Interface=http%3A%2F%2FSAP.com%2Fcomponent%2FAgency%5EFlightCheckAvailability&To.Name=Airline&To.Interface=http%3A%2F%2FSAP.com%2Fcomponent%2FAirline%5EFlightAvailability&MessageId=a10cd770-9aae-11d8-9cfa-c4670a12631c&QualityOfService=BestEffort&TimeSent=2004-04-30T13%3A59%3A42Z&Direction=Request