Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Note 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 workflows according to the results of jobs, i.e. their return codes. It can use job return codes to:
...
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
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.
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 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
Workflow control using return codes uses the inverse logic of return codes: an 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.
...
- a return code of 0 causes an order to move move to the next_state in the job chain.
- a return code between 1 and 5 causes the order to move to the cleanup_files some other state defined for the current 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 order for an additional additional order for the same or some other job chain.
- a non-zero return code causes an order to proceed to the error_state and start a second, error handling job chain.
...
- .
Alternative commands
The JobScheduler's next_state (true), error_state (false) and define the default behavior of the job chain as described above.
XML commands such as add_order commands and modify_job can also be used to provide a limited control of work flow workflow within a job chain (see How to configure the handling of exit codes by jobs and the JobScheduler <job_chain_node.job_chain> Element reference).However, these commands are job-specific and will be applied . 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 of on_return_codes is therefore independent of the job specified for a node and can be used more flexibly than next_state, error_state and commands such as add_order.
Example: Starting an order and skipping nodes according to the return code returned by a job chain node
...
Unpack the configuration in the JobScheduler's Live live
folder. See our series of Tutorials for JobScheduler for information getting JobScheduler installed and running.
...
- inspected - and edited if required - using in the JOE - JobScheduler Object Editor (JOE)
- run using the JOC - JobScheduler Operating Operations Center (JOC).
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:
...
A configuration as described in the previous section is shown in the diagram below:
- Job Chain A has JobChainA has 6 shell jobs 1, 2 ,3, 4, 5 and 6 and Job Chain B JobChainB has 2 shell jobs.
- If Job 3 in Job Chain A Job3 in JobChainA ends successfully (i.e. its shell script ends with a return code = 0):
- .An order will be generated for Job Chain B JobChainB and the order started.
- The Order order running on Job Chain A JobChainA should proceed to the next node configured for the chain (Job 4Job4).
- If Job 3 in Job Chain A JobChainA ends in error (, i.e. its shell script ends with a return code between 1 and 5) , then:
- No order for Job Chain B JobChainB should be generated.
- The Order order running on Job Chain A JobChainA should skip two processing steps (Jobs 4 Jobs4 and 5 Job5) and proceed to the last node in the chain (Job 6Job6).
Processing return codes
...
- 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.
One or more return_codes and one or more behaviors can be specified for each on_return_code element.- 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.Note 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.
- Generation of the order to start JobChainB:
- If Job3 in JobChainA
- If Job 3 in Job Chain A ends with an return code = 0 then an Order order for Job Chain B 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 any the parameters set for the originating order.In addition
- Skipping nodes in the current job chain:
- If Job 3 in Job Chain A 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:
- Job 3 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 state 6 for Job 6 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.
- If Job 3 in Job Chain A 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:
...
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 Job 3 in Job Chain A Job3 in JobChainA and used to set the return code for this job:
- The orderParameter for Order 0 Order0 has the value 0 and
- the orderParameter for Order 1 Order1 has value 1.
The behavior of the example configuration for each order will be as described in the previous section.
...
The code block below can be opened to show part of the log file for Order 0 Order0. This shows the log information for Job3 and the start of Job 4 Job4. The following points are relevant:
- The orderParameter order_parameter value of 0 is shown in Line 56 58 of the listing.
- Line 66 71 shows that Job 3 Job3 is exiting with return code 0.
- The end of processing of the node for Job 3 Job3 is noted in line 7072.
- Line 71 74 shows that the state is set for starting Job 4 Job4 - there is no mention of the generation of the order that will start Job Chain B JobChainB.
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
[info] set_state 3, Job /Examples/JobChainReturnCodes_1/Job_3Job3 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) SCHEDULER-842 Task is going to process Order Examples/JobChainReturnCodes_1/Chain_A:Order 0JobChainA:Order0 "JobJobChainA Chain- Aparameter - ParameterValuevalue 0", state=3, on JobScheduler 'http://AA-Win7:4110', Order's Process_class [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes_1,Job_3Job3.log [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) SCHEDULER-918 state=starting (at=never) [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) SCHEDULER-987 Starting processConfiguration File: "C:\Windows\TEMP\\sos-5C9FA042FB.cmd" 2015-11-05 11:21:01.483+0100 \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_1/Job_3:69722Job3: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_1/Job_3Job3:6972292842) [stdout] Job_3Job3 : job starting [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] orderParameterorder_parameter = "0" [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>set /a number=1592528451 %2 +1 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] Job_3Job3 : sleeping for 2 seconds..... [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>ping 127.0.0.1 -n 2 1>nul [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] Job_3Job3 : job ending exit 0 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>exit 0 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6972292842) SCHEDULER-843 Task has ended processing of Order Examples/JobChainReturnCodes_1/Chain_AJobChainA:OrderOrder0 0 "JobJobChainA Chain- Aparameter - ParameterValuevalue 0", state=3, on JobScheduler 'http://AA-Win7:4110' [info] set_state 4, Job /Examples/JobChainReturnCodes_1/Job_4Job4 [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) SCHEDULER-842 Task is going to process Order Examples/JobChainReturnCodes_1/Chain_A:Order 0JobChainA:Order0 "JobJobChainA Chain- Aparameter - ParameterValuevalue 0", state=4, on JobScheduler 'http://AA-Win7:4110', Order's Process_class [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes_1,Job_4Job4.log [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) SCHEDULER-918 state=starting (at=never) [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) SCHEDULER-987 Starting process: "C:\Windows\TEMP\\sos-5C9FD94DB4F7DEF0E7B2.cmd" [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) [stdout] Job_4Job4 : job starting [info] (Task Examples/JobChainReturnCodes_1/Job_4Job4:6972392843) [stdout] |
The next code block shows part of the log file for Order 1 Order1. This shows the log information for Job3 and the start of Job 6 Job6. The following points are relevant:
- Line 66 68 of the listing shows that Job 3 Job3 is exiting with return code 1.
- Line 69 shows that an error has been logged.
- The end of processing of the node for Job 3 Job3 is noted in line 70.
- Line 70 72 shows that an error is loggedLine 71 shows that the state is the state is set for starting Job 6 Job6 - the job at the node specified in the to_state element that was configured for node 3.
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
[info] set_state 3, Job /Examples/JobChainReturnCodes_1/Job_3Job3 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) SCHEDULER-842 Task is going to process Order Examples/JobChainReturnCodes_1/Chain_AJobChainA:OrderOrder1 1 "JobJobChainA Chain- Aparameter - ParameterValuevalue 1", state=3, on JobScheduler 'http://AA-Win7:4110', Order's Process_class [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes_1,Job_3Job3.log [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) SCHEDULER-918 state=starting (at=never) [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) SCHEDULER-987 Starting processConfiguration File: "C:\Windows\TEMP\\sos-5CA678D026.cmd"\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_1/Job_3Job3:6973092853) SCHEDULER-726Reading configuration Taskfrom runs on this JobScheduler 'http://AA-Win7:4110'xml payload... [info] (Task Examples/JobChainReturnCodes/Job3:92853) SCHEDULER-987 Starting process: "C:\Windows\TEMP\\sos-F85292D6E1.cmd" [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] Job_3 : job starting SCHEDULER-726 Task runs on this JobScheduler 'http://AA-Win7:4110' [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3:69730/Job3:92853) [stdout] orderParameterJob3 =: "1"job starting [info] (Task Examples/JobChainReturnCodes/Job3:92853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . order_parameter = "1" [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3:69730) [stdout] C:\ProgramData\sos [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=1607931044 %2 +1 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] Job_3Job3 : sleeping for 21 seconds..... [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>ping 127.0.0.1 -n 21 1>nul [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] Job_3Job3 : job ending exit 1 [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>exit 1 [ERROR] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) SCHEDULER-280 Process terminated with exit code 1 (0x1) [info] (Task Examples/JobChainReturnCodes_1/Job_3Job3:6973092853) SCHEDULER-843 Task has ended processing of Order Examples/JobChainReturnCodes_1/Chain_A:Order 1 "Job Chain A - ParameterValue/JobChainA:Order1 "JobChainA - parameter value 1", state=3, on JobScheduler 'http://AA-Win7:4110' [info] set_state 6, Job /Examples/JobChainReturnCodes_1/Job_6Job6 [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) SCHEDULER-842 Task is going to process Order Examples/JobChainReturnCodes_1/Chain_A:Order 1JobChainA:Order1 "JobJobChainA Chain- Aparameter -value ParameterValue 1", state=6, on JobScheduler 'http://AA-Win7:4110', Order's Process_class [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854 - Protocol starts in C:/ProgramData/sos-berlin.com/jobscheduler/jobscheduler_1.10/logs/task.Examples,JobChainReturnCodes_1,Job_6Job6.log [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) SCHEDULER-918 state=starting (at=never) [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) SCHEDULER-987 Starting process: "C:\Windows\TEMP\\sos-5CA6B147DFF852B1C77B.cmd" [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) [stdout] Job_6 : job starting . [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) [stdout] Job6 : job starting |
The next code block shows the last few lines of the log file for Order 1 Order1. Line 98 99 of the listing shows that despite the error recorded as Job 3 Job3 ended, the order is set to the success state.
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
[info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) [stdout] .Job6 [info] (Task Examples/JobChainReturnCodes_1/Job_6:69731) [stdout] Job_6 : : job ending [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) SCHEDULER-915 Process event [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6973192854) SCHEDULER-843 Task has ended processing of Order Examples/JobChainReturnCodes_1/Chain_AJobChainA:OrderOrder1 1 "JobJobChainA Chain- Aparameter - ParameterValuevalue 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_1,Chain_A.Order 1JobChainA.Order1.log |
Part of the log file for Job Chain B JobChainB, which only starts when Order 0 Order0 is run, is shown in the next code block. Only the log information for Job 6 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 5124.
- The orderParameter order_parameter value from Order 0 on Job Chain A Order0 on JobChainA has also been taken over and shown in line 3836.
- The ParameterJob3 parameter_job_3 parameter, which is set with value "Parameter from Job3 - RC=0ParameterReturnCodeJob3" is shown in line 3533. This parameter was set in the on_return_code element at the node for Job 3 Job3 in JobChain A JobChainA.
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
[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_1/Job_6Job6:6972592845) [stdout] Job_6 : job startingC:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>echo parameter_job_3 = "ParameterReturnCodeJob3" [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] .parameter_job_3 = "ParameterReturnCodeJob3" [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>echo ParameterJob3order_parameter = "Parameter from Job3 - RC=0" "3" [info] (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] order_parameter = "3" [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:69725) [stdout] ParameterJob3 = "Parameter from Job3 - RC=0"92845) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>echo10>set orderParameter/a number= "0"28461 %2 +1 [info] (Task Examples/JobChainReturnCodes/Job6:92845) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] orderParameter = "0" Job6 : sleeping for 2 seconds..... [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>set /a number=15932 %2 +1 [info] (Task Examples/JobChainReturnCodes_1/Job_6:69725) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6:69725) [stdout] Job_6 : sleeping for 1 seconds.....10>ping 127.0.0.1 -n 2 1>nul [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] Job6 : job ending [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] C:\ProgramData\sos-berlin.com\jobscheduler\jobscheduler_1.10>ping 127.0.0.1 -n 1 1>nul . [info] (Task Examples/JobChainReturnCodes/Job6:92845) SCHEDULER-915 Process event [info] (Task Examples/JobChainReturnCodes_1/Job_6Job6:6972592845) [stdout] . [info] (Task Examples/JobChainReturnCodes_1/Job_6:69725) [stdout] Job_6 : job ending 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
- 1) Give the return code, e.g
. return_code = 0
is signals success, in the ReturnCodes field- Syntax:
- Individual return codes are separated by blank 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 thejob_chain_node@next_state
(return code 0) orjob_chain_node@error_state
(other return codes) attribute.
- Syntax:
- 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 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
Example Job Chain Code
Code Block | ||||
---|---|---|---|---|
| ||||
<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="Chain_BJobChainB"> <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="Chain_BJobChainB"> <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="Job_4Job4" next_state="5" error_state="Error"/> <job_chain_node state="5" job="Job_5Job5" next_state="6" error_state="Error"/> <job_chain_node state="6" job="Job_6Job6" 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.
Example:Code Block language xml title Example showing 'overlapping' of return-codes collapse true <!-- do not use overlapping return codes --> <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> <!-- use mutliple add_order elements for the same 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 versions 1.9.7, 1.10.1) and when configuration is carried out with a code editor.Example:
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
...
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.
Further Examples
The following subjects have not been covered in this article:
...
References
Change Management References
Jira | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
...
See also
- The Knowledge Base Articles on return / exit code handling:
- JobScheduler Reference Documentation:
<job_chain_node> XML Element
<add_order> (Node Order plugin) XML Element
- <params> (Node Order plugin) XML Element
- <param> (Node Order plugin) XML Element
...