Introduction

FEATURE AVAILABILITY STARTING FROM RELEASE 2.4.0

The JITL CheckHistoryJob template can be used to check past executions of workflows and jobs.

• The job template makes use of the JS7 - REST Web Service API to retrieve information from the JS7 - History.
  • The job template authenticates with the JS7 - REST Web Service API by use of user account/password and/or by use of a certificate, for details see JS7 - Authentication.
  • For details about configuration items see JS7 - JITL Common Authentication.
• The job template checks the execution history of workflows and jobs
  • for execution with a start date or completion date in the given period,
  • for successful or failed execution results.

Usage

When defining the job either:

• invoke the Wizard that is available from the job properties tab in the Configuration view and select the JITL CheckHistoryJob and relevant arguments from the Wizard

or

• specify the JITL job class and com.sos.jitl.jobs.checkhistory.CheckHistoryJob Java class name and add arguments specifying what to send and where mail should be sent as explained in the documentation below.

Example

Download (upload .json): pdwCheckHistory.workflow.json

You can use the job wizard like this:

Explanation:

• Add an empty job from the instruction panel.
• Specify a name and a label for the job.
• Select an Agent.

In a next step invoke the job wizard that you find in the upper right corner of the job property editor. The wizard brings up the following popup window:

Explanation:

• From the list of available job templates select the CheckHistoryJob.

Then hit the Next button to make the job wizard display available arguments:

Explanation:

• Required Arguments
  • query : Specifies the expression that is used to query the execution history, for example isCompleted, isCompletedSuccessful, for the full list see Queries.
  • One or both of the following arguments are specified:
    • workflow: Specifies the name of a workflow for which the execution history is looked up. 
    • job: Specifies the name of a job for which the execution history is looked up.
    • If both arguments are specified then the job name is looked up in matching workflow names only.
    • Search for workflows and jobs is case-insensitive.
    • Wildcards can be used for both arguments, for example, accounting*, *account*.
      • * : matches zero or more characters
      • ? : matches any single character
• Optional Arguments
  • controller_id:  Optionally the identifier of a Controller can be specified to limit results to workflows and jobs executed with the indicated Controller.
• Note that the the check box provided with each argument has to be selected the argument is to be added to the arguments of the CheckHistoryJob template.

When hitting the Submit button the wizard adds the required arguments to the job which should look like this:

The job arguments can be specified:

• from individual variables as configured using the job wizard,
• by using JS7 - Job Resources.

Queries

Queries determine

• the history status of orders or jobs:
  • completed: the order or job completed successfully or failed.
  • completed successful
  • completed failed
• the period for which the execution history is looked up for orders and jobs that
  • started between two dates
  • completed between two dates
  • with periods being specified as absolute or relative dates

Syntax

Queries are specified from a function and optional arguments.

Functions

Arguments

Absolute Dates

Absolute date can be specified as values to the startedFrom, startedTo, completedFrom and completedTo arguments.

Dates are specified in ISO-8601 format like this:

• 2021-12-05
  • The date is specified as yyyy-MM-dd
  • The time is assumed to be midnight UTC time.
• 2021-12-05T01:30:15
  • The date and time are separated by the T character.
  • The time is specified as hh:mm:ss.
  • The time zone is assumed to be UTC.
• 2021-12-05T01:00:00+02:00
  • In addition to date and time the time zone offset is specified. A + character specifies a positive offset to UTC time, a - character specifies a negative offset.

Relative Dates

Relative dates can be specified as values to the startedFrom, startedTo, completedFrom and completedTo arguments.

Relative dates are specified like this:

• -1s, -2s
  • one second ago, two seconds ago
• -1m, -2m
  • one minute ago, two minutes ago
• -1h, -2h
  • one hour ago, two hours ago
• -1d, -2d
  • one day ago, two days ago
• -1w, -2w
  • one week ago, two weeks ago
• -1M, -2M
  • one month ago, two months ago
• -1y, -2y
  • one year ago, two years ago

Examples

Documentation

The Job Documentation including the full list of arguments can be found from: https://www.sos-berlin.com/doc/JS7-JITL/CheckHistoryJob.xml

Authentication

The Job makes use of the JS7 - REST Web Service API that is available from JOC Cockpit. 

• The job is executed with an Agent and requires a network connection to JOC Cockpit.
• The job has to authenticate with JOC Cockpit, for the related configuration see JS7 - JITL Common Authentication.

Arguments

The CheckHistoryJob template accepts the following arguments:

Return Variables

The CheckHistoryJob template returns the following variables:

Job Dependencies

The CheckHistoryJob template can be used to implement backward job dependencies:

• Jobs based on the CheckHistoryJob template do not fail if the underlying query does not return results.
• Instead, the CheckHistoryJob template provides Return Variables that can be inspected to determine further execution of jobs in a workflow.
• JS7 offers the JS7 - If Instruction to check the values of Return Variables and to decide what instructions to execute next.

Download (upload .json): pdwCheckHistory.workflow.json

Explanation:

• Arguments of the CheckHistoryJob template include to specify the query and workflow that is looked up in the execution history.
• The query isCompletedSuccessful checks if the indicated workflow was successfully executed during the current day.
  
  

Explanation:

• The JS7 - If Instruction is used to check the $returnValue return variable that carries
  • the value 0 if the query of the CheckHistoryJob template returns one or more hits.
  • the value 1 if the query of the CheckHistoryJob template returns no hits.
  • Alternative solutions include to check the value of the $js7CheckHistoryResult return variable for a Boolean value that indicates if the query did return any hits:
    • $js7CheckHistoryResult == true
    • $js7CheckHistoryResult == false
• The above example executes a successor job based on the result of the CheckHistoryJob. Such jobs have access to any Return Variables:
  • If the successor job is a Shell job then
    • Return Variables can be mapped to environment variables like this:
      
      
      
      
    • the job script can make use of environment variables like this:
      
      
      
      
  • If the successor job is a JVM job then Return Variables can be accessed directly.

Further Resources

• JS7 - JITL Common Authentication
• JS7 - JITL Common Variables