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:

http rest legacy.errors.fault error handling
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:

http rest legacy.errors.fault error handling 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:

http rest legacy.errors.error acceptance

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:

http rest legacy.errors.retry

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.