This blog is part of a collection of blog entries that shows architectural concepts and configuration of the SAP PI REST Adapter. We also added some sample scenarios to make it easier for you to understand how your scenario can be implemented using the PI REST Adapter.

If you haven’t done so far, best is to start with the very first blog PI Rest Adapter – Don’t be afraid within the blog series covering the concepts of the REST adapter. A complete list of all blog entries can be accessed from here PI REST Adapter – Blog Overview.

With release 7.31 SP15 / 7.4 SP10 we have enhanced the REST adapter supporting custom error handling. You can maintain rules for defining how the message processing should behave in certain (error) situations. For instance, you would like to ignore particular error codes, or you would like to reply with a custom message based on message content, etc. In this blog, I would like to show you the various options that you have when defining custom error handling.

From release 7.31 SP17 / 7.4 SP12 / 7.5 SP01 onwards, the custom error handling has been further enhanced in a way that situations where no errors occur can be handled. The following features have been introduced:

• A new rule type Always
• A new flag to inverse the rule expression
• A new rule type checking if a message is empty
• New variables keeping http attributes which can be used in custom message

Scenario 1 – Custom error handling on receiver side

I would like to introduce the various custom error handling options that are supported based on the REST receiver adapter. I have configured an Integration Flow from SOAP to REST which calls the REST endpoint exposed by the scenario from one of the previous blogs PI REST Adapter – Exposing a function module as RESTful service. Using the custom error handling on the REST sender side of this scenario, I am able to mock various error situations. This way, I am able to show you the behavior of the particular error situations by comparing when calling the RESTful service using either the Advanced REST Client Application in Google Chrome browser or via the additional SOAP to REST Integration Flow.

For each of the options, let’s take a closer look at how the receiver channel of adapter type REST has been maintained.

Custom error handling options

Double-click on the receiver channel of type REST, and switch to the Error Handling tab below the Adapter-Specific tab. Here, you can define rules that are validated during runtime. For each rule you have to define a condition and an action. The condition usually consists of a source and a value, the action can be either raising an error, ignoring the error, or replying with a custom message.

Fetch various http error situations and reply with respective custom message

We would like to return a custom text depending on particular error situations of the http transport layer. I have defined two rules as follows:

• Reply with custom text <error>not found</error> if HTTP Status Text of the service call response contains the phrase Not Found
• Reply with custom text <error>server not reachable</error> if HTTP Status Code equals either 500 or 503

In any case, the HTTP request becomes successful, i.e., the http status code is set to 200.

Let’s run the scenario that leads to an http status code 500. When directly calling the REST service using the Advanced REST Client, we get an http status code 500 – Internal Server Error.

When calling the REST service via the SOAP to REST Integration Flow using soapUI, the http status code 500 is fetched by the rule and the respective custom message is returned.

In the message monitor, you can see that the message has been successfully processed. An audit log entry has been added showing the rule which has been applied and the action taken.

Reply with custom message in case of a runtime exception

We would like to return a custom text whenever an exception within the REST adapter occurs. In our example, the RESTful service returns an invalid JSON format so that the conversion from JSON to XML fails. I have defined the rule as follows: Reply with custom text <error>a validation error occured</error> for source Exception.

If we call the RESTful service without having defined the rule, the message goes into a system error status. From the audit log in the message monitoring, you can see that an error validating the JSON input occured.

If we call the RESTful service with having the rule above active, the message will be delivered succesfully with the custom message as response. From the audit log you can see that the respective rule has been applied.

Reply with custom message for a particular JSON element

If the resource, here the customer, does not exist in the backend system, the field name in the response of the service call is set to NONE. We would like to return a custom text if the value of the JSON element name equals NONE. So, as source we choose JSON Expression from the drop down menu. The rule is met if the JSON Element customer.name matches the expression NONE. As action we choose Custom Result. Within the message content we use a variable in curly brackets which is replaced by the id of the customer during runtime.

When calling the REST service using the Advanced REST Client, the response in JSON format contains an element name equals NONE.

When calling the REST service via the soapUI, the respective custom message has been returned with the id derived from the request url, here 76.

Raise an error for a particular header element value

The response should be in JSON format. If an XML is returned, an error should be raised. So, we create a rule with source HTTP Header Element checking if the http header element content-type contains the term application/xml. If the rule matches, the action should be to raise an error.

When calling the REST service using the Advanced REST Client, you can see that the response is in XML format instead of JSON, and the header element content-type is application/xml instead of application/json.

When calling the REST service via the soapUI, from the audit log in the message monitor you can see that the respective rule matches, and the message is put into an error status.

Ignore error for a particular text in payload of response

In case of any timeout when calling the REST service, we would like to ignore the error. Here, we parse the payload of the response searching for the term Timeout. So, as source we choose Text Content from the drop down menu, and maintain *Timeout* as expression. As action, we select Ignore Error from the drop down menu.

When calling the REST service using the Advanced REST Client, we get an http status code 504 – Gateway Timeout. In the response payload, the reason is stated as Timeout.

When calling the REST service via the soapUI, from the audit log in the message monitor you can see that the respective rule applied, and the message is put into status Delivered.

Note: The following three scenarios are supported from release 7.31 SP17 / 7.4 SP12 / 7.5 SP01 onwards only.

Reply with custom message if response is empty

If you choose Text Content as Source, you have the option to define an action if the http result is empty. Here, select the flag Result message is empty.

Reply with custom message in case of any error

We would like to reply with a custom message whenever the http status code is not 200. The custom message should provide information about the issue of the RESTful call. Define a rule with Source HTTP Status Code, select the flag Selection does NOT match, and maintain Status Code 200. As Action choose Custom Result. In the Message Content you can use the variables http_status and http_status_text in curly brackets.

In case of an http status code 500, the rule applies and the respective http status code and text is displayed.

Always ignore errors

In case that any errors should be ignored, you can define a rule with Source Always, and Action Ignore Error.

Scenario 2 – Custom error handling on sender side

Always send an http status code 202

The following scenario is supported from release 7.31 SP17 / 7.4 SP12 / 7.5 SP01 onwards.

Instead of sending an http status code 200, you would like to send the status code 202. So, create a rule on the REST sender adapter with Source Always, Action Custom Result, and HTTP Status Code equals 202. By selecting the Use Message Payload flag you ensure that your response message is kept.

When calling the RESTful service from the Advanced REST Client Application in Chrome browser, you can see that the http status code has been set to 202.

I hope this blog was helpful to understand how the custom error handling can be used. If you like to learn more, check out the other blogs in the series, accessible from the main blog PI REST Adapter – Blog Overview.