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

Scope

Feature Availability

FEATURE AVAILABILITY STARTING FROM RELEASE 1.11.5

The CheckHistory LINK JITL Job is intended as a replacement for the JobSchedulerCheckRunHistory Job DEPRECATION 1.12 ?

ADVANTAGES ?

More 'accurate' results
Does not ask JobScheduler but the Web Services
Limit parameter change
Limited compatibility with CheckRunHistory (Limit parameter)
Does not use TCP connection CAN IT USE HTTPS OR ONLY HTTP?
Encrypted basic authentication information

Starting Point

Provide users with a method of checking in individual Job or Monitor scripts:
- 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 start.

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.

To create the object:

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

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

Using REST Web Services

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

How to create 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 for private.conf Configuration File

The private.conf file is located in the directory:

/config/private

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

joc.account = "root:root"
joc.url = "http://localhost:4446"
http.timeout = 5000

Example using the `com.sos.jitl.restclient.CreateApiAccessToken` pre-processor

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

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:

<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 parameter check_run_history_result.
The job does not need the pre-processing monitor to get a valid access token. This is implemented internally.

Examples

See 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

Scope

Feature Availability

Starting Point

Feature Description

Using REST Web Services

How to create a valid access token

The `/sos/rest/createApiAccessToken` Job

Example for private.conf Configuration File

Example using the `com.sos.jitl.restclient.CreateApiAccessToken` pre-processor

Available as a Java job

Examples

Space shortcuts

Page tree

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

Scope

Feature Availability

Starting Point

Feature Description

Using REST Web Services

How to create a valid access token

The /sos/rest/createApiAccessToken Job

Example for private.conf Configuration File

Example using the com.sos.jitl.restclient.CreateApiAccessToken pre-processor

Available as a Java job

Examples

The `/sos/rest/createApiAccessToken` Job

Example using the `com.sos.jitl.restclient.CreateApiAccessToken` pre-processor