Configure Workflow Control by Return Code Handling

WORK IN PROGRESS

Introduction

JobScheduler can manage work flow according to the results of jobs. It can use job return codes to:

• define the next job to be executed in the same job chain and
• start orders for other job chains.

Feature History

Workflow Control by return code handling was introduced with Release 1.9.0.

Issues

This feature support is subject to the following issues:

Feature Scope

Feature Implementation

The JobScheduler's next_state (true), error_state (false) and add_order commands can also be used to provide a limited control of work flow within a job chain.

Alternative commands

The JobScheduler's next_state (true), error_state (false) and add_order commands can also be used to provide a limited control of work flow within a job chain.

start_order, etc TODO

However these commands are job-specific and will be applied every time the job is called, limiting the extent to which the job can be reused.

The implementation described here is specified for a job chain node and is part of the job chain object. The implementation described is therefore independent of the job specified for a node.

Feature Logic

The feature uses the inverse logic of exit codes: an exit code of 0 is returned when a job has run successfully and all other exit codes (i.e. non 0) are returned when a job ends in error.

If the return code is 0 then the order should go to the next_state but if return code is between 1 and 5 then the order should go to the cleanup_files state. FALSCH ODER

Use Cases

• Welche Rolle ist für den Fall verantwortlich? Wer will etwas? Engineering, Operating, Business
• Was ist das Ziel? Was ist das Mittel? Was ist die Motivation?

Example: Starting an order accrding to the exit code returned by a job chain node

Consider two job chains where one of the chains will only be started if a job in the other chain has beens successfully completed.

Such a configuration is shown in the diagram below:

• JobChain0 has 6 shell jobs 1, 2 ,3, 4, 5 and 6 and JobChain1 has 2 shell jobs.
• JobChain1 should only start if Job 3 in JobChain0 ends successfully. 
• When any of the jobs in either chain ends with an exit code = 0 (i.e. successfully) it will proceed to the job defined by the next_state.
• When any of the jobs ends with an exit code other than 0 (i.e. in error) then processing of the order will stopped and the chain will go to the error_state.
• If Job 3 ends with an exit code = 0 then the Order 1 for JobChain 1 will be generated by JobScheduler and started.

Configure a job chain with return codes Delimitation TO REDO

This can be achieved by configuring the return code for the job node

1. Screenshot 1 : Open JobChain0 in the JobScheduler Object Editor, JOE 
2. Screenshot 1: Select Job 3, since we want to start the JobChain1 after if the Job3 ends successfully 
3. Screenshot 2 : Give the return code e.g. return code = 0 is success in the ReturnCodes text filed 
4. Screenshot 2 : Select the target job chain e.g. JobChain1  from the drop down list  (  only job chains present the same folder will be available in the dropdown list ) 
5. Screenshot 2 : Click on Add Order button to assign the an Order to the JobChain1 
6. Screenshot 2 : Click on Apply to make the changes in the job chain configuration
7. Screenshot 2 : Save your job chain configuration. 

Screenshot 1

Screenshot 2

Example Files

Download: JobChainReturnCodes Example working example ( Windows Version ), for Linux simply change the job's shell scripts with Linux scripts 

2nd Example TO REDO

Workflow within Job Chain

Delimitation TO REDO

Workflow in event of error is possible but does not suppress the error

•  If an order for another job chain is to be generated in the event of an error occurring in a job  ->
• If alternative job chains are to be started depending on the return code (OR) then only one of the alternatives can not result in an error (only one success code poss)

Use Cases MOVE TO BEFORE EXAMPLE

Start one or multiple job chains

Start multiple job chains ( split and sync back ) < NO??

Assign Unique Order IDs

Parameter handling

Example Exit code range

References

• Change Management References
  • JIRA Issues
• Documentation
  •  XML Element in der Referenzdokumentation

 ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

Scope

• Worum geht es? In einem Satz.
• Für welches Release? (Confluence Macro display_feature_availablity)

Use Case

• Welche Rolle ist für den Fall verantwortlich? Wer will etwas? Engineering, Operating, Business
• Was ist das Ziel? Was ist das Mittel? Was ist die Motivation?

Implementierung

• Wie ist die Lösung implementiert? Mit welchen Mitteln?

Delimitation

• Abgrenzungen, was ein Feature nicht leistet, z.B. nur für bestimmten Plattformen verfügbar
• Funktionalität, die eben nicht bereitgestellt wird
• Limitation (technische Beschränkungen)

Example

• Beispiel Code und Erläuterungen
  • Code Beispiel via Confluence Code Macro
• Beispiel Objekte
  
  • Ganze Objekte wie jobs, orders etc nur als Anhang

References

• Change Management References
  • JIRA Issues
• Documentation
  •  XML Element in der Referenzdokumentation

<job_chain
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://www.sos-berlin.com/repository/scheduler/1.9/scheduler.xsd">
    <job_chain_node state="100" job="/test-a"/>
    <job_chain_node state="200" job="/test-a">
        <on_return_codes>
            <on_return_code return_code="7..9 100..199 -99999..-1000">
                <to_state state="end"/>
            </on_return_code>
        </on_return_codes>
    </job_chain_node>
    <job_chain_node state="300" job="/test-a"/>
    <job_chain_node.end state="end"/>
</job_chain>

<?xml version="1.0" encoding="utf-8"?>
<spooler xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.sos-berlin.com/repository/scheduler/1.7/scheduler.xsd">
    <config>
        <plugins>
            <plugin java_class="com.sos.scheduler.engine.plugins.nodeorder.NodeOrderPlugin"/>
        </plugins>
    </config>
</spooler>

<?xml version="1.0" encoding="utf-8"?>
<job_chain
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://www.sos-berlin.com/repository/scheduler/1.9/scheduler.xsd"
        xsi:schemaLocation="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin NodeOrderPlugin.xsd"
        xmlns:NodeOrderPlugin="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin">
    <job_chain_node state="200" job="/test-exit-7">
        <on_return_codes>
            <on_return_code return_code="7">
                <NodeOrderPlugin:add_order NodeOrderPlugin:job_chain="test-a"/>
            </on_return_code>
            <on_return_code return_code="5">
                <NodeOrderPlugin:add_order NodeOrderPlugin:job_chain="./test-b"/>
                <NodeOrderPlugin:add_order NodeOrderPlugin:job_chain="/other-folder/test-c" NodeOrderPlugin:id="${ORDER_ID\u0022}-copy"/>
            </on_return_code>
            <on_return_code return_code="9">
                <add_order xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="/x">
                    <params>
                        <param name="a" value="AAA"/>
                        <param name="b" value="BBB"/>
                    </params>
                </add_order>
                <to_state state="end"/>
            </on_return_code>
        </on_return_codes>
    </job_chain_node>
    <job_chain_node.end state="end"/>
</job_chain>

<?xml version="1.0" encoding="utf-8"?>
<spooler xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.sos-berlin.com/repository/scheduler/1.9/scheduler.xsd">
    <config>
        <plugins>
            <plugin java_class="com.sos.scheduler.engine.plugins.nodeorder.NodeOrderPlugin"/>
        </plugins>
    </config>
</spooler>