Provide a function for checking the job history in job monitors by use of web services

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 Proposal

• 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 informations 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 startet
• .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 startet today. Doesn't matter whether ended successful, with error or still running

  • boolean isStartedTodayCompletedSuccessful()

    • true, if the job has been startet today and ended today successful.

  • jobHistoryInfo.isStartedTodayCompletedWithError()

    • true, if the job has been startet today and ended today with error

  • jobHistoryInfo.isStartedTodayCompleted()

    • true, if the job has been startet today. Doesn't matter whether ended successful or with error

  • jobHistoryInfo.isCompletedToday()

    • true, if the job has been ended today. Doesn't matter whether ended successful or with error or whether startet some days before today.

  • jobHistoryInfo.isCompletedTodaySuccessful()

    • true, if the job has been ended today successful. Doesn't matter whether startet some days before today.

  • jobHistoryInfo.isCompletedTodayWithError()

    • true, if the job has been ended today with error. Doesn't matter whether startet some days before today.

  • jobHistoryInfo.isCompletedAfter("03:00:00")

    • true, if the job has been ended after the given time. To specify a e.g. 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 been ended with error after the given time. To specify a e.g. yesterday use "-1:03:00:00" .

  • jobHistoryInfo.isCompletedSuccessfulAfter("03:00:00")

    • true, if the job has been ended successful after the given time. To specify a e.g. yesterday use "-1:03:00:00" .

  • jobHistoryInfo.isCompletedSuccessfulAfter("03:00:00")

    • true, if the job has been ended successful after the given time. To specify a e.g. yesterday use "-1:03:00:00" .

  • jobHistoryInfo.startedAfter("03:00:00")

    • true, if the job has been startet after the given time. To specify a e.g. 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 startet after the given time and ended with error. To specify a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.startedSuccessfulAfter("03:00:00")

    • true, if the job has been startet after the given time and ended successful. To specify a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.isCompletedBefore()

    • true, if the job has been completed before the given time. To specify a e.g. 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 error before the given time. To specify a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.isCompletedSuccessfulBefore()

    • true, if the job has been completed successful before the given time. To specify a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.lastCompletedIsEndedBefore.order("03:00:00")

    • true, if the last completion of the job is ended before the given time. To specify a e.g. 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 a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.lastCompletedWithErrorIsEndedBefore("03:00:00")

    • true, if the last completion with error of the job is before the given time. To specify a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.lastCompletedIsStartedBefore("03:00:00")

    • true, if the last completion of the job is before the given time. To specify a e.g. 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 is before the given time. To specify a e.g. yesterday use "-1:03:00:00".

  • jobHistoryInfo.lastCompletedWithErrorIsStartedBefore("03:00:00")

    • true, if the last completion with error of the job is before the given time. To specify a e.g. 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
e.g. jobHistoryInfo.queryHistory("isCompletedAfter(-1:10:48:33)")

Using Rest Webservices

The implementation uses the rest webservices /orders/history and /tasks/history. No database connection is neccessary.

How to create a valid access token

• There must be a valid access token for a user that have the permission sos:products:joc_cockpit:history:view
  • (e.g. api_user with the role api_user).
• To make sure that this user is logged in you can use the pre processing monitor com.sos.jitl.restclient.CreateApiAccessToken (see Example)
• The monitor will check, whether there is a valid access token
• If not a access token will be created
  • 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.
• No parameters are neccessary for the monitor. The user and password are not neccessary 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/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

Job /sos/rest/createApiAccessToken

<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

• joc.account is base64 encoded. e.g. "api_user:api_user" is base64 encoded YXBpX3VzZXI6YXBpX3VzZXI=

  joc.webservice.jitl{
      joc.account="YXBpX3VzZXI6YXBpX3VzZXI="
      joc.url = "http://localhost:4446"
  
  }
  
  joc.account = "root:root"
  joc.url = "http://localhost:4446/joc/api"
  http.timeout = 5000
  

Example using the preprocessor com.sos.jitl.restclient.CreateApiAccessToken

<?xml version="1.0" encoding="ISO-8859-1"?>

<job  name="job_check_javascript">
    <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

Instead of using the API in a JavaScript implementation there are Java Implementation available

<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: Checking a given job. For each funciton there is one example order
• job_chain_check_job_chain_history: Checking a given job chain. For each funciton there is one example order
• job_check_javascript: A java script example to check a given job
• job_chain_check_javascript: A java script example to check a given job chain