Page History

Table of Contents

	outlinh1. true
	outlinh1. true
1	printablefalse
2	stylh1. none
3	indent20px

StatuscolourYellowtitleWork in ProgressNote that on_return_code elements are specified for the job chain node and not for the job, which is a child element of the node in the configuration. This allows jobs to be reused in other job chains with a different workflow control configuration.

Introduction

JobScheduler can manage work flow workflows according to the results of jobs, i.e. their return codes. It can use job return codes to:

define the next job node to be executed in the same job chain,
dynamically generate order parameters and
start orders for other job chains.

Feature History

Workflow Control by return code handling was introduced with Release

Display feature availability

StartingFromRelease

1.9

.0.

Issues

This feature Feature support is subject to the following issues:

Jira

server	SOS JIRA
columns	key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution,fixversions
serverId	6dc67751-9d67-34cd-985b-194a8cdc9602
key	JS-1190

Jira

server	SOS JIRA
columns	key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
maximumIssues	20
jqlQuery	issue = js-1193 or issue = js-1190
serverId	6dc67751-9d67-34cd-985b-194a8cdc9602

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

Status

colour	Yellow
title	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.

...

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.

Image Removed

...

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

Screenshot 1 : Open JobChain0 in the JobScheduler Object Editor, JOE
Screenshot 1: Select Job 3, since we want to start the JobChain1 after if the Job3 ends successfully
Screenshot 2 : Give the return code e.g. return code = 0 is success in the ReturnCodes text filed
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 )
Screenshot 2 : Click on Add Order button to assign the an Order to the JobChain1
Screenshot 2 : Click on Apply to make the changes in the job chain configuration
Screenshot 2 : Save your job chain configuration.

Screenshot 1

Image Removed

Screenshot 2

Image Removed

Example Files

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

...

Workflow within Job Chain

...

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
Status
colour Yellow
title Move to before Example

Start one or multiple job chains

...

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

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

JS-1190 - Control the workflow of a job chain by exit codes

Workflow Control
This feature allows to configure the next job node in a job chain for a range of exit codes of the current job.

In addition to controlling the workflow by next_state (true) and error_state attributes the exit code of shell processes can be used directly. The return values true and false of API tasks are are mapped to the same result as exit code 0 (success) and 1 (error).

Use Cases

If the exit code of the current task returns 3 then the next state for the order should be the error state. Other exit codes are considered to represent the successful execution of the task.
If the exit code of the current task returns one of the values 3-9 then the order should be assigned a specific state and should be continued by the respective job node.

Examples

<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>

Explanations

Should the element <to_state> be missing, then JobScheduler will apply the job_chain_node/@next_state or job_chain_node/@error_state attribute.
For return_code single values can be specified and closed intervals [i, j] separated by spaces, e.g. "1..5 7 12..15".
Each return code can only be used once..
The attributes next_state and error_state are applied if no on_return_code element is used.
Should no <on_return_code> element match the current return code then JobScheduler will apply the job_chain_node/@next_state (return code 0) or job_chain_node/@error_state (other return codes) attribute.

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

JS-1193 -Start of an order should be possible depending on the result of a task of a job chain node

Plugin

A Plugin is provided that handles the return code of a previous job node:
```
<NodeOrderPlugin:add_order NodeOrderPlugin:job_chain="/test-b"/>
```
The following modes are available for the handling of the Order ID when adding orders:
- If no Order ID is specified then the order receives the Order ID of the current order. A different job chain has to be specified and that job chain must not contain an order with same Order ID.
- The order is assigned an individual Order ID and job chain (which includes assigning the current job chain). The Order ID of the current order can be referenced by using the variable $ {ORDER_ID}
  .
- Examples
  - <add_order job_chain="..."/> adds an order with the same Order ID as the current order to a different job chain.
  - <add_order id=“${ORDER_ID}.1” job_chain="..."/> adds an order with parts of the Order ID being created from a reference to the Order ID of the current order. The current job chain or a different job chain can be used.
The handling of parameters is applied as follows:
- A newly added order receives a copy of the parameters of the current order.
- Additional parameters can be added by using the elements <add_order><params><param name="..." value="..."/>.... Additional parameters have precedence to parameters of the current order.
Any errors when adding the order to the job chain are logged and ignored.

Configuration
Following configuration has to be applied to scheduler.xml to enable the corresponding plugin:

<?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>

Complete sample job chain

...

key	JS-1193

Use Cases

Workflow control by job return codes allows conditional job chain execution and the representation of more dynamic and complex processes than was previously possible with JobScheduler.

The return codes from individual jobs in a job chain can be used to:

dynamically generate orders to start alternative job chains and, if required, assign order parameters and
extend the range of error handling possibilities by allowing orders to jump/skip nodes in the current job chain.

Scope of workflow control

Implementation

A return code of 0 is returned when a job has run successfully and all other return codes (i.e. non 0) are returned when a job ends in error.

In addition, whereas by default a non-zero return code causes the JobScheduler to log an error for the job and to move the order to the error state, return code handling can be used to continue processing of the order without logging an error for the order.

Workflow control has been implemented to use individual return codes (0, 1, 2, etc.) or return code ranges (1-5, 6-9, etc.).

A typical implementation of this feature within a job chain could be:

a return code of 0 causes an order to move to the next_state in the job chain.
a return code between 1 and 5 causes the order to move to some other state defined for the job chain.
a return code between 6 and 9 causes the order to proceed to the error_state.

A typical implementation involving additional job chains could be:

a return code of 0 will cause an order to move to the next_state in the job chain and to generate an additional order for the same or some other job chain.
a non-zero return code causes an order to proceed to the error_state.

Alternative commands

The JobScheduler's next_state (true), error_state (false) define the default behavior of the job chain as described above.

XML commands such as add_order and modify_job can also be used to provide a limited control of workflow within a job chain. 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. For more information see:

the How to configure the handling of exit codes by jobs article
the JobScheduler <job_chain_node.job_chain> Element reference

Feature comparison

The implementation of return_codes is specified for a job chain node and is part of the job chain object. The implementation of on_return_codes is therefore independent of the job specified for a node and can be used more flexibly than commands such as add_order.

Example: Starting an order and skipping nodes according to the return code returned by a job chain node

Demonstration Files

Download: JobChainReturnCodes Example 1 working example (Windows Version), for Linux simply modify the shell scripts.

Unpack the configuration in the JobScheduler's live folder. See our series of Tutorials for information getting JobScheduler installed and running.

The configuration can now be:

inspected - and edited if required - using in the JOE - JobScheduler Object Editor
run using the JOC - JobScheduler Operations Center.

Example

Use Case

Consider two job chains where the return code for a job in one of the chains is used to control further workflow as follows:

If the job configured to control the workflow runs successfully then:
- an order for another job chain will be generated and started and
- the order for the original job chain will proceed to the next node for the chain.
If the job configured to control the workflow does not run successfully then:
- the order for the other job chain will not be be generated
- processing of the order for the original job chain will 'skip' to an alternative chain node.

Example configuration

A configuration as described in the previous section is shown in the diagram below:

JobChainA has 6 shell jobs 1, 2 ,3, 4, 5 and 6 and JobChainB has 2 shell jobs.
If Job3 in JobChainA ends successfully (i.e. its shell script ends with a return code = 0):
- .An order will be generated for JobChainB and the order started.
- The order running on JobChainA should proceed to the next node configured for the chain (Job4).
If Job 3 in JobChainA ends in error, i.e. its shell script ends with a return code between 1 and 5, then:
- No order for JobChainB should be generated.
- The order running on JobChainA should skip two processing steps (Jobs4 and Job5) and proceed to the last node in the chain (Job6).

Image Added

Processing return codes

The configuration of the return codes takes place in one of two ways:

The standard progression of an order along a job chain is as follows:
- When any of the jobs in either chain ends with an return code = 0, i.e. successfully, the order will proceed to the node defined by the next_state.
- When any of the jobs ends with an return code other than 0, i.e. in error, then processing of the order will be stopped and the order will proceed to the error_state.
- For more information about the principles of the jobs, job chains and orders elements used to configure JobScheduler workflows see our series of Jobs, Job Chains and Orders articles.
Workflow control is activated by specifying one or more on_return_code elements for a job chain node.
A match of a job return code and a return_code attribute specified for will cause the behavior(s) specified for the on_return_code element to be carried out.
Generation of the order to start JobChainB:
If Job3 in JobChainA ends with an return code = 0 then an order for JobChainB will be generated by the JobScheduler and started. This is configured using an add_order element.
By default the generated order will have the ID of the originating order.
By default the generated order will have the parameters set for the originating order.
Skipping nodes in the current job chain:
If Job3 in JobChainA ends with a non-zero return code (in the example between 1 and 5) and a to_state element is set then JobScheduler behaves as follows:
Job3 will be set to the error_state.
The order will not proceed to the error_state but to the state specified in the state attribute of the to_state element.
In the example this is 6 for Job6 as shown in the diagram above.
If no further jobs in the job chain end with a non-zero return code then the order will end with the success state.

Example Job Chain Operation

Two orders are available for the example configuration, with each order carrying a parameter named orderParameter. This parameter is read by the shell script in Job3 in JobChainA and used to set the return code for this job:

The orderParameter for Order0 has the value 0 and
the orderParameter for Order1 has value 1.

The behavior of the example configuration for each order will be as described in the previous section.

Running the Example Orders

The orders can be started in the Job Chains tab of the JobScheduler Operating Center (JOC) using the Start order now command as shown in the screenshot below:

Image Added

Run both Order 1 and Order 2 and then open their log files using the Show log link shown in the Order History pane as in the next screenshot:

Image Added

The code block below can be opened to show part of the log file for Order0. This shows the log information for Job3 and the start of Job4. The following points are relevant:

The order_parameter value of 0 is shown in Line 58 of the listing.
Line 71 shows that Job3 is exiting with return code 0.
The end of processing of the node for Job3 is noted in line 72.
Line 74 shows that the state is set for starting Job4 - there is no mention of the generation of the order that will start JobChainB.

Code Block

language	text
title	Log output - Order0, JobChainA (Job3)
firstline	47
linenumbers	true
collapse	true

[info]   set_state 3, Job /Examples/JobChainReturnCodes/Job3
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) SCHEDULER-842  Task is going to process Order Examples/JobChainReturnCodes/JobChainA:Order0 "JobChainA - parameter value 0", state=3, on JobScheduler 'http://AA-Win7:4110', Order's Process_class
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) 
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) Task Examples/JobChainReturnCodes/Job3:92842 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes,Job3.log
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) SCHEDULER-918  state=starting (at=never)
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) Configuration File: C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10\config\live\Examples\JobChainReturnCodes\JobChainA.config.xml not found (Probably running on an agent).
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) Reading configuration from xml payload...
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) SCHEDULER-987  Starting process: "C:\Windows\TEMP\\sos-F7DE9FD90F.cmd"
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) SCHEDULER-726  Task runs on this JobScheduler 'http://AA-Win7:4110'
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] Job3 : job starting 
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] .                                    
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] order_parameter = "0"                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>set /a number=28451 %2 +1  
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] Job3 : sleeping for 2 seconds..... 
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>ping 127.0.0.1 -n 2  1>nul  
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] Job3 : job ending exit 0 
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>exit 0 
[info]   (Task Examples/JobChainReturnCodes/Job3:92842) SCHEDULER-843  Task has ended processing of Order Examples/JobChainReturnCodes/JobChainA:Order0 "JobChainA - parameter value 0", state=3, on JobScheduler 'http://AA-Win7:4110'
[info]   set_state 4, Job /Examples/JobChainReturnCodes/Job4
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) SCHEDULER-842  Task is going to process Order Examples/JobChainReturnCodes/JobChainA:Order0 "JobChainA - parameter value 0", state=4, on JobScheduler 'http://AA-Win7:4110', Order's Process_class
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) 
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) Task Examples/JobChainReturnCodes/Job4:92843 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes,Job4.log
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) SCHEDULER-918  state=starting (at=never)
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) SCHEDULER-987  Starting process: "C:\Windows\TEMP\\sos-F7DEF0E7B2.cmd"
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) [stdout] Job4 : job starting 
[info]   (Task Examples/JobChainReturnCodes/Job4:92843) [stdout]

The next code block shows part of the log file for Order1. This shows the log information for Job3 and the start of Job6. The following points are relevant:

Line 68 of the listing shows that Job3 is exiting with return code 1.
Line 69 shows that an error has been logged.
The end of processing of the node for Job3 is noted in line 70.
Line 72 shows that the state is set for starting Job6 - the job at the node specified in the to_state element that was configured for node 3.

Code Block

language	text
title	Log output - Order1, JobChainA (Job 3)
firstline	43
linenumbers	true
collapse	true

[info]   set_state 3, Job /Examples/JobChainReturnCodes/Job3
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-842  Task is going to process Order Examples/JobChainReturnCodes/JobChainA:Order1 "JobChainA - parameter value 1", state=3, on JobScheduler 'http://AA-Win7:4110', Order's Process_class
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) 
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) Task Examples/JobChainReturnCodes/Job3:92853 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes,Job3.log
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-918  state=starting (at=never)
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) Configuration File: C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10\config\live\Examples\JobChainReturnCodes\JobChainA.config.xml not found (Probably running on an agent).
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) Reading configuration from xml payload...
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-987  Starting process: "C:\Windows\TEMP\\sos-F85292D6E1.cmd"
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-726  Task runs on this JobScheduler 'http://AA-Win7:4110'
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .

...


[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] Job3 : job starting 
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .

...

     
[info]

...

(Task Examples/JobChainReturnCodes/Job3:92853) [stdout] order_parameter = "1"

...

Explanations

The NodeOrderPlugin allows to specify absolute and relative paths for job chains. Relative paths are based on the location of the current job chain.
Multiple orders (in different job chains) can be started for the same return code.
The job chain path of the new order can be used relative to the current job chain. Just let the path start with "./".
Mixed usage for orders that should be added and for the job node state that an order should move to is possible.

To use the plugin, it has to be included in the JobScheduler configuration file scheduler.xml:

...

                          
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>set /a number=31044 %2 +1  
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .

...


[info]   (Task

...

Examples/

...

Restriction

JobChainReturnCodes/Job3:92853) [stdout] Job3 : sleeping for 1 seconds..... 
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>ping 127.0.0.1 -n 1  1>nul  
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] Job3 : job ending exit 1 
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>exit 1 
[ERROR]  (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-280  Process terminated with exit code 1 (0x1)
[info]   (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-843  Task has ended processing of Order Examples/JobChainReturnCodes/JobChainA:Order1 "JobChainA - parameter value 1", state=3, on JobScheduler 'http://AA-Win7:4110'
[info]   set_state 6, Job /Examples/JobChainReturnCodes/Job6
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) SCHEDULER-842  Task is going to process Order Examples/JobChainReturnCodes/JobChainA:Order1 "JobChainA - parameter value 1", state=6, on JobScheduler 'http://AA-Win7:4110', Order's Process_class
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) 
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) Task Examples/JobChainReturnCodes/Job6:92854 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes,Job6.log
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) SCHEDULER-918  state=starting (at=never)
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) SCHEDULER-987  Starting process: "C:\Windows\TEMP\\sos-F852B1C77B.cmd"
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) [stdout] .                               
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) [stdout] Job6 : job starting

The next code block shows the last few lines of the log file for Order1. Line 99 of the listing shows that despite the error recorded as Job3 ended, the order is set to the success state.

Code Block

language	text
title	Log output - Order1, JobChainA (Job 6 - set_state Success)
firstline	95
linenumbers	true
collapse	true

[info]   (Task Examples/JobChainReturnCodes/Job6:92854) [stdout] Job6 : job ending 
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) [stdout] .
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) SCHEDULER-915  Process event
[info]   (Task Examples/JobChainReturnCodes/Job6:92854) SCHEDULER-843  Task has ended processing of Order Examples/JobChainReturnCodes/JobChainA:Order1 "JobChainA - parameter value 1", state=6, on JobScheduler 'http://AA-Win7:4110'
[info]   set_state Success
[info]   SCHEDULER-944  End state reached - order will be repeated at 2038-01-19 03:14:07.000Z with state=1
[info]   SCHEDULER-962  Protocol ends in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/order.Examples,JobChainReturnCodes,JobChainA.Order1.log

Part of the log file for JobChainB, which only starts when Order0 is run, is shown in the next code block. Only the log information for Job6 is shown in the listing. It can be seen that:

The ID from the order generating the order for has been taken over by default. This is shown in the listing in line 24.
The order_parameter value from Order0 on JobChainA has also been taken over and shown in line 36.
The parameter_job_3 parameter, which is set with value "ParameterReturnCodeJob3" is shown in line 33. This parameter was set in the on_return_code element at the node for Job3 in JobChainA.

Code Block

language	text
title	Log output - Order0, JobChainB (Job6)
firstline	23
linenumbers	true
collapse	true

[info]   set_state 2, Job /Examples/JobChainReturnCodes/Job6
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) SCHEDULER-842  Task is going to process Order Examples/JobChainReturnCodes/JobChainB:Order0, state=2, on JobScheduler 'http://AA-Win7:4110', Order's Process_class
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) 
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) Task Examples/JobChainReturnCodes/Job6:92845 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes,Job6.log
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) SCHEDULER-918  state=starting (at=never)
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) SCHEDULER-987  Starting process: "C:\Windows\TEMP\\sos-F7DF14AB5D.cmd"
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] Job6 : job starting 
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] .                                    
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>echo parameter_job_3 = "ParameterReturnCodeJob3"  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] parameter_job_3 = "ParameterReturnCodeJob3" 
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>echo order_parameter = "3"  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] order_parameter = "3" 
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] .                                      
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>set /a number=28461 %2 +1  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] .  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] Job6 : sleeping for 2 seconds..... 
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout]  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>ping 127.0.0.1 -n 2  1>nul  
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] .                                       
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] Job6 : job ending 
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] .
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) SCHEDULER-915  Process event
[info]   (Task Examples/JobChainReturnCodes/Job6:92845) SCHEDULER-843  Task has ended processing of Order Examples/JobChainReturnCodes/JobChainB:Order0, state=2, on JobScheduler 'http://AA-Win7:4110'
[info]   set_state Success
[info]   SCHEDULER-945  No further job in job chain - order has been carried out
[info]   SCHEDULER-940  Removing order from job chain

Configuring the example return codes

This is done in the Nodes tab of the JobScheduler Object Editor JOE for JobChain0 as shown in Screenshot 1 below.
(A more detailed description of how to use JOE to configure a job chain can be found in JobScheduler Tutorial 2 - Editing a Simple Job with JOE.)

The standard progression through the job chains is configured in the NextState and ErrorState fields of the form.
Generation of the order to start JobChain1 is configured as shown in the screenshot:
1) Select Job3 since we want to start JobChain1 if this job ends successfully
2) Click on the Return Codes button to open the Return Code configuration form

Screenshot 1

Image Added

1) Give the return code, e.g. return_code = 0 signals success, in the ReturnCodes field
Syntax:
Individual return codes are separated by spaces (e.g. 1 2).
Return code ranges are inclusive and written 1..5 6..9
Return codes can only be specified once
Behavior:
Note that non-zero return codes can be used but will be seen as an errors in the originating job chain.
Should no <on_return_code> element match the current return code then JobScheduler will apply the job_chain_node@next_state (return code 0) or job_chain_node@error_state (other return codes) attribute.
2), 3) Select the target job chain e.g. JobChain1 from the drop down list
only job chains present in the same folder will be available in the Job Chain dropdown list
Other job chains can be:
navigated to using the Browse button.
specified using the syntax: /myFolder/myJobChain.
4) Click on Add Order button to assign the Order to the JobChain1
5) Click on Apply (at the foot of the form)to make the changes in the job chain configuration
Save the job chain configuration.

Screenshot 2

Image Added

Example Job Chain Code

Code Block

language	xml
title	JobChainA with return code parameters

<job_chain  title="JobChain A">

    <job_chain_node  state="1" job="Job_1" next_state="2" error_state="Error"/>

    <job_chain_node  state="2" job="Job_2" next_state="3" error_state="Error"/>

    <job_chain_node  state="3" job="Job_3" next_state="4" error_state="Error">
        
        <on_return_codes >
            <on_return_code  return_code="1..5">
                <to_state  state="6"/>
            </on_return_code>

            <on_return_code  return_code="0">
                <add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainB">
                    <params >
                        <param  name="parameterJob3" value="Parameter from Job3 - RC=0"/>
                    </params>
                </add_order>
            </on_return_code>

            <on_return_code  return_code="1">
                <add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainB">
                    <params >
                        <param  name="parameterJob3" value="Parameter from Job3 - RC=1"/>
                    </params>
                </add_order>
            </on_return_code>

        </on_return_codes>

    </job_chain_node>

    <job_chain_node  state="4" job="Job4" next_state="5" error_state="Error"/>

    <job_chain_node  state="5" job="Job5" next_state="6" error_state="Error"/>

    <job_chain_node  state="6" job="Job6" next_state="Success" error_state="Error"/>

    <job_chain_node  state="Success"/>

    <job_chain_node  state="Error"/>

</job_chain>

Limitations of use

Overlapping return codes

Avoid creating overlapping return codes and/or overlapping return code ranges.

Overlapping return codes should not be used to create multiple orders.
This is automatically corrected in JOE but is possible when configuration is carried out with a code editor.
Code Block
language xml
title Example showing 'overlapping' of return-codes
collapse true
 <on_return_code return_code="3"> <add_order xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainC"/> </on_return_code> <on_return_code return_code="3"> <add_order xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainD"/> </on_return_code>  <on_return_code return_code="3"> <add_order xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainC"/> <add_order xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainD"/> </on_return_code>

Overlapping return code ranges should not be be used.

This is currently possible in JOE (versions 1.9.7, 1.10.1).

Code Block

language	xml
title	Example showing 'overlapping' of return-code ranges
collapse	true

<!-- do not use overlapping return code ranges -->
<on_return_code  return_code="3">
	<add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainC"/>
	<to_state  state="6"/>
</on_return_code>

<on_return_code  return_code="1..3">
	<add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainD"/>
</on_return_code>

<!-- use a number of return code configurations -->
<on_return_code  return_code="3">
	<add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainC"/>
	<add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainD"/>
	<to_state  state="6"/>
</on_return_code>

<on_return_code  return_code="1..2">
	<add_order  xmlns="https://jobscheduler-plugins.sos-berlin.com/NodeOrderPlugin" job_chain="JobChainD"/>
</on_return_code>

<on_return_code> matching limitations

Identical return code values are matched when a configuration is being generated in the JobScheduler Object Editor JOE.

This means that when a behavior (to_state or add_order) is specified for a single return code value and/or range of values or any combination thereof and another behavior is specified for exactly the same return code(s) then both will be included in the same on_return_code element and both behaviors will be carried out.

However, if there is a slight 'mismatch' of return codes - for example, if a behavior is specified for a return code of 3 and a second behavior for a return code range of 3..5 then these behaviors will be saved in different on_return_code elements.

JobScheduler executes on_return_code elements one after the other and executes any element containing a to_state attribute first. This means that of a job ends with a return code that is matched by a number of on_return_code elements, only the element with a to_state attribute will be executed as once this has been done, the order will no longer be at the original state to execute any further on_return_code elements.

References

Change Management References

Jira

server	SOS JIRA
columns	type,key,issuelinks,fixversions,status,priority,summary,updated
maximumIssues	20
jqlQuery	labels in (return-code)
serverId	6dc67751-9d67-34cd-985b-194a8cdc9602

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 2

New Version Current

Key

Introduction

Feature History

Issues

Feature Scope

Feature Implementation

Alternative commands

Feature Logic

Use Cases

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

Screenshot 1

Screenshot 2

Example Files

Use Cases StatuscolourYellowtitleMove to before Example

Start one or multiple job chains

Assign Unique Order IDs

Parameter handling

Example Exit code range

References

Scope

Use Case

Implementierung

Delimitation

Example

References

Use Cases

Scope of workflow control

Implementation

Alternative commands

Feature comparison

Example: Starting an order and skipping nodes according to the return code returned by a job chain node

Demonstration Files

Example

Use Case

Example configuration

Processing return codes

Example Job Chain Operation

Running the Example Orders

Configuring the example return codes

Screenshot 1

Screenshot 2

Example Job Chain Code

Limitations of use

Overlapping return codes

<on_return_code> matching limitations

References

Change Management References

See also

Use Cases
Status
colour Yellow
title Move to before Example