h3. Introduction When consuming a web service, it’s nice when all is working smoothly - the web service receives valid input from the web service client and, in turn, returns a valid response to that client. It would be nice if all services always "worked" in this way or just "worked" period. Well... back to reality. Sometimes bad data is inevitably supplied or changes take place in the implementation of the web service and a SOAP fault response containing application specific error information is sent back to the client. When SAP NetWeaver XI is in the middle, and the receiver SOAP adapter is used to call a web service, technically, XI (specifically the receiver SOAP adapter) is the web service client that initiates the call to a web service and receives its response. XI then passes the response back to the original sender that passed the initial request to XI. In successful cases, this is straightforward. However, in problem cases, the web service will return a SOAP fault message which will either result in a +system error+ message or an +application error+ message in XI, usually with a HTTP 500 response code. In the system error case, there are not many options as far as capturing and handling specifics within the SOAP fault. For application errors, however, the fault payload can be captured/accessed and, if necessary, mapped back to the original sender’s format. For you seasoned XI experts, none of this is news to you. However, there have recently been some threads on SDN on how to handle these SOAP fault responses, so... In this blog, a closer look is taken at handling SOAP fault application error messages when using SAP NetWeaver XI. It also illustrates how a +fault mapping+ can be used to map a SOAP fault back to a corresponding fault format that the original sender can understand. It also discusses some differences to consider in handling SOAP faults when using the standard soap mode vs. the "nosoap" mode.
h3. SOAP Fault - Application Error Message element within the SOAP Fault message as specified for {code:html}SOAP 1.1{code}. An example within the given link is provided: h3. HTTP Return Codes - soap/nosoap modes h3. RFC to SOAP Example The main example in this blog shows a synchronous RFC to SOAP scenario using a custom RFC client application calling a demo XMethods web service called "Currency Exchange Rate" that returns the currency exchange rate between two countries. There are many threads and blogs on SDN on how to set up a basic RFC to SOAP scenario (just do a SDN search), so this is NOT a "step-by-step". Instead, the focus is on the fault/exception handling aspects of this scenario. h4. About XMethods Currency Exchange Service The "Currency Exchange Service" web service, along with the WSDL (http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl), is provided on the XMethods website at http://www.xmethods.net (http://www.xmethods.net). It’s an +RPC style+ service and the basic SOAP request and response (successful case), looks like this:
h5. Request h5. Response The above is an example of a valid request/response case. Now, what if I submitted the request with some invalid input - say +InvalidCountry+ and US for "Country1" and "Country2" respectively as shown:
h5. Invalid Request h5. SOAP Fault - Application Error Response h4. RFC "Stub" Shown below is my remote-enabled RFC "stub" (just parameters, no implementation code) that will, more-or-less, serve as the main client/sender in my RFC to SOAP scenario to send the two "Country" input data to the "Currency Exchange Service" web service. Notice the declaration of the "Exceptions" parameter +CURR_EXCHANGE_APP_ERROR+. The fault payload from the web service will map to this RFC exception.
h4. Integration Repository (Design) Below is my imported RFC Z_CURRENCY_EXCHANGE_1. The imported RFC metadata will serve as the sender/outbound/synchronous interface and also contains the relevant request/response/exception message types to be used the corresponding mappings. Displayed is only the RFC Exception message type. 
For the inbound interface (corresponding to the web service invocation), the Currency Exchange Service WSDL is imported and used for the input and output message types. Based on the fault response payload received while testing the service, a fault message type XML schema (xsd) was created externally and imported as an External Definition, which is what is displayed as "electric-detail" below. 
Also regarding the import of the WSDL for the Currency Exchange Service, a couple of things to note: ** ** However, even with this option, if the WSDL is imported as is, the namespace for the messages +getRate+ and +getRateResponse+ do not get set to the correct/necessary namespace +urn:xmethods-CurrencyExchange+ as shown above. As a work-around, the WSDL can be tweaked externally and re-imported. Basically, the target namespace reflected in the first line for the definitions element should be adjusted to reflect the namespace "urn:xmethods-CurrencyExchange" and not "http://www.xmethods.net/sd/CurrencyExchangeService.wsdl". The final import should look like this: 
Regarding the Interface Mapping, a fault mapping must be configured. In order to be able to configure a fault mapping, a Fault Message Type should be specified within both the source and target interface. Then when clicking on the "Read Interfaces" button within the Interface Mapping, a "Fault" tab will appear. 
Below is a shot of the fault message mapping that maps the Currency Exchange Service fault payload ("electric-detail") to the RFC exception. 
Note that the "Name" field should reflect the RFC exception name. In this case +CURR_EXCHANGE_APP_ERROR+. 
h4. Integration Directory (Configuration) As far as configuration is concerned, no special configuration is needed as it relates to fault handling. Standard configuration for the channels (sender RFC/receiver SOAP), receiver determination, etc. should be maintained for this scenario. h4. Runtime - Sample Test Run Using the function module test tool is sufficient in initiating a runtime test scenario for this RFC to SOAP example once the configuration has been complete. Below are some screen shots within the function module test tool and the XI monitoring tool to illustrate what happens at runtime. For comparison, both success and error cases are provided.
h5. Success Case Initiating the request...
Monitoring the request and mapped payloads... 
Monitoring successful response and mapped payloads... 
Successful response back to original RFC sender... 
h5. Error Case Bad data will be passed as one of the parameters... 
An application error will result... 
A look at the request part and mapped payloads... 
A look at the application error response fault payload... As you can see, the fault mapping is invoked where the fault payload is mapped back to the RFC exception. 
Ultimately, the RFC sender receives the application error message as an RFC exception. 
h3. SOAP Fault - Application Error Message element within the SOAP Fault message as specified for {code:html}SOAP 1.1{code}. An example within the given link is provided: h3. HTTP Return Codes - soap/nosoap modes h3. RFC to SOAP Example The main example in this blog shows a synchronous RFC to SOAP scenario using a custom RFC client application calling a demo XMethods web service called "Currency Exchange Rate" that returns the currency exchange rate between two countries. There are many threads and blogs on SDN on how to set up a basic RFC to SOAP scenario (just do a SDN search), so this is NOT a "step-by-step". Instead, the focus is on the fault/exception handling aspects of this scenario. h4. About XMethods Currency Exchange Service The "Currency Exchange Service" web service, along with the WSDL (http://www.xmethods.net/sd/2001/CurrencyExchangeService.wsdl), is provided on the XMethods website at http://www.xmethods.net (http://www.xmethods.net). It’s an +RPC style+ service and the basic SOAP request and response (successful case), looks like this:
h5. Request h5. Response The above is an example of a valid request/response case. Now, what if I submitted the request with some invalid input - say +InvalidCountry+ and US for "Country1" and "Country2" respectively as shown:
h5. Invalid Request h5. SOAP Fault - Application Error Response h4. RFC "Stub" Shown below is my remote-enabled RFC "stub" (just parameters, no implementation code) that will, more-or-less, serve as the main client/sender in my RFC to SOAP scenario to send the two "Country" input data to the "Currency Exchange Service" web service. Notice the declaration of the "Exceptions" parameter +CURR_EXCHANGE_APP_ERROR+. The fault payload from the web service will map to this RFC exception.
h4. Integration Repository (Design) Below is my imported RFC Z_CURRENCY_EXCHANGE_1. The imported RFC metadata will serve as the sender/outbound/synchronous interface and also contains the relevant request/response/exception message types to be used the corresponding mappings. Displayed is only the RFC Exception message type. For the inbound interface (corresponding to the web service invocation), the Currency Exchange Service WSDL is imported and used for the input and output message types. Based on the fault response payload received while testing the service, a fault message type XML schema (xsd) was created externally and imported as an External Definition, which is what is displayed as "electric-detail" below. Also regarding the import of the WSDL for the Currency Exchange Service, a couple of things to note: ** ** However, even with this option, if the WSDL is imported as is, the namespace for the messages +getRate+ and +getRateResponse+ do not get set to the correct/necessary namespace +urn:xmethods-CurrencyExchange+ as shown above. As a work-around, the WSDL can be tweaked externally and re-imported. Basically, the target namespace reflected in the first line for the definitions element should be adjusted to reflect the namespace "urn:xmethods-CurrencyExchange" and not "http://www.xmethods.net/sd/CurrencyExchangeService.wsdl". The final import should look like this: Regarding the Interface Mapping, a fault mapping must be configured. In order to be able to configure a fault mapping, a Fault Message Type should be specified within both the source and target interface. Then when clicking on the "Read Interfaces" button within the Interface Mapping, a "Fault" tab will appear. Below is a shot of the fault message mapping that maps the Currency Exchange Service fault payload ("electric-detail") to the RFC exception. Note that the "Name" field should reflect the RFC exception name. In this case +CURR_EXCHANGE_APP_ERROR+. h4. Integration Directory (Configuration) As far as configuration is concerned, no special configuration is needed as it relates to fault handling. Standard configuration for the channels (sender RFC/receiver SOAP), receiver determination, etc. should be maintained for this scenario. h4. Runtime - Sample Test Run Using the function module test tool is sufficient in initiating a runtime test scenario for this RFC to SOAP example once the configuration has been complete. Below are some screen shots within the function module test tool and the XI monitoring tool to illustrate what happens at runtime. For comparison, both success and error cases are provided.h5. Success Case Initiating the request...
Monitoring the request and mapped payloads... Monitoring successful response and mapped payloads... Successful response back to original RFC sender... h5. Error Case Bad data will be passed as one of the parameters... An application error will result... A look at the request part and mapped payloads... A look at the application error response fault payload... As you can see, the fault mapping is invoked where the fault payload is mapped back to the RFC exception. Ultimately, the RFC sender receives the application error message as an RFC exception.
15 Comments