Table of Contents |
---|
Starting Point
- Users would like to check in individual job scripts or monitor scripts
- if a job chain has been executed in the current period, e.g. for the current day,
- what is the last job chain order state what execution result (success/failure) was created on completion of the job chain,
- if an order previously completed successfully or with an error.
- The intention for checking the job chain execution history is to automate decision making based on the point in time or execution result of a previous job startchain run.
Feature
Display feature availability StartingFromRelease 1.10.2 - This feature
- is available with
Jira server SOS JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JITL-217228 - is a subset of
Jira server SOS JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JITL-212
- is available with
- A JobHistory JobChainHistory object is provided for job chain history checks that can be used
- in individual jobs that are implemented with Java or JavaScript.
- in individual job monitors that are implemented with Java or JavaScript.
- The JobHistory JobChainHistory object returns a JobHistoryInformation JobChainHistoryInformation object for a given job chain that contains the history of the job chain runs.
- The JobHistoryInformation JobChainHistoryInformation object provides a set of JobHistoryInformationEntry JobChainHistoryInformationEntry objects that expose the history information for the respective job chain runs.
...
JobChainHistory Object
This object is instantiated by a job or job monitor and provides the method to retrieve a JobHistoryInformation JobCHainHistoryInformation object for a given job chain.
Object | Description |
---|---|
jobHistoryjobChainHistory = new Packages.com.sos.jitl.checkrunhistory.JobHistoryJobChainHistory( spooler.delegate ) | object for use with jobs and job monitors that are implemented with Java or JavaScript |
Methods | |
jobHistoryInfo | retrieves the JobHistoryInformation object within the specified limits:
|
JobHistoryInformation Object
This object is returned by the JobHistory object for a given job and provides a set of JobHistoryInformationEntry objects for the respective job runs.
| |
jobChainHistory.getNumberOfCompleted() | The number of completed entries |
jobChainHistory.getNumberOfStarts() | The number of starts |
jobChainHistory.getNumberOfCompletedSuccessful() | The number of completed runs with a state that is not an error state |
jobChainHistory.getNumberOfCompletedWithError() | The number of completed runs with a state that is an error state |
jobChainHistory.getCount() | The number of entries |
JobChainHistoryInformation Object
This object is returned by the JobChainHistory object for a given job chain and provides a set of JobChainHistoryInformationEntry objects for the respective job chain runs.
- Completed translates to: "has an end date"
- With error translates to: "has a state that is an error state in the job chain"
Object | Description | ||
---|---|---|---|
jobChainHistoryInfo = jobChainHistory.getChainJobInfo( jobchain, limit, timelimit ) | The JobChainHistoryInformation object is retrieved from the JobChainHistory object for a given job chain Please note that an order can be specified with the jobchain: jobchain(order_id) . | ||
Methods | Description | ||
Retrieve JobChainHistoryInformationEntry objects | |||
JobSchedulerHistoryInfoEntry jobChainHistoryInfo.getRunning() | Get the JobSchedulerHistoryInfoEntry object for the current job chain run. | ||
JobSchedulerHistoryInfoEntry | Get the JobSchedulerHistoryInfoEntry object for the most recently started job chain run including running order and orders that completed successfully or failed with error. | ||
JobSchedulerHistoryInfoEntry | Get the JobSchedulerHistoryInfoEntry object for the most recently completed job chain run including orders that completed successfully or failed with error. | ||
JobSchedulerHistoryInfoEntry | Get the JobSchedulerHistoryInfoEntry object for the most recently successfully completed job chain run. | ||
JobSchedulerHistoryInfoEntry | Get the JobSchedulerHistoryInfoEntry object for the most recently completed job chain run that failed with error. | ||
Checks for any job chain runs in the period of the current day | |||
boolean | Indicates that a job chain run started within the current period and applies to running job chains and completed job chain runs. | ||
boolean | Indicates that a job chain run started and completed within the current period and applies to job chain | ||
Object | Description | ||
jobHistoryInfo = jobHistory.getJobInfo( jobname, limit, timelimit ) | The JobHistoryInformation object is retrieved from the JobHistory object for a given job. | ||
Methods | Description | ||
Retrieve JobHistoryInformationEntry objects | |||
JobHistoryInfoEntry jobHistoryInfo.getRunning() | Get the JobHistoryInformationEntry object for the current job run. If used in a job's pre-processing monitor then this method will return an empty object as the job is not currently running. | ||
JobHistoryInfoEntry jobHistoryInfo.getLastExecution() | Get the JobHistoryInformationEntry object for the most recently started job run including running jobs and jobs that completed successfully or failed with error. | ||
JobHistoryInfoEntry jobHistoryInfo.getLastCompleted() | Get the JobHistoryInformationEntry object for the most recently completed job run including jobs that completed successfully or failed with error. | ||
JobHistoryInfoEntry jobHistoryInfo.getLastCompletedSuccessful() | Get the JobHistoryInformationEntry object for the most recently successfully completed job run. | ||
JobHistoryInfoEntry jobHistoryInfo.getLastCompletedWithError() | Get the JobHistoryInformationEntry object for the most recently completed job run that failed with error. | ||
Checks for any job runs in the period of the current day | |||
boolean jobHistoryInfo.isStartedToday() | Indicates that a job run started within the current period and applies to running jobs and completed job runs. | ||
boolean jobHistoryInfo.isStartedTodayCompleted() | Indicates that a job run started and completed within the current period and applies to job runs that completed successfully or failed with errror. | ||
boolean jobHistoryInfo.isStartedTodayCompletedSuccessful() | Indicates that a job run started and completed successfully within the current period. | ||
boolean jobHistoryInfo.isStartedTodayCompletedWithError() | Indicates that a job run started and completed with error within the current period. | ||
Checks for any job runs that completed today | |||
boolean jobHistoryInfo.isCompletedToday() | Indicates that a job run completed in the current period and applies to job runs that completed successfully or failed with error. | ||
boolean jobHistoryInfoboolean | Indicates that a job chain run started and completed successfully within the current period. | ||
boolean jobHistoryInfoboolean | Indicates that a job chain run started and completed with error within the current period. | ||
Checks for any job chain runs that | ended after a specific point in timecompleted today | ||
boolean | Indicates | boolean jobHistoryInfo.endedAfter( "03:00:00" ) | indicates that a job chain run completed after the given date |
boolean jobHistoryInfo.endedWithSuccessfulAfter( "03:00:00" ) | indicates that a job run completed successfully after the given date | ||
in the current period and applies to job runs that completed successfully or failed with error. | |||
boolean | Indicates that a job chain run completed successfully within the current period. | ||
boolean | Indicates that a job chain run completed with error within the current period. | boolean jobHistoryInfo.endedWithErrorAfter( "03:00:00" ) | indicates that a job run completed with error after the given date |
Checks for any job chain runs that started ended after a specific point in time | |||
boolean jobHistoryInfoboolean | indicates that a job chain run started completed after the given date, the job might be completed or running | ||
boolean | indictes indicates that a job chain run started completed successfully after the given date and does not report any errors, the job might be completed or running | ||
boolean | indicates that a job chain run completed with error after the given date | ||
Checks for any job chain runs that started after a specific point in time | |||
boolean | indicates that a job chain run started after the given date and does report errors, the job chain might be completed or running |
JobHistoryInformationEntry Object
The object represents the history for a specific job run and is provided by the JobHistoryInformation object.
boolean | indictes that a job chain run started after the given date and does not report any errors, the job chain might be completed or running |
boolean | indicates that a job chain run started after the given date and does report errors, the job chain might be completed or running |
JobSchedulerHistoryInfoEntry Object
The object represents the history for a specific job chain run and is provided by the JobChainHistoryInformation object.
Object | Description | ||
---|---|---|---|
| Get the JobSchedulerHistoryInfoEntry object for the current job chain run. | ||
| Get the JobSchedulerHistoryInfoEntry | ||
Object | Description | ||
JobHistoryInfoEntry jobHistoryInfo.getRunning() | Get the JobHistoryInformationEntry object for the current job run. If used in a job's pre-processing monitor then this method will return an empty object as the job is not currently running. | ||
JobHistoryInfoEntry jobHistoryInfo.getLastExecution() | Get the JobHistoryInformationEntryobject for the most recently started job chain run including running jobs job chains and jobs job chains that completed successfully or failed with error. | ||
... | |||
Property | Description | ||
name | Contains the job chain name. | ||
found | Indicates if the associated object is not null. | ||
id | Exposes the unique task order history identification as provided by JobScheduler. | ||
order_id | The order id of the current order | ||
position | Returns the position of the object in the job chain execution history: a value 0 signals the most recent entry, larger values suggest older entries. | ||
start | Returns the start date of the job chain run. | ||
end | Returns the end date of the job chain run. | ||
duration | Returns the duration in the format hh:mm:ss . If longer the than one day the format provided is d:hh:mm:ss . | ||
state | The current state of the order. | executionResult | Provides the exit code for shell jobs or -1 if no exit code is provided, e.g. for API jobs. |
error | Indicats Indicates an error status, 1=error, 0=no error. | ||
errorMessage | Returns the error message as provided e.g. for shell jobs by the operating system, for API jobs from exceptions. | ||
errorCode | Optionally returns an error code, e.g. from API jobs that raise defined exceptions. |
Usage
...
An order execution will be assumed as an error if the state is an error state in the job chain. |
Usage
Use with a Job Script
A complete sample files example file demonstrates the use of
- Download complete sample example file: check_job_chain_run_history.job.xml
Code Block | ||||
---|---|---|---|---|
| ||||
function spooler_process() { // using the current job chain name and the defaultgiven limit var jobHistoryInfo = getJobHistoryInfoObject(); // using the current job name and the given limit // var jobHistoryInfo = getJobHistoryInfoObjectvar jobChainHistoryInfo = getjobChainHistoryInfoObject( "", 30 ); // using the given job chain name and default limit // var jobHistoryInfojobChainHistoryInfo = getJobHistoryInfoObjectgetjobChainHistoryInfoObject( "job1jobchain1" ); // using the given job chain name and the given limit // var jobHistoryInfojobChainHistoryInfo = getJobHistoryInfoObjectgetjobChainHistoryInfoObject( "job1jobchain1", 20 ); // reportingusing somethe info ongiven job runs chain name and report( jobHistoryInfo.getRunning()a given order_id // var jobChainHistoryInfo = getjobChainHistoryInfoObject( "jobchain1(order_id)", 20 ); // report some info on job chain runs report( jobHistoryInfojobChainHistoryInfo.getLastCompleted() ); report( jobHistoryInfojobChainHistoryInfo.getLastCompletedSuccessfulgetRunning() ); report( jobHistoryInfojobChainHistoryInfo.getLastCompletedWithErrorgetLastCompletedSuccessful() ); report( jobChainHistoryInfo.getLastCompletedWithError() ); // report on currently running job chains report( jobHistoryInfojobChainHistoryInfo.getLastExecution() ); spooler_log.info("isStartedToday: " + jobHistoryInfojobChainHistoryInfo.isStartedToday()); spooler_log.info("isStartedTodayCompletedSuccessful: " + jobHistoryInfojobChainHistoryInfo.isStartedTodayCompletedSuccessful()); spooler_log.info("isStartedTodayCompletedWithError: " + jobHistoryInfojobChainHistoryInfo.isStartedTodayCompletedWithError()); spooler_log.info("isStartedTodayCompleted: " + jobHistoryInfojobChainHistoryInfo.isStartedTodayCompleted()); spooler_log.info("isCompletedToday: " + jobHistoryInfojobChainHistoryInfo.isCompletedToday()); spooler_log.info("isCompletedTodaySuccessful: " + jobHistoryInfojobChainHistoryInfo.isCompletedTodaySuccessful()); spooler_log.info("isCompletedTodayWithError: " + jobHistoryInfojobChainHistoryInfo.isCompletedTodayWithError()); spooler_log.info("endedAfter: " + jobHistoryInfojobChainHistoryInfo.endedAfter("03:00:00")); spooler_log.info("endedWithErrorAfter: " + jobHistoryInfojobChainHistoryInfo.endedWithErrorAfter("03:00:00")); spooler_log.info("endedSuccessfulAfter: " + jobHistoryInfojobChainHistoryInfo.endedSuccessfulAfter("03:00:00")); spooler_log.info("startedAfter: " + jobHistoryInfojobChainHistoryInfo.startedAfter("03:00:00")); spooler_log.info("startedWithErrorAfter: " + jobHistoryInfojobChainHistoryInfo.startedWithErrorAfter("03:00:00")); spooler_log.info("startedSuccessfulAfter: " + jobHistoryInfojobChainHistoryInfo.startedSuccessfulAfter("03:00:00")); // example how to convert Date fields (start date)spooler_log.info("isStartedToday:" + jobChainHistoryInfo.queryHistory("isStartedToday")); if ( jobHistoryInfo.getLastCompletedSuccessful().found ) {spooler_log.info("isStartedTodayCompletedSuccessful:" + jobChainHistoryInfo.queryHistory("isStartedTodayCompletedSuccessful")); spooler_log.info("isStartedTodayCompletedWithError:" + jobChainHistoryInfo.queryHistory("isStartedTodayCompletedWithError")); var d = jobHistoryInfo.getLastCompletedSuccessful().start spooler_log.info("isStartedTodayCompleted:" + jobChainHistoryInfo.queryHistory("isStartedTodayCompleted")); spooler_log.info("isCompletedToday:" if (d != null) {+ jobChainHistoryInfo.queryHistory("isCompletedToday")); spooler_log.info("isCompletedTodaySuccessfully:" var d2 = new Date(d.getTime(+ jobChainHistoryInfo.queryHistory("isCompletedTodaySuccessful")); spooler_log.info ("------->isCompletedTodayWithError:" + d2jobChainHistoryInfo.getFullYearqueryHistory("isCompletedTodayWithError ") ); } } // since release spooler_log.info ( "check if the job started on the previous day before a specific point in time" );1.10.2, 1.9.8 also possible var jobHistoryInfo = getJobHistoryInfoObject( "", "", "spooler_log.info("isCompletedAfter:" + jobChainHistoryInfo.queryHistory("isCompletedAfter(-1:10:4348:5633)" )); spooler_log.info ( "endedBefore -1:10:43:56: "isCompletedWithErrorAfter:" + jobHistoryInfo.getLastCompleted().found jobChainHistoryInfo.queryHistory("isCompletedWithErrorAfter(03:00:00)")); spooler_log.info( "endedBeforeWithError -1:10:43:56: "isCompletedSuccessfulAfter:" + jobHistoryInfo.getLastComletedWithError().found ); jobChainHistoryInfo.queryHistory("isCompletedSuccessfulAfter(03:00:00)")); spooler_log.info("isStartedAfter:" + "endedBeforeSuccessful jobChainHistoryInfo.queryHistory("isStartedAfter(-1:10:43:56: 48:33)")); spooler_log.info("isStartedWithErrorAfter:" + jobHistoryInfo.getLastCompletedSuccessful().found jobChainHistoryInfo.queryHistory("isStartedWithErrorAfter(03:00:00)")); spooler_log.info("isStartedSuccessfulAfter:" + jobChainHistoryInfo.queryHistory("isStartedSuccessfulAfter(03:00:00)")); return false; } function getJobHistoryInfoObject(jobname, limit, timelimit// example how to convert date fields (start date) if ( jobChainHistoryInfo.getLastCompletedSuccessful().found ) { var jobHistory = new Packages.com.sos.jitl.checkrunhistory.JobHistory( spooler.delegate ); var d = jobChainHistoryInfo.getLastCompletedSuccessful().start; if ((jobname === undefined) ||if (jobnamed =!== "")null) { jobname = spooler_task.job.name; } var d2 = new if (limit === undefined || limit === "") { Date(d.getTime()); spooler_log.info limit = "100"("------->" + d2.getFullYear() ); } if} (timelimit === undefined) {} spooler_log.info ( "check if the job chain started timelimit = ""; } on the previous day before a specific point in time" ); var jobHistoryInfojobChainHistoryInfo = jobHistory.getJobInfogetjobChainHistoryInfoObject( jobname"jobchain1", limit"", timelimit"-1:10:43:56" ); return jobHistoryInfo; } function report( reportItem ) {spooler_log.info ( "completedBefore -1:10:43:56: " + jobChainHistoryInfo.isCompletedBefore()); spooler_log.info( "_____________________________" ); if (reportItem.found) { ( "completedWithErrorBefore -1:10:43:56: " + jobChainHistoryInfo.isCompletedWithErrorBefore() ); spooler_log.info ( "Name:completedSuccessfulBefore -1:10:43:56: " + reportItemjobChainHistoryInfo.nameisCompletedSuccessfulBefore() ); // since spooler_log.info( "Task ID: " + reportItem.id ); release 1.10.2, 1.9.8 also possible spooler_log.info ( "Job NamecompletedBefore -1:10:43:56: " + reportItem.jobName jobChainHistoryInfo.queryHistory("isCompletedBefore")); spooler_log.info ( "Position: " + reportItem.position completedWithErrorBefore -1:10:43:56: " + jobChainHistoryInfo.queryHistory("isCompletedWithErrorBefore")); spooler_log.info ( "Start TimecompletedSuccessfulBefore -1:10:43:56: " + reportItem.start jobChainHistoryInfo.queryHistory("isCompletedSuccessfulBefore")); spooler_log.info( "End Time: " + reportItem.end ); return false; } function getjobChainHistoryInfoObject(jobchain, limit, timelimit) { var jobChainHistory = spooler_log.info( "Exit Code: " + reportItem.executionResult );new Packages.com.sos.jitl.checkrunhistory.JobChainHistory( spooler.delegate ); if ((jobchain === undefined) || spooler_log.info(jobchain "Error Message: " + reportItem.errorMessage );=== "")) { jobchain = spooler_log.info( "Error: " + reportItem.error )task.order.job_chain.name; } if spooler_log.info( "ErrorCode: " + reportItem.errorCode );limit === undefined || limit === "") { } else { limit = "100"; } if spooler_log.info( "Name: " + reportItem.name + " not found" )timelimit === undefined) { timelimit = ""; } } |
...
var jobChainHistoryInfo = jobChainHistory.getJobChainInfo( jobchain, limit, timelimit );
spooler_log.info("Number of completed: " + jobChainHistory.getNumberOfCompleted());
spooler_log.info("Number of starts: " + jobChainHistory.getNumberOfStarts());
spooler_log.info("Number of completed successfull: " + jobChainHistory.getNumberOfCompletedSuccessful());
spooler_log.info("Number of completed with error: " + jobChainHistory.getNumberOfCompletedWithError());
spooler_log.info("Number of entries: " + jobChainHistory.getCount());
return jobChainHistoryInfo;
}
function report( reportItem ) {
spooler_log.info( "_____________________________" );
if (reportItem.found) {
spooler_log.info( "Name:" + reportItem.name );
spooler_log.info( "id: " + reportItem.id );
spooler_log.info( "Job chain name: " + reportItem.jobChainName );
spooler_log.info( "Position: " + reportItem.position );
spooler_log.info( "Start Time: " + reportItem.start );
spooler_log.info( "End Time: " + reportItem.end );
spooler_log.info( "Duration: " + reportItem.duration );
spooler_log.info( "Error: " + reportItem.error );
} else {
spooler_log.info( "Name: " + reportItem.name + " not found" );
}
} |
Use with a Monitor Script
To identify if a running job chain is a rerun of a previously failed job chain execution you can use the following script for a pre-processing monitor. The script will expose the information if a rerun has been identified with the environment variable SCHEDULER_PARAM_JOB_CHAIN_IS_RERUN
- Download integrated job chain script sample: check_job_chain_rerun.job.xml
- Download a re-usable monitor script sample: check_job_chain_rerun_with_monitor_use.job.xml and check_job_chain_rerun.monitor.xml
Code Block | ||||
---|---|---|---|---|
| ||||
function spooler_task_before() { var jobHistoryjobChainHistory = new Packages.com.sos.jitl.checkrunhistory.JobHistoryJobChainHistory( spooler.delegate ); var jobHistoryInfojobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfogetJobChainInfo( spooler_task.order.jobjob_chain.name, 100, "" ); var isRerun = (jobHistoryInfojobChainHistoryInfo.getLastCompletedWithError().found && jobHistoryInfojobCHainHistoryInfo.getLastCompletedWithError().position == 0); var params = spooler_task.params; params.set_var("JOB_CHAIN_IS_RERUN", isRerun ); spooler_log.info("Job chain rerun identified: " + isRerun); return true; } |
...
- The script retrieves the last job chain execution that completed with error and checks if the position of the object provided is the first in the recent history list. The first position of a job chain that recently completed with error is
- 0 if the script is executed as a pre-processing monitor script before a task start.
- 1 if the script is executed as a job script for a running task. That task would be added to the begin of the recent history list.
- In order to check if a job chain did run before a given point in time you can query a job chain history object that takes a time limit into consideration as from the following samples:
Code Block language js jobHistoryInfojobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfogetJobChainInfo( "job1jobchain1", 100, "-1:10:43:56" ); spooler_log.info( "endedBefore -1:10:43:16:" + jobHistoryInfojobChainHistoryInfo.getLastCompleted().found ); spooler_log.info( "endedBeforeWithError -1:10:43:16:" + jobHistoryInfojobChainHistoryInfo.getLastComletedWithError().found ); spooler_log.info( "endedBeforeSuccessful -1:10:43:16:" + jobHistoryInfojobChainHistoryInfo.getLastCompletedSuccessful().found );
Code Block language js jobHistoryjobChainHistory.setTimeLimit( "-1:10:43:56" ); jobHistoryInfojobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfogetJobChainInfo( "job1jobchain1", 100, "" "" ); spooler_log.info( "endedBefore -1:10:43:16:" + jobChainHistoryInfo.getLastCompleted().found ); spooler_log.info( "endedBeforeendedBeforeWithError -1:10:43:16:" + jobHistoryInfojobChainHistoryInfo.getLastCompletedgetLastComletedWithError().found ); spooler_log.info( "endedBeforeWithErrorendedBeforeSuccessful -1:10:43:16:" + jobHistoryInfo.getLastComletedWithError().found ); spooler_log.info( "endedBeforeSuccessful -1:10:43:16:" + jobHistoryInfo.getLastCompletedSuccessful().found );
Implementation
" + jobChainHistoryInfo.getLastCompletedSuccessful().found );
Implementation
- The implementation makes use of API methods, i.e. XML commands, to retrieve the job history instead of a database connection.
- The solution can be used with Agents.
- No separate HTTP connection is created, the solution makes use of the HTTP(S) connection that is established between Master and Agent.
References
Change Management References
Jira | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Documentation
- How to check the job history for previous job runs
- How to check previous job chain executions and to start successor job chains
- The implementation makes use of API methods, i.e. XML commands, to retrieve the job history instead of a database connection.
- The solution can be used with Agents.
- No separate HTTP connection is created, the solution makes use of the HTTP(S) connection that is established between Master and Agent.