Introduction

Assume the following scenario:

• A number of jobs are executed in sequence.
• If one or more jobs fail with return code 1 then the jobs should be repeated for a number of times. For any other non-zero return codes the order should be put to a failed state and should wait for user intervention, for example to resume or to cancel the failed order.
• A related scenario is available from JS7 - How to retry a job in case of specific exit codes.

Solution

The below workflow implements the use case from the following instructions:

• JS7 - Retry Instruction
• JS7 - Try / Catch Instruction
• JS7 - If Instruction

Download: retry-on-return-code.workflow.json

Retry Block

A Retry Block includes any number of jobs or instructions. If one of them fails then processing will be repeated from the beginning of the block.

Explanation:

• This workflow implements
  • an outer Retry Block to repeat execution,
  • an inner Try / Catch Block to handle return codes of the job,
  • an If Instruction to decide about the handling of specific return codes.

Try Block

The Try Block inside a Try / Catch Instruction includes any number of jobs or instructions. If one of them fails then processing will be continued with the Catch Block.

Explanation:

• After a first job job1 the job2 should be restarted for a number of times if it fails with return code 1.
• The JS7 - Retry Instruction manages the retry capability and the intervals.
  • The properties of the Retry Instruction include to specify a common delay for any retries or to use individual delays per retry.
• The JS7 - Try / Catch Instruction 
  • executes any number of instructions and jobs within the Try Block.
    • Should the jobs complete successfully then processing will continue after the Catch Block.
    • Should jobs fail then the instructions and jobs inside the Catch Block will be executed.

Catch Block

The Catch Block is executed in case of failed instructions or jobs in a Try Block.

The solution makes use of an JS7 - If Instruction to apply different types of error handling depending on the return code reported by the failed job.

If Instruction

Explanation:

• Within the Catch Block the JS7 - If Instruction is used to check the return code value. This value is available from the built-in $returnCode variable.
• The If Instruction evaluates the return code by use of the $returnCode == 1 predicate. For details about predicates, see JS7 - Expressions for Variables.
• The evaluation result gives two options:
  • if the return code value is 1 then the left branch (true) of the If Instruction is used,
  • for any other return code values the right branch (false) is used.
• Subsequently we find two occurrences of a JS7 - Fail Instruction.

Fail Instruction

Left Fail Instruction

Explanation:

• The left Fail Instruction fails the order with a return code value 1.
• In addition, a message is added that becomes visible with the JOC Cockpit GUI for the failed order.
• As a consequence the failed order is immediately picked up by the outer Retry Instruction that will repeat execution of job1 having applied the indicated delay.

Right Fail Instruction

Explanation:

• The right Fail Instruction fails the order with a return code value 2.
• In addition, a message is added that becomes visible with the JOC Cockpit GUI for the failed order.
• The uncatchable checkbox is used to indicate that the failed order cannot be picked by the outer Retry Instruction. Instead, the order will remain with its current position in a failed state and waits for user intervention.

Implications

In this scenario the job is configured to consider any non-zero return code signaling failure. This requires use of a Try / Catch Instruction to handle errors.

This implies that

• the JS7 - Task History classifies the job being failed,
• a notification is created for each failed execution that is visible from the JS7 - Monitor view and that can be forwarded by use of a JS7 - Notification.

These implications might reflect what some users need. For an alternative solution that does not fail the offending job and that does not create notifications see JS7 - How to retry a job in case of specific exit codes.