Error/Success Handling Steps
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 (i.e., protected steps). Error/success handlers and protected steps are part of the so-called protected block (see Structure of a Protected Block below).
Depending on your business needs, you can create Execution steps, Choose, For-Each, and Postpone blocks inside a protected block. You can also nest other protected blocks blocks inside your protected block.
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.
The code listing below illustrates the structure of a sample protected block. The protected block below 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.
Types of handlers
Each handler block has a special condition, and if this condition is true, the steps of this handler will be executed. 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 retry count option (see Retry Option below). By default, this option is set to 0.
•The Always handler runs regardless of whether the steps in the protected block have been successful or not.
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 sequence has encountered an error.
In the code listing 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 (see subsection below).
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 be executed once only and no retries will be attempted.
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, e.g., 3 times (see screenshot below).
3.Click the button under the Execute with error/success handling section and add a step (or steps) that will be retried if an error occurs.
In the example below, the job, which 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.
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 (screenshot below).
In the sample job below, 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. Only if the execution of the first step fails will the On-Error handler send an email with the ID of the failed job instance in the subject line. The Always handler will be executed regardless of whether the first step has been successful or not. The Always handler will log a message by running a script from the C:\scripts directory.
For more examples, see Adding Error Handling to a Job.