Introduction

Assume Consider the following scenario:

• A number of jobs are executed in sequence.
• If one or more jobs fail with exit return code 1 then the these jobs should be repeated for a number of times. For any other non-zero exit 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 described in the  JS7 - How to retry a job and to catch specific exit codes article.

...

Solution

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

• JS7 - Retry Instruction
• JS7 - If Instruction

Download (.json upload): retry-on-return-code.workflow.json

Retry Block

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

...

Image Modified

Explanation:

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

Try Block

...

Job

The job is implemented to complete with varying return codes which are handled like this:

Image Added

Explanation:

• Return code 0 signals success and the job will continue after the Retry-End Instruction.
• Return code 1 and 2 similarly are considered successful, however, they are handled by the subsequent If Instruction.

If Instruction

The JS7 - If Instruction applies

Image Removed

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

:

Image AddedImage Removed

Explanation:

• Within the Catch Retry Block the JS7 - If Instruction is used to check the return code value, This value is available with the built-in $returnCode variable.
• The first If Instruction uses the $returnCode != 0 predicate to exclude any successful orders from the nested If Instruction. For details about predicates, see JS7 - Expressions for Variables.
• The second If Instruction determines the error handling using the $returnCode == 1 predicate value which 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.

Left Fail Instruction

...

Image Modified

Explanation:

• The left Fail Instruction fails the order with a return code value 1.
• In addition, a message can be 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

Image Modified

Explanation:

• The right Fail Instruction fails the order with a return code value 2.
• In addition, a message can be 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 interventionwait for user intervention.

Implications

In this scenario the job is configured to consider return codes 1 and 2 as signaling success. This allows the return code to be checked and appropriate action to be taken by either failing or retrying order execution.

At the same time this implies that the job is not considered to have failed. As a result:

• the JS7 - Task History classifies the job being successfully executed,
• a JS7 - Notifications will neither be created nor visible in the JS7 - Monitor view.

These implications might reflect what some users need. For an alternative solution that fails the offending job and that creates notifications see JS7 - How to retry a job and to catch specific exit codes.