Page History

...

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 execution result (success/failure) was created on completion is the last job chain order state of the job chain
- did the order end with an error or successful
The intention for checking the job chain order execution history is to automate decision making based on the point in time or execution result of a previous job chain start.

Feature

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
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 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 jobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfogetJobChainInfo( jobnamejobchain, limit, timelimit )

retrieves the JobHistoryInformation object within the specified limits:

jobnamejobchain: for a specific job chain (a relative name or absolute path)the path of the job chain)
- an specific order id can be added: jobchain(order_id)
limit: for the specified number of entries from the job history
timelimit: for a specific point in time up to that the job history is considered

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.

- it is a from to intervall
- the default for from is 00:00:00
- the default for to is the current time
- the interval is specified with from..to
- if a single time is given, it is the from time.

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

Completed means "has an end date"
With error means "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 jobChainHistoryInfo.getLastExecution()`	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 jobChainHistoryInfo.getLastCompleted()`	Get the `JobSchedulerHistoryInfoEntry` object for the most recently completed job chain run including orders that completed successfully or failed with error.
`JobSchedulerHistoryInfoEntry jobChainHistoryInfo.getLastCompletedSuccessful()`	Get the `JobSchedulerHistoryInfoEntry` object for the most recently successfully completed job chain run.
`JobSchedulerHistoryInfoEntry jobChainHistoryInfo.getLastCompletedWithError()`	Get the `JobSchedulerHistoryInfoEntry` object for the most recently completed 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 jobHistoryInfoboolean jobChainHistoryInfo.isStartedToday()`	Indicates that a job chain run started within the current period and applies to running jobs job chains and completed job chain runs.
`boolean jobHistoryInfoboolean jobChainHistoryInfo.isStartedTodayCompleted()`	Indicates that a job chain run started and completed within the current period and applies to job chain runs that completed successfully or failed with errror.
`boolean jobHistoryInfoboolean jobChainHistoryInfo.isStartedTodayCompletedSuccessful()`	Indicates that a job chain run started and completed successfully within the current period.
`boolean jobHistoryInfoboolean jobChainHistoryInfo.isStartedTodayCompletedWithError()`	Indicates that a job chain run started and completed with error within the current period.
Checks for any job runs that completed today
`boolean jobHistoryInfoboolean jobChainHistoryInfo.isCompletedToday()`	Indicates that a job chain run completed in the current period and applies to job runs that completed successfully or failed with error.
`boolean jobHistoryInfoboolean jobChainHistoryInfo.isCompletedTodaySuccessful()`	Indicates that a job chain run completed successfully within the current period.
`boolean jobHistoryInfoboolean jobChainHistoryInfo.isCompletedTodayWithError()`	Indicates that a job chain run completed with error within the current period.
Checks for any job runs that ended after a specific point in time
`boolean jobHistoryInfoboolean jobChainHistoryInfo.endedAfterisCompleteddAfter( "03:00:00" )`	indicates that a job chain run completed after the given date
`boolean jobHistoryInfoboolean jobChainHistoryInfo.endedWithSuccessfulAfterisCompletedWithSuccessfulAfter( "03:00:00" )`	indicates that a job chain run completed successfully after the given date
`boolean jobHistoryInfoboolean jobChainHistoryInfo.endedWithErrorAfterisCompletedWithErrorAfter( "03:00:00" )`	indicates that a job chain run completed with error after the given date
Checks for any job runs that started after a specific point in time
`boolean jobHistoryInfoboolean jobChainHistoryInfo.startedAfter( "03:00:00" )`	indicates that a job chain run started after the given date, the job might be completed or running
`boolean jobHistoryInfoboolean jobChainHistoryInfo.startedSuccessfulAfter( "03:00:00" )`	indictes that a job chain run started after the given date and does not report any errors, the job might be completed or running
`boolean jobHistoryInfojobChainHistoryInfo.startedWithErrorAfter( "03:00:00" )`	indicates that a job chain run started after the given date and does report errors, the job might be completed or running

...

JobSchedulerHistoryInfoEntry Object

The object represents the history for a specific job chain run and is provided by the JobHistoryInformation JobChainHistoryInformation object.

Object	Description
`JobHistoryInfoEntry jobHistoryInfoJobSchedulerHistoryInfoEntry jobChainHistoryInfo.getRunning()`	Get the JobHistoryInformationEntry`JobSchedulerHistoryInfoEntry` 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.chain run.
`JobSchedulerHistoryInfoEntry jobChainHistoryInfoJobHistoryInfoEntry jobHistoryInfo.getLastExecution()`	Get the JobHistoryInformationEntry`JobSchedulerHistoryInfoEntry` object for the most recently started job run including running jobs job chains and jobs job chains that completed successfully or failed with error.
...
Property	Description
`name`	Contains the job 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 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 one day 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 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.
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_run_history.job.xml.job.xml

Code Block

language	js
collapse	true

function spooler_process()  {
 
    // using the current job name and default limit
    var jobChainHistoryInfo = getjobChainHistoryInfoObject("test");

    // using the current job chain name and the given limit        
    // var jobChainHistoryInfo = getjobChainHistoryInfoObject( "", 30 );

    // using the given job chain name and default limit
    // var jobChainHistoryInfo = getjobChainHistoryInfoObject( "jobchain1" );

    // using the given job chain name and the given limit
    // var jobChainHistoryInfo = getjobChainHistoryInfoObject( "jobchain1", 20 );

    // using the given job chain name and a given order_id
    // var jobChainHistoryInfo = getjobChainHistoryInfoObject( "jobchain1(order_id)", 20 );

    // reporting some info on job runs

    report( jobChainHistoryInfo.getLastCompleted() );
    report( jobChainHistoryInfo.getRunning() );
    report( jobChainHistoryInfo.getLastCompletedSuccessful() );
    report( jobChainHistoryInfo.getLastCompletedWithError() );

    // report on currently running job
    report( jobChainHistoryInfo.getLastExecution() );
 
    spooler_log.info("isStartedToday: " + jobChainHistoryInfo.isStartedToday());
    spooler_log.info("isStartedTodayCompletedSuccessful: " + jobChainHistoryInfo.isStartedTodayCompletedSuccessful());
    spooler_log.info("isStartedTodayCompletedWithError: " + jobChainHistoryInfo.isStartedTodayCompletedWithError());
    spooler_log.info("isStartedTodayCompleted: " + jobChainHistoryInfo.isStartedTodayCompleted());
    spooler_log.info("isCompletedToday: " + jobChainHistoryInfo.isCompletedToday());
    spooler_log.info("isCompletedTodaySuccessful: " + jobChainHistoryInfo.isCompletedTodaySuccessful());
    spooler_log.info("isCompletedTodayWithError: " + jobChainHistoryInfo.isCompletedTodayWithError());

    spooler_log.info("endedAfter: " + jobChainHistoryInfo.endedAfter("03:00:00"));
    spooler_log.info("endedWithErrorAfter: " + jobChainHistoryInfo.endedWithErrorAfter("03:00:00"));
    spooler_log.info("endedSuccessfulAfter: " + jobChainHistoryInfo.endedSuccessfulAfter("03:00:00"));

    spooler_log.info("startedAfter: " + jobChainHistoryInfo.startedAfter("03:00:00"));
    spooler_log.info("startedWithErrorAfter: " + jobChainHistoryInfo.startedWithErrorAfter("03:00:00"));
    spooler_log.info("startedSuccessfulAfter: " + jobChainHistoryInfo.startedSuccessfulAfter("03:00:00"));

 

    spooler_log.info("isStartedToday:" + jobChainHistoryInfo.queryHistory("isStartedToday"));
    spooler_log.info("isStartedTodayCompletedSuccessful:" + jobChainHistoryInfo.queryHistory("isStartedTodayCompletedSuccessful"));
    spooler_log.info("isStartedTodayCompletedWithError:" + jobChainHistoryInfo.queryHistory("isStartedTodayCompletedWithError"));
    spooler_log.info("isStartedTodayCompleted:" + jobChainHistoryInfo.queryHistory("isStartedTodayCompleted"));

Code Block

language	js
collapse	true

function spooler_process()  {

    // using the current job name and default limit
    var jobHistoryInfo = getJobHistoryInfoObject();

    // using the current job name and the given limit        
    // var jobHistoryInfo = getJobHistoryInfoObject( "", 30 );

    // using the given job name and default limit
    // var jobHistoryInfo = getJobHistoryInfoObject( "job1" );

    // using the given job name and the given limit
    // var jobHistoryInfo = getJobHistoryInfoObject( "job1", 20 );

    // reporting some info on job runs
    report( jobHistoryInfo.getRunning() );
    report( jobHistoryInfo.getLastCompleted() );
    report( jobHistoryInfo.getLastCompletedSuccessful() );
    report( jobHistoryInfo.getLastCompletedWithError() );

    // report on currently running job
    report( jobHistoryInfo.getLastExecution() );
 
    spooler_log.info("isStartedTodayisCompletedToday: " + jobHistoryInfojobChainHistoryInfo.isStartedTodayqueryHistory("isCompletedToday"));
    spooler_log.info("isStartedTodayCompletedSuccessfulisCompletedTodaySuccessfully: " + jobHistoryInfo.isStartedTodayCompletedSuccessful(jobChainHistoryInfo.queryHistory("isCompletedTodaySuccessful"));
    spooler_log.info("isStartedTodayCompletedWithErrorisCompletedTodayWithError: " + jobHistoryInfojobChainHistoryInfo.isStartedTodayCompletedWithErrorqueryHistory("isCompletedTodayWithError "));
        
    //since 1.10.2 1.9.8 also possible
    spooler_log.info("isStartedTodayCompleted: " + jobHistoryInfo.isStartedTodayCompleted("isCompletedAfter:" + jobChainHistoryInfo.queryHistory("isCompletedAfter(-1:10:48:33)"));
    spooler_log.info("isCompletedTodayisCompletedWithErrorAfter: " + jobHistoryInfo.isCompletedToday(jobChainHistoryInfo.queryHistory("isCompletedWithErrorAfter(03:00:00)"));
    spooler_log.info("isCompletedTodaySuccessfulisCompletedSuccessfulAfter: " + jobHistoryInfo.isCompletedTodaySuccessful());jobChainHistoryInfo.queryHistory("isCompletedSuccessfulAfter(03:00:00)"));

    spooler_log.info("isCompletedTodayWithErrorisStartedAfter: " + jobHistoryInfo.isCompletedTodayWithError(jobChainHistoryInfo.queryHistory("isStartedAfter(-1:10:48:33)"));

    spooler_log.info("endedAfterisStartedWithErrorAfter: " + jobHistoryInfojobChainHistoryInfo.endedAfterqueryHistory("isStartedWithErrorAfter(03:00:00)"));
    spooler_log.info("endedWithErrorAfterisStartedSuccessfulAfter: " + jobHistoryInfojobChainHistoryInfo.endedWithErrorAfterqueryHistory("isStartedSuccessfulAfter(03:00:00)"));

    // example how to convert Date fields (start date));
    if ( jobChainHistoryInfo.getLastCompletedSuccessful().found ) {
    spooler_log.info("endedSuccessfulAfter: " + jobHistoryInfo.endedSuccessfulAfter("03:00:00"));

    spooler_log.info("startedAfter: " + jobHistoryInfo.startedAfter("03:00:00"));
    spooler_log.info("startedWithErrorAfter: " + jobHistoryInfo.startedWithErrorAfter("03:00:00"));
    spooler_log.info("startedSuccessfulAfter: " + jobHistoryInfo.startedSuccessfulAfter("03:00:00"));

    // example how to convert Date fields (start date)
    if ( jobHistoryInfo.getLastCompletedSuccessful().found ) {
    var d = jobChainHistoryInfo.getLastCompletedSuccessful().start;
        if (d != null) {
            var d2 = new Date(d.getTime());
            spooler_log.info ("------->" + d2.getFullYear() );
        }
 var d = jobHistoryInfo.getLastCompletedSuccessful().start;
        if (d != null) {
         }

    spooler_log.info ( "check if the job chain started on the previous day before a specific point in time" );
    var d2jobChainHistoryInfo = new Date(d.getTime());
       getjobChainHistoryInfoObject( "jobchain1", "", "-1:10:43:56" );
     spooler_log.info ( "------->completedBefore -1:10:43:56: " + d2jobChainHistoryInfo.getFullYearisCompletedBefore() );
        }
    }

    spooler_log.info ( "check if the job started on the previous day before a specific point in time"completedWithErrorBefore -1:10:43:56: " + jobChainHistoryInfo.isCompletedWithErrorBefore() );
    spooler_log.info ( "completedSuccessfulBefore -1:10:43:56: " + jobChainHistoryInfo.isCompletedSuccessfulBefore() );

    var jobHistoryInfo = getJobHistoryInfoObject( "", "", "-1:10:43:56" );//since 1.10.2 1.9.8 also possible
    spooler_log.info ( "endedBeforecompletedBefore -1:10:43:56: " + jobHistoryInfojobChainHistoryInfo.getLastCompletedqueryHistory("isCompletedBefore").found );
    spooler_log.info ( "endedBeforeWithErrorcompletedWithErrorBefore -1:10:43:56: " + jobHistoryInfojobChainHistoryInfo.getLastComletedWithErrorqueryHistory("isCompletedWithErrorBefore").found );
    spooler_log.info ( "endedBeforeSuccessfulcompletedSuccessfulBefore -1:10:43:56: " + jobHistoryInfojobChainHistoryInfo.getLastCompletedSuccessfulqueryHistory("isCompletedSuccessfulBefore").found );
     
    return false;
}

function getJobHistoryInfoObjectgetjobChainHistoryInfoObject(jobnamejobchain, limit, timelimit) {
    var jobHistoryjobChainHistory = new Packages.com.sos.jitl.checkrunhistory.JobHistoryJobChainHistory( spooler.delegate );

    if ((jobnamejobchain === undefined) || (jobnamejobchain === "")) {
      jobnamejobchain = spooler_task.order.job_chain.name;
    }
    if (limit === undefined || limit === "") {
       limit = "100";
    }
    if (timelimit === undefined) {
       timelimit = "";
    }

    var jobHistoryInfojobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfogetJobChainInfo( jobnamejobchain, limit, timelimit );
    return jobHistoryInfojobChainHistoryInfo;
}

function report( reportItem ) {
    spooler_log.info( "_____________________________" );
    if (reportItem.found) {
        spooler_log.info( "Name:" + reportItem.name );
        spooler_log.info( "Task IDid: " + reportItem.id );
        spooler_log.info( "Job chain Namename: " + reportItem.jobNamejobChainName );
        spooler_log.info( "Position: " + reportItem.position );
        spooler_log.info( "Start Time: " + reportItem.start );
        spooler_log.info( "End Time: " + reportItem.end );
        spooler_log.info( "Exit CodeDuration: " + reportItem.executionResultduration );
        spooler_log.info( "Error Message: " + reportItem.errorMessageerror );
        spooler_log.info( "Error: " + reportItem.error );
        spooler_log.info( "ErrorCode: " + reportItem.errorCode );
    } else {
        spooler_log.info( "Name: " + reportItem.name + " not found" );
    }
}

...

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

language	js
collapse	true

function spooler_task_before() {
    var jobHistoryjobChainHistory = new Packages.com.sos.jitl.checkrunhistory.JobHistoryJobChainHistory( spooler.delegate );
    var jobHistoryInfojobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfogetJobChainInfo( spooler_task.order.job_chain.name, 100, "" );
    var isRerun = (jobHistoryInfojobChainHistoryInfo.getLastCompletedWithError().found && jobHistoryInfojobCHainHistoryInfo.getLastCompletedWithError().position == 0);

    var params = spooler_task.params;
    params.set_var("IS_RERUN", isRerun );
    spooler_log.info("Job 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 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:

Code Block

language	js

jobHistoryInfojobChainHistoryInfo = jobHistoryjobChainHistory.getJobInfo( "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 = jobHistory.getJobInfo( "job1", 100, "" );

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

...

Space shortcuts

Page tree

Versions Compared

Old Version 1

New Version 2

Key

Feature

JobChainHistory Object

JobHistoryInformation Object

JobChainHistoryInformation Object

JobSchedulerHistoryInfoEntry Object

Usage

Use with a Job Script