Skip to end of metadata
Go to start of metadata

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 workflow presented below implements the use case using the following instructions:

Download (.json upload)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, 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 specifying a common delay for any retries or using individual delays for each retry.
  • The JS7 - Try-Catch Instruction 
    • executes any number of instructions and jobs within the Try Block.
      • if the jobs complete successfully then processing will continue after the Catch Block.
      • if 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 with 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 which is shown in 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 wait 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:

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.