N.B. Данные параметры адаптера доступны и корректно работают в зависимости от версии, SP и PL компонент системы. Просьба не ругать авторов, если ваша версия компонент ниже требуемого

N.B. Минимальная версия SP указана ниже для каждой версии NetWeaver. Отражён минимальный SP, который содержит указанную функциональность. Функциональность может быть доступна только начиная с определённого PL в рамках указанной или последующих SP. Детали применимости -- см. релевантные ноты

When SOAP adapter is configured at receiver side in a synchronous scenario to call the services of an external partner via https with Proxy configured. The partner declines the calls with response code 400 due to handshake failure. The calls were rejected because SOAP adapter is not providing the correct FQDN in the SNI TLS server extension. Instead of target host the external partner receives the FQDN of the proxy server configured in SOAP receiver channel, as SNI target.

Special Development.

When SOAP receiver channel is configured in HTTPS mode with Proxy setup.

Please configure the parameter XMBWS.SniImplementation with value true in module tab under XISOAPAdapterBean to activate the feature. By default the value is false.

This note corrects a potentially incompatible change introduced in note

933599 XI 3.0 soap receiver in nosoap mode ignores HTTP status code

Prior to note 933599, the nosoap mode of the receiver SOAP adapter ignored the HTTP status code. Note 933599 corrected this behavior by including the HTTP status code check to treat HTTP 4xx/5xx responses as XI System error. Some application, however, had been already developed to depend on the prior behavior of accepting any responses.

In order to provide compatibility with those applications, this note provides a configurable option to disable the HTTP status code check.

Program error

The HTTP status code check for the nosoap mode of the SOAP receiver adapter can be disabled by the following module parameter for the SOAP adapter module

parameter name: XMBWS.NoSOAPIgnoreStatusCode parameter value: true or false (default is false)

Setting the above parameter to true will configure the SOAP receiver adapter to ignore the HTTP status code.

Apply the following patch according to the SP version

When PI SOAP adapter with XI protocol is configured in multiple ICOs in the same Adapter then, the processing fails when the message is sent from first ICO to second ICO in Asynchronous mode, with duplicate message-ID.

When PI SOAP adapter with XI protocol is configured in multiple ICOs in the same Adapter then, the processing fails when the message is sent from first ICO to second ICO in Synchronous mode, with duplicate message-ID.

This is a new requirement as it was never implemented in PI SOAP adapter with XI protocol processing.

Configure two ICO scenarios, where SOAP adapter with XI protocol is configured at received side in first ICO and at sender side in second ICO.

Code changes have been made at the receiver side processing of SOAP adapter to consider new GUID when such kind of request comes in Asynchronous / Synchronous mode. For this, you have to configure a module parameter XMBWS.replaceMessageGUID with value true (both without quotes) under the SOAP adapter module i.e., XISOAPAdapterBean.

By default, the value is set to false and SOAP receiver adapter will not process the request between two ICOs inside the same Adapter Engine.

In the scenario where SOAP Receiver adapter is used and while processing in Synchronous mode, gets an application error as a response. But the response is expected to contain error and do not want the channel monitoring to indicate this as an error and change the channel's monitoring status to RED (from GREEN). Currently there is no way to suppress these errors.

In the current implementation of PI SOAP adapter, this option (to suppress the application fault) is not available.

PI SOAP Receiver adapter, processing messages in Synchronous mode.

Please set the parameter suppressAppFault to true as a Module Parameter in the SOAP Receiver adapter. If it is set to true, then you can suppress the Application fault error in the auditlog and also avoid channel's monitoring status being changed from GREEN to RED.

Application fault or System fault response messages in synchronous receiver SOAP scenarios, received from the target system, are not transferred to the PI Integration Engine with the expected format after upgrade.

A new behavior has been introduced with SAP Note 1109648 for the cases when the target system of a receiver SOAP adapter in no-SOAP mode has returned a fault message in synchronous business scenarios. As a result, the response message to the Integration Engine comes with newly introduced format. Therefore, mapping programs or other programming flow at the Integration Engine which depend on that, would fail.

The difference in the formats is as follow:

-- The new format after the changes of Note 1109648: the SOAP faults received by the target system are treated as adapter framework internal errors and again treated further as HTTP 500 Internal Server Error but in the format:

<SAP:Error xmlns:SAP="http://sap.com/xi/XI/Message/30"
            xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
            SOAP:mustUnderstand="1">
  <SAP:Category>XIAdapterFramework</SAP:Category>
  <SAP:Code area="MESSAGE">GENERAL</SAP:Code>
  <SAP:P1 />
  <SAP:P2 />
  <SAP:P3 />
  <SAP:P4 />
  <SAP:AdditionalText>com.sap.aii.af.ra.ms.api.DeliveryException:
     SOAP: response message contains an error
     XIAdapter/HTTP/ADAPTER.HTTP_EXCEPTION -
     HTTP 500 Internal server error</SAP:AdditionalText>
  <SAP:ApplicationFaultMessage namespace="" />
  <SAP:Stack />
  <SAP:Retry>M</SAP:Retry>
</SAP:Error>

No payload follows to this message as it is treated as unsuccessful in the Adapter Framework.

-- Prior to the changes of Note 1109648: the faults received by the target system are treated further as HTTP 500 Internal Server Error and sent to Integration Engine in the format:

<SAP:Error xmlns:SAP="http://sap.com/xi/XI/Message/30"
           xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
            SOAP:mustUnderstand="1">
  <SAP:Category>XIAdapter</SAP:Category>
  <SAP:Code area="HTTP">ADAPTER.HTTP_EXCEPTION</SAP:Code>
  <SAP:P1 />
  <SAP:P2 />
  <SAP:P3 />
  <SAP:P4 />
  <SAP:AdditionalText>
      HTTP 500 Internal server error
  </SAP:AdditionalText>
  <SAP:ApplicationFaultMessage namespace="" />
  <SAP:Stack />
  <SAP:Retry>M</SAP:Retry>
</SAP:Error>

The payload with the fault XML follows. The message is successful in the Adapter Framework.

The current note resolves the conflict by making it switchable. A new parameter to SOAP adapter's module is introduced:

noSOAPMakeSysErrFromResponseFault

The default value is true. This means that the behavior is the one introduced by the the change of Note 1109648, that is the errors have the first format shown above. If you need the format before the changes of Note 1109648, for the default module sap.com/com.sap.aii.af.soapadapter/XISOAPAdapterBean set:

  Module Key  =  soap
Parameter Name  =  noSOAPMakeSysErrFromResponseFault
Parameter Value  =  false

In addition, you can set the receiver SOAP adapter to completely ignore the HTTP 500 Internal Server Errors received by the target system. In this case, the messages are successful in the Adapter Engine and sent as successful to the Integration Engine. The payload of the message contains the fault received by the target system. Refer to SAP Note 1055678 for details on setting this.

In the scenario where SOAP Receiver adapter is used and if XISOAPAdapterBean is not the last module, even though there is no error while processing the last module, SOAP adapter is generating an error.

Programming error.

Please set the parameter XMBWS.SoapIsNotLastModule to true as a Module Parameter in the SOAP Receiver adapter.

SOAP Receiver Channel when configured with certificate authentication randomly encouters HTTP 401 error.

SOAP Receiver Channel should be configured to use certificate authentication.

The error is resolved by code change. Please apply the patches as available in the note to solve the issue. The fix is provided for 731 SP17 onwards.

After applying the patch as per the note, please add following module parameters with the value as true for the fix to be effective:

isMessageSecurity
XMBWS.restoreCertificate

An error Acknowledgement message is returning when asynchronous and sync interfaces are connected. In an asynchronous scenario after a successful commit of data, the PI return a Acknowledgement message, but the interface is not ready to manage this information, as this is an asynchronous scenario.

In SOAP adapter for Asynchronous scenarios, System Acknowledgment is generated.

The module key XMBWS.GenerateSysAck is set to true by default.

The issue has been resolved by code correction

SOAP adapter returns HTTP 500 in case of application error.

The parameter SynchSetErrorResponseAtFault which is used to is set to true / false in the channel it is not used anymore from PI 730.

SOAP adapter returns HTTP 200 in case of application error instead of the expected HTTP 500 error response code. The parameter SynchSetErrorResponseAtFault is set to true / false in the channel. This is not the exact behavior and hence this feature has been removed from PI 730 and above.

The parameter SynchSetErrorResponseAtFault is not read any more and for an application error HTTP 500 will be the response code.

SOAP sender channel with the option Keep Attachment enabled. Keep the name of the SOAP attachment, which is set with the MIME header Content-Description. This name should be used as the payload name.

However, even after setting the XI.BindPayloadName to true in the SOAP Sender Channel, SOAP adapter automatically sets the payload name to attachment-1, attachment-2, … , attachment-n.

Bug Fix.

Set the module parameter XI.BindPayloadName to true in the SOAP Sender Channel with the option Keep Attachment enabled.

Original attachment filenames are changed to attachment-1, attachment-2, … , attachment-n.

Code changes have been made in the sender side processing of the SOAP adapter to retain the original attachment-names.

Configure a module parameter XI.BindPayloadName with value true under the SOAP adapter module i.e., CallSapAdapter and restart the SOAP Sender Channel for the changes to reflect.

When SOAP adapter is configured at receiver side, it has been observed that in synchronous processing, the sessions are getting timed out and reporting the error as given below :

java.lang.RuntimeException: Error while silently connecting: org.w3c.www.protocol.http.HttpException: Unable to contact target server 

This is happening due to the improper handling of timeouts.

When HTTP destination option is used in PI SOAP receiver adapter with XI protocol, the processing of the XI request depends upon the timeout settings at receiver adapter and also the timeout settings at IAIK library.

Configuring PI SOAP adapter receiver side with below options:

• XI protocol as message protocol with HTTP destination as Addressing Type and configure the timeout parameter.
• SOAP protocol as message protocol with URL Address as Addressing Type and configure the timeout parameter.

The latest update of SSL/TLS and HTTP implementation on SAP Netweaver Java Server is available in SAP note 2284059.

Code changes have been made at receiver side processing of XI request by PI SOAP receiver channel. Two more timeout parameter have been introduced i.e.,

• XMBWS.ConnectTimeout: This timeout is valid for establishing the initial connection to the receiver system. Typically this process should be very fast. The default value for this timeout is 10000 msec (i.e., 10 seconds). Setting higher timeouts is not advisable. Instead it should be checked why it takes that long to establish the connection.

• XMBWS.ReadTimeout: This timeout is a processing timeout. If the receiver system did not return the complete response within the specified time the connection will be closed. Potentially long running data transfer (e.g. due to large message sizes) can be interrupted by this. The default value for this timeout is 300000 msec (5 minutes).

Note : If XMBWS.Timeout is set, then it will behave as read timeout. But we recommend you to use the new timeouts to ensure both connect and read timeouts are covered properly.

In SOAP Receiver channel, XMBWS.XMLEncoding parameter can be added in module tab to specify the encoding of the payload. However, the parameter does not work when the Do Not Use SOAP Envelope is selected in the SOAP Recevier Channel Configuration.

In SOAP Receiver channel, Do Not Use SOAP Envelope option should be checked. Parameter XMBWS.XMLEncoding should be added in module tab.

The issue is fixed through code correction.

You are using SOAP Adapter at the Sender Side with the whitespaces before the initial <?xml tag of the SOAP Request. During SOAP Message procesing, following error(s) are observed:

500 Internal Server Error
Error during parsing the SOAP part --- Can't parse the document
org.xml.sax.SAXParseException; The processing instruction target matching "[xX][mM][lL]" is not allowed

<?xml version='1.0'?>
<!-- see the documentation -->
<SOAP:Envelope xmlns:SOAP='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP:Body>
<SOAP:Fault>
<faultcode>SOAP:Server</faultcode>
<faultstring>Server Error</faultstring>
<detail>
<s:SystemError xmlns:s='http://sap.com/xi/WebService/xi2.0'>
<context>XIAdapter</context>
<code>ADAPTER.JAVA_EXCEPTION</code>
<text>
<![CDATA[
Reason : Can't parse the document See log trace with id: n/a
]]>
</text>
</s:SystemError>
</detail>
</SOAP:Fault>
</SOAP:Body>
</SOAP:Envelope>

Soap Request with the whitespaces before the initial <?xml tag.

Code changes have been made in the SOAP Sender to trim the leading whitespaces as the part of the SOAP Request.

Set the module parameter trimWhiteSpaces to true for CallSapAdapter in PI SOAP Sender Adapter.

The SOAP receiver adapter may fail to establish an SSL connection using a client certificate. This problem is indicated in the audit log of the adapter's message monitor.

Program error/limitation

The default behavior of the SOAP receiver adapter is to send the certificate chain included in the keystore object identified by the specified keystore view and alias.

Depending on the server's setting, the server may refuse to accept the connection because of some missing certificates to the root. On the other hand, if the server already has those certificates, it may accept the connection even when the client sends only its own certificate.

You may manage your certificate in such a way that the adapter can establish a connection, namely by putting all certificates required by the server in the keystore object.

For other cases, this patch will provide three configurable options in sending certificates. This is configured in the module configuration table using parameter

name: certLookupMode
value: integer value (default is 2)

1 for the top certificate in the keystore object;
2 for the certificate chain in the keystore object;
3 for all certificates down to the root certificate across multiple keystore objects

Apply the following patch and configure the module parameter described above.

PI SOAP receiver channel is configured with third-party X.509 certificates over HTTPS communication with target system. Although that server-side certificate chain is valid/trusted and typically other non-PI scenarios work with the very same HTTPS target system, sending messages through the SOAP receiver channel fails with:

iaik.security.ssl.SSLCertificateException: Peer certificate rejected by ChainVerifier
at iaik.security.ssl.r.checkIsTrusted(Unknown Source)
at iaik.security.ssl.x.b(Unknown Source)
at iaik.security.ssl.x.a(Unknown Source)
at iaik.security.ssl.r.d(Unknown Source)
at iaik.security.ssl.SSLTransport.startHandshake(Unknown Source)
at iaik.security.ssl.SSLTransport.getInputStream(Unknown Source)
at iaik.security.ssl.SSLSocket.getInputStream(Unknown Source)
at com.sap.aii.af.sdk.xi.net.HTTPClientConnection.getInputStream(..)
at com.sap.aii.af.sdk.xi.net.HTTPClientConnection.call(..)
    .. .. ..

Important: This SAP Note applies to SOAP receiver channel transport-level security only, also known as SSL server certificate trust. It does not concern message level security configuration - SOAP payload validation and/or decryption. It neither applies to client-side X.509 certificate authentication towards the target system, also known as SSL mutual trust.

The issue occurs intermittently due to program error. The fix provided with this SAP Note comprises of:

• SOAP receiver adapter evaluates the TrustedCAs Keystore View as default trusted certificates list. This can be changed by any other keystore view by manipulating the parameter mentioned in the solution section below. TrustedCAs is the recommended keystore view for trusted certificates import.

• SOAP receiver adapter improves synchronization issue with the TrustedCAs Keystore View whenever it is selected as trusted certificates store.

The recommended keystore view to keep your partner's certificate is TrustedCAs view. Move your trusted certificates there.

In all other cases, you can try the workarounds below. They are valid for limited scenarios only:

Find the receiver SOAP channel module configuration, navigate to the module sap.com/com.sap.aii.af.soapadapter/XISOAPAdapterBean, and set up the following parameter:

Module Key  = soap
Parameter Name = trustStore
Parameter Value = TrustedCAs

An alternative workaround is to restart the application com.sap.aii.adapter.soap.lib, which will also trigger a restart of the application com.sap.aii.adapter.soap.app.

SOAP Adapter is using the AFW/MS internal HTTPClientConnection for HTTP / HTTPS communication.

HTTPClientConnection is proprietary client tailored for internal PI communication and may have limitations like HTTP method support, connection pooling and other.

With this Note the standard SAP HttpClient library is adopted by SOAP Adapter to be used for HTTP / HTTPS communication.

The switch to the SAP HttpClient library is controlled in two ways:

Via global online modifiable application property useSAPHttpClient with type boolean of the sap.com/com.sap.aii.adapter.soap.app. To change the property, open netWaver Administrator, go to Configuration tab -> Infrastructure -> Java System properties. In the templates section select the corresponding template. In the details section select Applications tab, search and select com.sap.aii.adapter.soap.app. In the Extended details section change the value of the property.

You can overwrite the upper global property for each SOAP receiver channel. In the module section, you can add the useSAPHttpClient module parameter for the soap module with boolean value.

After the switch the version of HTTP protocol will be HTTP/1.1.

Enable client side HTTP communication tracing, as this is easier to setup than TCP Gateway or another sniffing tool.

The trace is enabled per channel. For each channel, traces are written in a separate trace file in .../server#/log/pi_http directory, in a separate tracing location. Filenames contains location name is (location name = PI_HTTP.<party>.<service>.<channel>) and a suffix with a number. The number of trace files per channel is limited to 10, each up to 7.6 MB (8000000 bytes) large.

There are 3 possible severity levels: headers, plain and hex.

• headers severity means that only HTTP headers are traced, both for the HTTP request and HTTP response;
• plain severity means that the whole HTTP request-response communication is traced (headers and body) in plain text
• hex severity means that a hex dump is traced for the whole HTTP request-response communication in the same format as SAP ICM implementation does it.

Tracing is done before writing the data to the socket, so the functionality is fully valid for HTTPS communication cases.

This note introduces client side HTTP tracing for HTTP based receiver channels: SOAP, AXIS, HTTP and ISpeak adapter receiver channels.

With this first version, a reference implementation first for SOAP adapter receiver channels is done.

1. Enabling HTTP trace

The trace is enabled by setting a module parameter for the receiver SOAP channel: in the module configuration choose the XISOAPAdapterBean module's key and set the following module parameter: TraceHTTP with one of the above values.

The default severity is headers, it is also applicable in case the parameter is mistyped in the channel configuration.

2. Monitoring the traces

• In NetWeaver Administrator's Log Viewer: download the attached XML definition for a custom view. In NWA Log Viewer, got to View -> Import View and select the XML. You will have a new Log View: PI_HTTP, which contains only PI HTTP traces. Edit the host and SID values so that you have the system's proper ones.

• Directly in the trace files on files system - for every channel there is a separate file with name: PI_HTTP.<Party>.<Component>.<Channel>.#.trc

HTTP_AAE adapter implementation: see note 2157425.

You are using a SOAP adapter at receiver side to process SOAP requests synchronously and observe that a set of SOAP / XML related namespace definitions are added to the root tag of the XML payload in the SOAP response.

These namespace definitions are not required by the payload and might cause issue when the message is sent to system, which does not support namespaces.

Advance Development.

Send a synchronous SOAP request to target at receiver side of SOAP adapter processing.

All the namespaces of the SOAP envelope element are added to the root element of the XML payload, including:

xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

A new option is introduced for the SOAP adapter that allows removing the not required namespace definition from the message root XML tag, when created by a SOAP sender channel.

In order to switch on the new option, go to SAP NetWeaver Administration -> Java System Properties -> Application Tab and filter for application name com.sap.aii.adapter.soap.app and set value true to the property removeNotUsedNamespacesInSynchResponse.

During SSL Handshake/Channel Ping, the connection with the Target (HTTPS with PROXY) fails with the following error(s):

Could not open connection to the URL https://<hostname>:<port>/********************
ssl_debug: Sending alert: Alert Fatal: bad certificate
ssl_debug: Shutting down SSL Layer
ssl_debug: SSLException while handshaking: Peer Certifcate rejected by ChainVerifier
Communication over HTTPS/PROXY. Handshake error; Additional info com.sap.aii.af.sdk.xi.net.TraceWriter@*****
[EXCEPTION]
iaik.security.ssl.SSLCertificateException: Peer certificate rejected by ChainVerifier

Bug fix.

Instead of the hostName, IP Address is used. Host Verification mode apparently set to false even though hostVerification = true in the SOAP Receiver Channel (module configuration).

Sending v3 client_hello message to <IP Address>

where IP address is used instead of hostName. PI SOAP Receiver Channel with the Target configured to support SSL and the Proxy i.e. Target URL with HTTPS schema and Configure Proxy.

Set hostVerification to true for the module bean sap.com/com.sap.aii.af.soapadapter/XISOAPAdapterBean

Code changes have been made in the receiver side processing for the Target Host Connectivity.

Set hostVerification to true for sap.com/com.sap.aii.af.soapadapter/XISOAPAdapterBean module bean and restart the channel for the changes to reflect.