Starting Point
- Users would like to check in individual job scripts or monitor scripts
- if a job has been executed in the current period, e.g. for the current day
- what execution result (success/failure) was created on completion of the job
- The intention for checking the job execution history is to automate decision making based on the point in time or execution result of a previous job start.
Feature
- This feature
- A JobHistory object is provided for job 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 object returns a JobHistoryInformation object for a given job.
- The JobHistoryInformation object provides a set of JobHistoryInformationEntry objects that expose the history information for the respective job runs.
JobHistory Object
This object is instantiated by a job or job monitor and provides the method to retrieve a JobHistoryInformation object for a given job.
Object | Description |
---|---|
jobHistory = new Packages.com.sos.jitl.checkrunhistory.JobHistory( spooler.delegate ) | object for use with jobs and job monitors that are implemented with Java or JavaScript |
Methods | |
jobHistoryInfo = jobHistory.getJobInfo( jobname, limit, timelimit ) | 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.
Object | Description |
---|---|
jobHistoryInfo = jobHistory.getJobInfo( jobname, limit, timelimit ) | object retrieved from the JobHistory object for a given job |
Methods | Description |
Retrieve JobHistoryInformationEntry objects | |
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.getLastCompletedExecution() | get the JobHistoryInformationEntry object for the most recently started job run for jobs that completed successfully or failed with error |
Checks for job runs for the period of the current day | |
boolean isStartedToday() | indicates that a job run started within the current period and applies to running jobs and completed job runs |
boolean 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 isStartedTodayCompletedSuccessful() | indicates that a job run started and completed successfully within the current period |
boolean isStartedTodayCompletedWithError() | indicates that a job run started and completed with error within the current period |
Checks for any job runs that completed today | |
boolean isCompletedToday() | indicates that a job run completed in the current period and applies to job runs that completed successfully or failed with error |
boolean isCompletedTodaySuccessful() | indicates that a job run completed successfully within the current period |
boolean isCompletedTodayWithError() | indicates that a job run completed with error within the current period |
Checks for any job runs that ended after a specific point in time | |
boolean endedAfter( "03:00:00" ) | indicates that a job run completed after the given date |
boolean endedWithSuccessfulAfter( "03:00:00" ) | indicates that a job run completed successfully after the given date |
boolean endedWithErrorAfter( "03:00:00" ) | indicates that a job run completed with error after the given date |
Checks for any job runs that started after a specific point in time | |
boolean startedAfter( "03:00:00" ) | indicates that a job run started after the given date, the job might be completed or running |
boolean startedSuccessfulAfter( "03:00:00" ) | indictes that a job run started after the given date and does not report any errors, the job might be completed or running |
boolean startedWithErrorAfter( "03:00:00" ) | indicates that a job run started after the given date and does report errors, the job might be completed or running |
JobHistoryInformationEntry Objects
Object | Description |
---|---|
running | the current job run |
lastCompleted | the last job run being completed |
lastCompletedSuccessful | the last successfully completed execution of the job |
lastCompletedWithError | the last unsuccessfully completed execution of the job |
Method | Description |
boolean isStartedToday() | indicates that the job run started within the current period and applies to running jobs and completed job runs |
boolean isStartedTodayCompleted() | indicates that the job run started and completed within the current period and applies to job runs that completed successfully or with errror |
boolean isStartedTodayCompletedSuccessful() | indicates that the job run started and completed successfully within the current period |
boolean isStartedTodayCompletedWithError() | indicates that the job run started and completed with error within the current period |
boolean isCompletedToday() | indicates that the job run completed in the current period and applies to job runs that completed successfully or with error |
boolean isCompletedTodaySuccessful() | indicates that the job run completed successfully within the current period |
boolean isCompletedTodayWithError() | indicates that the job run completed with error within the current period |
boolean endedAfter( "03:00:00" ) | indicates that the job run completed after the given date |
boolean endedWithSuccessfulAfter( "03:00:00" ) | indicates that the job run completed successfully after the given date |
boolean endedWithErrorAfter( "03:00:00" ) | indicates that the job run completed with error after the given date |
boolean startedAfter( "03:00:00" ) | indicates that the job run started after the given date, the job might be completed or running |
boolean startedSuccessfulAfter( "03:00:00" ) | indictes that the job run started after the given date and does not report any errors, the job might be completed or running |
boolean startedWithErrorAfter( "03:00:00" ) | indicates that the job run started after the given date and does report errors, the job might be completed or running |
Property | Description |
name | job name |
found | indicates if the associated object is not null |
id | unique task identification as provided by JobScheduler |
position | position of the object in the job execution history: a value 0 signals the most recent entry, larger values suggest older entries |
start | the start date of the job run |
end | the end date of the job run |
executionResult | the exit code for shell jobs or -1 if no exit code is provided, e.g. for API jobs |
error | 1=error, 0=no error |
errorMessage | the error message as provided e.g. for shell jobs by the operating system, for API jobs from exceptions |
errorCode | optionally includes an error code, e.g. from API jobs that raise defined exceptions |
Usage
Use with a Job Script
A complete sample files demonstrates the use of
- Download complete sample file: check_run_history.job.xml
Use with a Monitor Script
To identify if a running job is a rerun of a previously failed job 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_IS_RERUN
- Download integrated job script sample: check_rerun.job.xml
- Download a re-usable monitor script sample: check_rerun_with_monitor_use.job.xml and check_rerun.monitor.xml
Explanations
- The script retrieves the last job 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 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 did run before a given point in time you can query a job history object that takes a time limit into consideration as from the following samples:
jobHistoryInfo = jobHistory.getJobInfo( "job1", 100, "-1:10:43:56" ); spooler_log.info( "endedBefore -1:10:43:16:" + jobHistoryInfo.getLastCompleted().found ); spooler_log.info( "endedBeforeWithError -1:10:43:16:" + jobHistoryInfo.getLastComletedWithError().found ); spooler_log.info( "endedBeforeSuccessful -1:10:43:16:" + jobHistoryInfo.getLastCompletedSuccessful().found );
jobHistory.setTimeLimit( "-1:10:43:56" ); jobHistoryInfo = jobHistory.getJobInfo( "job1", 100, "" ); spooler_log.info( "endedBefore -1:10:43:16:" + jobHistoryInfo.getLastCompleted().found ); spooler_log.info( "endedBeforeWithError -1:10:43:16:" + jobHistoryInfo.getLastComletedWithError().found ); spooler_log.info( "endedBeforeSuccessful -1:10:43:16:" + jobHistoryInfo.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.