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 ?
Starting Point
- Users would like to check in individual job scripts or monitor scripts
- at what point in time a specific job has been executed and
- 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 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:
- jobHistoryInfo.getLastCompleted(): to get the last completed run. Doesn't matter whether ended successful or with error.
- jobHistoryInfo.getRunning(): to get the last running entry.
- jobHistoryInfo.getLastCompletedSuccessful(): to get the last completed successful run
- jobHistoryInfo.getLastCompletedWithError(): to get the last completed run, 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. Then assuming the job is still running.
- .executionResult: The exit code
- .errorMessage: The error message
- .error: True if ended with error
- .errorCode: The error code
- In addition to the number of job runs and order runs some more methods are provided:
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. Instead of using the methods you can also use the .queryHistory method with the name of 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 file rest.zip) is needed.
- You have to configure the correct JOC Url and the user account there.
- For this the configuration stored in /sos/rest (see attached file rest.zip) is needed.
- No parameters are necessary for the monitor. The user and password are not necessary per job/order configuration.
- The job /sos/rest/createApiAccessToken must be configured
- The job reads the value for the joc_url and the user credentials from the file config/.private.conf
- The values are stored in joc.webservice.jitl in the key joc.account 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.url = "http://localhost:4446/joc/api" } joc.account = "root:root" joc.url = "http://localhost:4446/joc/api" 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 parameter "job_name" is set. When job_name does not begin with "/" it is relative to the actual path
- The job looks for job chains when the parameter "job_chain_name" is set. When job_chain_name does not begin with "/" it is relative to the actual path
- The job looks for order when the parameter "job_chain_name" 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 file check_history.zip
- 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