Altova FlowForce Server 2023 Advanced Edition

When a step of a job fails, the job is considered failed as well. To perform some clean-up actions before the job exits (such as logging or sending email notifications), you can create error/success handling steps. These steps allow you to protect the execution of one or more steps that are part of the so-called protected block. The diagram below illustrates the structure of a sample protected block.

fs_retry_on_error

The protected block above consists of the protected steps (Steps A and B) and the error/success handlers (Steps C, D, E and F). Whenever the protected sequence has been executed (successfully or with an error), the handler blocks will be executed next. Each handler block has a special condition, and if this condition is true, the steps of this handler will be executed.

 

Types of handlers

Error/success handlers are listed below:

 

The On-Error block is executed whenever an error occurs inside the block.

The On-Success block runs if all steps in the protected block have been successful.

The On-Retry handler runs if any of the steps in the protected block has failed. The handler runs as many times as specified in the the retry count option. By default, this option is set to 0.

The Always handler runs regardless of whether the steps in the protected block have been successful.

 

Order of handler execution

Handler blocks are always executed in the specified order. For example, if there is an Always block followed by an On-Error block, which is in turn followed by another Always block, the two Always blocks will be executed in the order specified whenever the protected sequence has finished executing. The On-Error block will run after the first Always block only if the protected block has finished executing with an error.  

 

In the diagram above, if Step A or B fails, the protected sequence is left, and Steps C and F are guaranteed to be executed (because they are On-Error and Always, respectively). Step D will be executed only when retries are left. For more information about the On-Retry block, see the subsection below.

 

Add an error/success handler

To add an error/success handler, create a job or open an existing job, and click new Error/Success handling step. Then select the relevant error/success handling step.

 

On-Retry

There are cases, in which you may want to run a step again if its execution has failed. For this purpose, FlowForce Server provides the Retry option. By default, this option is set to 0, which means that the protected block will execute once only and no retries will be attempted.

 

The on-retry blocks are executed only if the protected sequence has retries left. The actual retry will start only after all the handler blocks have been successfully executed and only if the protected sequence has been left because of an error. When no retries are left, the error is re-raised outside of this protected block and might be observed by further protected blocks.

 

To add an execution step that will be retried a certain number of times, follow the instructions below:

 

1.Click new Error/Success handling step on the job configuration page.

2.Specify the number of retries you need (see screenshot below).

3.Click the add button under the Execute with error/success handling section and add an execution step that is to be retried if an error occurs.

 

In the example illustrated below, a job that uploads a file to an FTP server will be retried 3 times on error. The number of retries of any given job instance is reported in the log. In addition, if you need to get and process the number of retries at runtime, call the retry-count expression function.

fs_retry_on_error_03

 

Example

In practice, it is not necessary to define all three handler types for every job. The most common scenario is to define only On-Error and Always handlers. For example, the image below illustrates a simple protected block with the On-Error and Always handlers.

fs_protected_block_01

The first step runs a script from the C:\scripts directory by calling the \system\shell\commandline function. The execution of this step is protected by two handlers: On-Error and Always. The On-Error handler will be triggered only if the execution of the first step fails. More specifically, the error handling step will send an email that contains the ID of the failed job instance in the subject line.

 

The Always handler will be executed unconditionally, regardless of whether the first step has been successful or not. This handler will log a message by running a script from the C:\scripts directory.

 

For more examples, see Adding Error Handling to a Job.

 

© 2016-2022 Altova GmbH