Getting started with invocation error handling
| This page is legacy documentation. For the current HTTP REST connector, see its dedicated section. |
Semarchy xDI offers the possibility to handle web services invocation failures with several mechanisms, such as the possibility to retrieve and handle seamlessly invocation failures or implementing a retry behavior for re-attempting failed invocations.
This article explains how those mechanisms are working and how to use them in Mappings to use it.
Generalities
When invoking SOAP or REST web services several things have to be in mind about invocation error handling.
Are invocations errors accepted and handled in the Mapping or does the session have to end with errors after a defined amount of tolerated errors?
When an invocation fails should the Runtime retry invoking it?
Everything can be configured directly on web service invocation template through the available parameters.
The following parameters are the important ones for error handling:
| Parameter | Description |
|---|---|
Delay Between Invocations |
Delay in millisecond between each invocation of the web service. As a reminder the web service is invoked for each source row based on the specified repetition key. |
Retry Number |
Specifies the number of retry to perform when an invocation fails. The failed invocation will be re-executed the amount of time specified until it succeed. When the amount of retry is reached, the Runtime will stop attempting to perform the invocation and go to the next one. |
Retry Delay |
Delay in millisecond to wait between each retry when an invocation fails. When an invocation fails, and a Retry Number is specified, the invocation will be re-executed a certain amount of time, waiting between each of them the delay specified in this parameter. When this parameter is not set, the value specified in the 'Delay Between Invocations' parameter is used instead. |
Error Acceptance Number |
Number of failed invocations tolerated when invoking a web service. The execution will stop as soon as this value is reached. The default value when not set is -1 (no error limit). Important: An invocation is considered as an error if, even after all the retries, it is still failing. |
About type of errors
An invocation can fail because of two types of error:
-
technical errors: such as a network connection issues
-
functional errors: such as a web service returning an error because the inputs are incorrect for instance Depending on the type of error, the error handling behavior will be different, and explained further in the article.
About number of tolerated errors
As explained on the description of Error Acceptance Number parameter the default behavior is to accept all invocation failures and continue invocations for all source rows.
This mechanism allows to handle easily functional errors, offering the possibility to retrieve the response of the web service and store it in a table.
Here is an example of error handling Mapping:
| We are using here target filters to load a table or the other based on a specified filter. In this example we are simply splitting the flows based on if there is customer id returned or not. |
When the execution is finished we can see the number of successful and unsuccessful invocations in statistics:
This is the case where invocation failures are allowed and handled directly in the Mapping.
If you do not want the Mapping to succeed if there are invocation failures, specify the amount of tolerated errors on the template:
|
In this example we specified one accepted error in the parameter. This means that if there are only one error or less during invocations the Mapping will succeed. If the number of invocation failures exceed one failure, the execution will stop and the Mapping fail. |
About technical errors
When a technical error occurs, such as a network issue, incorrect hostname or port, unavailable service, … the execution will stop directly and not continue with next invocations.
The "Error Acceptance number" is not taken into account in this case because such technical issues cannot be handled directly by users in Mappings for instance, as the invocation is not performed at all.
However, the retry mechanism can be used to attempt again invocations a defined amount of time, which can help for temporary network issues for instance.
About retry mechanism
The Template offers the possibility to enable a retry mechanism for failed invocations.
For this, specify a Retry Number and, optionally, a Retry Delay.
Then, when an invocation fails, attempts to re-execute it will be performed the specified amount of time until it succeeds.
As soon as an retry attempts succeed the Runtime will stop performing retries for the given invocation and goes to next invocation.
When the amount of retry is reached without succeeding, the Runtime will stop attempting to perform the given invocation and go or not to the next one depending on the "Error Acceptance Number" presented in the previous part.
Example:
We also specified a Retry Delay in this example, to wait two seconds between each retry attempts.
About functional and technical errors
The retry mechanisms works for both types of errors.
The only difference is for technical issue: if the invocation is still failing after performing all the retry attempts, the execution will stop and not continue next invocations, as explained previously in the "About technical errors" part.
Previous versions behaviors
Error handling behaviors were different in Runtime versions prior to S17.6.2.
It has been revised since S17.6.2 to be clearer, more intuitive, and more consistent between REST and SOAP.
For history, previous behaviors are presented below.
Error handling behaviors in Runtime versions prior to S17.6.2
The Error Acceptance Number worked the same way with the difference that retries were performed only when this number was reached.
When the number of errors was reached the Runtime was then starting to perform retries.
For REST Web Services invocations, the execution stopped after performing the retries if the invocation was still failing after all the attempts.
For SOAP Web Services invocations, the execution continued next invocations after performing the retries if the invocation was still failing after all the attempts.
From S17.6.2 the retries are not linked anymore to the Error Acceptance Number, they are performed independently for each invocation, and the behavior is the same between REST and SOAP invocations.