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 calledrest
, containing a JobcreateApiAccessToken.job.xml
and a Job ChaincreateApiAccessToken.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-525Getting issue details... STATUS ). - A user that has been granted at least the
sos:products:joc_cockpit:history:view
permission has to be specified in theprivate.conf
file. Note that the api_user role defined in theshiro.ini-example
file has these permissions by default. More information about theprivate.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 attachedrest.zip
file) is needed.- You have to configure the correct JOC Url and the user account there.
- For this the configuration stored in
- 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 job reads the value for the joc_url and the user credentials from the
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.
<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.