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 and to catch specific exit codes.
Solution
The below workflow implements the use case from the following instructions:
Download: 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.
Explanation:
- This workflow implements
- an outer Retry Block to repeat execution,
- an inner Job Instruction that fails with varying return codes,
- an inner If Instruction to decide about the handling of specific return codes.
Job
The job is implemented to complete with varying return codes that are handled like this:
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 different types of error handling depending on the return code reported by the failed job:
Explanation:
- Within the Retry Block the JS7 - If Instruction is used to check the return code value, This value is available from the built-in
$returnCode
variable. - The first If Instruction excludes by use of the
$returnCode != 0
predicate 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 by use of the
$returnCode == 1
predicate:- 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
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 return codes 1 and 2 signaling success. This allows to later on check the return code and act accordingly by failing or retrying order execution.
At the same time this implies that the job is not considered being failed. As a result
- the JS7 - Task History classifies the job being successfully executed,
- no JS7 - Notification is created and is visible with 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.