Checking the job history in job monitors by use of web services

Use

The CheckHistory Job provides a method of using individual Job or Monitor scripts to check:
- at what point in time a specific Job, Job Chain or Order running on a Job Chain has been executed and
- what execution result (success or failure) was created on completion of the Job, Job Chain or Order.
The intention behind checking the job execution history is to enable automated decision making based on the point in time or execution result of a previous Job, Job Chain or Order start.

Scope

Feature Availability

FEATURE AVAILABILITY STARTING FROM RELEASE 1.11.5

The CheckHistory JITL Job is intended as a replacement for the deprecated JobSchedulerCheckRunHistory Job.

While the JobSchedulerCheckRunHistory Job queried the JobScheduler, the CheckHistory Job uses the Web Services to query the reporting database.

Feature Description

A Java object is provided for history checks that can be used:
- in individual jobs that are created with Java or JavaScript.
- in individual job monitors with Java or JavaScript.
The properties and methods of the object provided can be used to:
- get the information for a given Job, Job Chain or Order.

Prerequisites

Up to and including Release 1.12.7, there must be a sub-folder in the live/sos folder called rest, containing a Job createApiAccessToken.job.xml and a Job Chain createApiAccessToken.job_chain.xml. These objects provided by default with a new installation or update of the JOC Cockpit. They are not required for Releases 1.12.8 and newer.
(For details see JITL-525 - Getting issue details... STATUS ).
A user that has been granted at least the sos:products:joc_cockpit:history:view permission has to be specified in the private.conf file. Note that the api_user role defined in the shiro.ini-example file has these permissions by default. More information about the private.conf file can be found below.

Object Creation

To create the object:

function spooler_process()  {
 
    // using the current job name
    var jobHistoryInfo = getJobHistoryInfoObject("job1");
    ...
    return false;
}
 
 function getJobHistoryInfoObject(jobname, timelimit) {
    var jobHistory = new Packages.com.sos.jitl.checkhistory.JobHistory( spooler.delegate );

    if ((jobname === undefined) || (jobname === "")) {
      jobname = spooler_task.job.name;
    }
    if (timelimit === undefined) {
       timelimit = "";
    }

    var jobHistoryInfo = jobHistory.getJobInfo( jobname, timelimit );
    return jobHistoryInfo;
}

Note that in the above example the job1 Parameter in the spooler_process function has to include the full path within the JobScheduler live folder.

Object Methods

The object provides the following methods:

jobHistoryInfo.getLastCompleted()
- to get the last completed run.
- It doesn't matter whether the last run ended successfully or in error.
jobHistoryInfo.getRunning()
- to get the last running entry.
jobHistoryInfo.getLastCompletedSuccessful()
- to get the last successfully completed run
jobHistoryInfo.getLastCompletedWithError()
- to get the last completed run that ended with error.

Each object provides:

.found
- Whether such entry has been found
.name
- The name of the object
.id
- The task id
.jobName
- The name of the job
.top
- True if the entry is the first in the history.
.start:
- When the job was started
.end:
- The end time of the job. Can be empty. It is then assumed the job is still running.
.executionResult
- The exit code
.errorMessage
- The error message
.error
- True if ended with error
.errorCode
- The error code

The following methods are provided in addition to the number of Job and Order runs:

```
boolean jobHistoryInfo.isStartedToday()
```
- true, if the job has been started today.
- Doesn't matter whether ended successful, with error or still running.
```
boolean isStartedTodayCompletedSuccessful()
```
- true, if the job has been started today and ended today successful.
```
jobHistoryInfo.isStartedTodayCompletedWithError()
```
- true, if the job has been started today and ended today with error.
```
jobHistoryInfo.isStartedTodayCompleted()
```
- true, if the job has been started today. Doesn't matter whether ended successful or with an error.
```
jobHistoryInfo.isCompletedToday()
```
- true, if the job has ended today.
- Doesn't matter whether ended successful or with error or whether started a number of days before today.
```
jobHistoryInfo.isCompletedTodaySuccessful()
```
- true, if the job has ended today successful.
- Doesn't matter whether started some a number of before today.
```
jobHistoryInfo.isCompletedTodayWithError()
```
- true, if the job has ended today with an error.
- Doesn't matter whether started a number of days before today.
```
jobHistoryInfo.isCompletedAfter("03:00:00")
```
- true, if the job has ended after the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
- Doesn't matter whether ended successful or with error.
```
jobHistoryInfo.isCompletedWithErrorAfter("03:00:00")
```
- true, if the job has ended with an error after the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.isCompletedSuccessfulAfter("03:00:00")
```
- true, if the job has ended successful after the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.isCompletedSuccessfulAfter("03:00:00")
```
- true, if the job has ended successful after the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.startedAfter("03:00:00")
```
- true, if the job has been started after the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
- Doesn't matter whether ended successful, with error or still running.
```
jobHistoryInfo.startedWithErrorAfter("03:00:00")
```
- true, if the job has been started after the given time and ended with error.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.startedSuccessfulAfter("03:00:00")
```
- true, if the job has been started after the given time and ended successful.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.isCompletedBefore()
```
- true, if the job has been completed before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
- Doesn't matter whether ended successful or with error.
```
jobHistoryInfo.isCompletedWithErrorBefore()
```
- true, if the job has been completed with an error before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.isCompletedSuccessfulBefore()
```
- true, if the job has been completed successful before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.lastCompletedIsEndedBefore.order("03:00:00")
```
- true, if the last completion of the job has ended before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
- Doesn't matter whether ended successful or with error.
```
jobHistoryInfo.lastCompletedSuccessfulIsEndedBefore("03:00:00")
```
- true, if the last successful completion of the job is ended before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.lastCompletedWithErrorIsEndedBefore("03:00:00")
```
- true, if the last completion of the job with an error was before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.lastCompletedIsStartedBefore("03:00:00")
```
- true, if the last completion of the job was before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
- Doesn't matter whether ended successful or with error.
```
jobHistoryInfo.lastCompletedSuccessfulisStartedBefore("03:00:00")
```
- true, if the last successful completion of the job was before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".
```
jobHistoryInfo.lastCompletedWithErrorIsStartedBefore("03:00:00")
```
- true, if the last completion of the job with an error was before the given time.
- To specify, for example, yesterday, use "-1:03:00:00".

Please note that instead of using the methods described above, you can also use the .queryHistory method with the name of the method as a parameter.
For example:

jobHistoryInfo.queryHistory("isCompletedAfter(-1:10:48:33)")

Implementation

Using REST Web Services

This implementation uses the /orders/history and /tasks/history REST web services. A database connection is not necessary.

Creating a valid access token

There must be a valid access token for a user that has the permission:
- sos:products:joc_cockpit:history:view (e.g. api_user with the api_user role).
You can use the com.sos.jitl.restclient.CreateApiAccessToken pre-processing monitor (see the example below) to make sure that this user is logged in.
- Note that the functions provided by this monitor are integrated in the Java job implementation described below.
The monitor will check whether there is a valid access token.
A valid access token will be created if one is not found:
- For this the configuration stored in /sos/rest (see attached rest.zip file) is needed.
  - You have to configure the correct JOC Url and the user account there.
No parameters are necessary for the monitor. The user and password are not necessary per job/order configuration.
The /sos/rest/createApiAccessToken Job must be configured:
- The job reads the value for the joc_url and the user credentials from the config/.private.conf file.
- The values are stored in joc.webservice.jitl in the joc.account key and joc.url.
- If not there the values from root with the same keys will be read.

The `/sos/rest/createApiAccessToken` Job

 <job  order="yes" stop_on_error="no" name="createApiAccessToken">
    <script  language="java" java_class_path="" java_class="com.sos.jitl.restclient.CreateApiAccessToken"/>
    <run_time />
</job>

Example private.conf Configuration File

The private.conf file is located in the /config/private directory.
The value for the joc.acount parameter is username:password base64 encoded.

joc.webservice.jitl{
   joc.account="YXBpX3VzZXI6YXBp"
   joc.url = "http://localhost:4446"
}

This code is used in the check pre-processor of the check_start job in the example download archive.

<job  title="Check the last job run with monitor" stop_on_error="no" order="yes">
    <settings >
        <log_level ><![CDATA[debug9]]></log_level>
    </settings>
    <description >
        <include  file="jobs/JobSchedulerCheckHistory.xml"/>
    </description>
    <params />
    <script  language="java:javascript">
        <![CDATA[function spooler_process()  { 

    // using the current job name 
    var jobHistoryInfo = getJobHistoryInfoObject("job1");
    report( jobHistoryInfo.getLastCompleted() );
    return false;
}

function getJobHistoryInfoObject(jobname, timelimit) {
    var jobHistory = new Packages.com.sos.jitl.checkhistory.JobHistory( spooler.delegate );

    if ((jobname === undefined) || (jobname === "")) {
      jobname = spooler_task.job.name;
    }
    if (timelimit === undefined) {
       timelimit = "";
    }
    var jobHistoryInfo = jobHistory.getJobInfo( jobname, timelimit );
    return jobHistoryInfo;
}

function report( reportItem ) {
    if (reportItem.found) {
        spooler_log.info( "Name:" + reportItem.name );
        spooler_log.info( "Start Time: " + reportItem.start );
        spooler_log.info( "End Time: " + reportItem.end );
    } else {
        spooler_log.info( "Name: " + reportItem.name + " not found" );
    }
}
        ]]>
    </script>

    <monitor  name="apiAccessToken" ordering="0">
        <script  language="java" java_class="com.sos.jitl.restclient.CreateApiAccessToken"/>
    </monitor>

    <run_time />
</job>

Available as a Java job

A Java implementation is available as an alternative to using the API in a JavaScript implementation as described above. Two example Jobs using this implementation are provided in the Check History download linked at the end of this article.

'Check the Last Job Run' Java Job

<job  title="Check the last job run" order="yes" stop_on_error="no">
    <script  language="java" java_class="com.sos.jitl.checkhistory.JobSchedulerCheckHistoryJSAdapterClass"/>
    <run_time />
</job>

The job looks for jobs when the "job_name" parameter is set.
- When job_name does not begin with "/" it is relative to the actual path.
The job looks for job chains when the "job_chain_name" parameter is set.
- When job_chain_name does not begin with "/" it is relative to the actual path.
The job looks for orders when the "job_chain_name" parameter contains an order e.g. my_chain(myId).
- When job_chain_name does not begin with "/" it is relative to the actual path.
The parameter query contains the method to be executed e.g. query=isCompletedAfter (00:10:30).
The return is true|false according to the result of the given method.
The job returns the result in the check_run_history_result parameter.
The job does not need the pre-processing monitor to get a valid access token. This is implemented internally.

Examples

See the attached check_history.zip file.

job_chain_check_job_history:
- Checks a given job. There is an example order for each function.
job_chain_check_job_chain_history:
- Checks a given job chain. There is an example order for each function.
job_check_javascript:
- A JavaScript example to check a given job.
job_chain_check_javascript:
- A JavaScript example to check a given job chain.

Space shortcuts

Page tree

Use

Scope

Feature Availability

Feature Description

Prerequisites

Object Creation

Object Methods

Implementation

Using REST Web Services

Creating a valid access token

The `/sos/rest/createApiAccessToken` Job

Example private.conf Configuration File

Available as a Java job

Examples

Space shortcuts

Page tree

Checking the job history in job monitors by use of web services

Use

Scope

Feature Availability

Feature Description

Prerequisites

Object Creation

Object Methods

Implementation

Using REST Web Services

Creating a valid access token

The /sos/rest/createApiAccessToken Job

Example private.conf Configuration File

Available as a Java job

Examples

The `/sos/rest/createApiAccessToken` Job