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. Operation of the job template requires
- network access from the Agent that executes the job to the JOC Cockpit instance,
- availability of the Controller and of JOC Cockpit,
- authentication and authorization with JOC Cockpit.
- 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.
- 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 andcom.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.
Syntax | Explanation |
---|---|
<function> | Functions can be used without arguments by stating exclusively the name of the function. |
<function>( argument[, argument] ) | Functions can optionally be specified with one or more arguments that are separated by commas. |
Functions
Function | Arguments | Default | Explanation |
---|---|---|---|
isStarted | startedFrom, startedTo, count | startedFrom=0d, startedTo=0d, count=1 |
|
isCompleted | startedFrom, startedTo, completedFrom, completedTo, count | completedFrom=0d, completedTo=0d, count=1 |
|
isCompletedSuccessful | startedFrom, startedTo, completedFrom, completedTo, count | completedFrom=0d, completedTo=0d, count=1 |
|
isCompletedFailed | startedFrom, startedTo, completedFrom, completedTo, count | completedFrom=0d, completedTo=0d, count=1 |
|
lastCompletedSuccessful | startedFrom, startedTo, completedFrom, completedTo, count | completedFrom=0d, completedTo=0d, count=1 |
|
lastCompletedFailed | startedFrom, startedTo, completedFrom, completedTo, count | completedFrom=0d, completedTo=0d, count=1 |
|
lastCompletedSuccessful |
| completedFrom=0d, completedTo=0d, count=1 |
|
Arguments
Argument | Default | Explanation |
---|---|---|
startedFrom | 0d | The workflow or job started after the given date. |
startedTo | 0d | The workflow or job started before the given date. |
completedFrom | 0d | The workflow or job completed after the given date. |
completedTo | 0d | The workflow or job completed before the given date. |
count | 1 | The minimum number of history items that is expected to be returned for the given period. By default a single history item is expected. The CheckHistoryJob will fail if the number of expected history entries specified by this argument exceeds the number of history items returned. |
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.
- The date and time are separated by the
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
Example | Explanation |
---|---|
isStarted | Specifies that the workflow or job started today. |
isCompleted | Specifies that the workflow or job completed today independently from its start date. |
isCompletedSuccessful | Specifies that the workflow or job completed successfully today independently from its start date. |
isCompletedFailed | Specifies that the workflow or job failed today independently from its start date. |
isCompleted( startedFrom=0d ) | Specifies that the workflow or job started today and completed today. It is not considered if the workflow or job completed successfully or failed. |
isCompletedSuccessful( startedFrom=0d ) | Specifies that the workflow or job started today completed successfully today. |
isCompletedFailed( startedFrom=0d ) | Specifies that the workflow or job started today and failed today. |
isStarted( startedFrom=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job started after the given point in time. |
isCompletedSuccesful( startedFrom=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job started after the given point in time and completed successfully. |
isCompletedFailed( startedFrom=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job started after the given point in time and failed. |
isCompleted( completedFrom=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job completed after the given point in time. |
isCompletedSuccessful( completedFrom=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job completed successfully after the given point in time. |
isCompletedFailed( completedFrom=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job failed after the given point in time. |
isCompleted( completedFrom=2021-12-05T01:00:00.000Z, completedTo=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job completed before the given point in time. |
isCompletedSuccesful( completedFrom=2021-12-03T01:00:00+02:00, completedTo=2021-12-05T01:00:00+02:00 ) | Specifies that the workflow or job completed successfully before the given point in time. |
isCompletedFailed( completedFrom=2021-12-04T01:00:00+02:00, completedTo=2022-12-05T01:00:00+02:00 ) | Specifies that the workflow or job failed before the given point in time. |
lastCompletedSuccessful | Specifies that the last run of the workflow or job completed successfully. |
lastCompletedFailed | Specifies that the last run of the workflow or job failed. |
lastCompletedSuccessful( startedFrom=-1d, startedTo=-1d ) | Specifies that the last run of the workflow or job started in the given period and completed successfully today. |
lastCompletedFailed( startedFrom=-1d, startedTo=-1d ) | Specifies that the last run of the workflow or job started in the given period and failed today. |
lastCompletedSuccessful( completedFrom=-1d, completedTo=-1d ) | Specifies that the last run of the workflow or job completed successfully in the given period. |
lastCompletedFailed( completedFrom=-1d, completedTo=-1d ) | Specifies that the last run of the job failed in the given period. |
Documentation
The Job Documentation including the full list of arguments can be found from: https://www.sos-berlin.com/doc/JS7-JITL/CheckHistoryJob.xml
Arguments
The CheckHistoryJob template accepts the following arguments:
Name | Required | Default Value | Purpose |
---|---|---|---|
query | yes | n/a | Specifies the expression that is used to look up the execution history, for example isCompleted, isCompletedSuccessful etc., for the full list see Queries. |
| no | n/a | Specifies the name of a workflow for which the execution history is looked up. A |
job | no | n/a | Specifies the name of a job for which the execution history is looked up. A workflow name or job name has to be specified. |
controller_id | no | n/a | The identifier of a Controller can be specified to limit results to workflows and jobs executed with the indicated Controller. |
Return Variables
The CheckHistoryJob template returns the following variables:
Return Variable | Data Type | Purpose | Example |
---|---|---|---|
js7CheckHistoryResult | Boolean | Returns the Boolean result of the query. | true, false |
| String | Returns the Controller ID of the resulting history entry. The value of the return variable is empty if the query returns no result. If the query returns a result then the return variable holds the Controller ID of the youngest resulting history entry. | controller |
js7CheckHistoryResultWorkflow | String | Returns the workflow name of the resulting history entry. The value of the return variable is empty if the query returns no result. | check_history |
js7CheckHistoryResultJob | String | Returns the job name of the resulting history entry. The value of the return variable is empty if the query returns no result. | check-history-job |
js7CheckHistoryResultStarted | Date | Returns the start date and time of the resulting history entry. The value of the return variable is empty if the query returns no result. If the query returns a result then the return variable holds the start date and time of the youngest resulting history entry in ISO-8601 format. | 2012-12-05T01:00:00+02:00 |
js7CheckHistoryResultCompleted | Date | Returns the completion date and time of the resulting history entry. The value of the return variable is empty if the query returns no result. If the query returns a result then the return variable contains the completion date and time of the youngest resulting history entry in ISO-8601 format. | 2012-12-05T01:00:00+02:00 |
js7CheckHistoryQuery | String | Returns the value of the Returns a copy of the value of the | isStarted |
| String | Returns the value of the Returns a copy of the value of the | controller |
js7CheckHistoryQueryWorkflow | String | Returns the value of the Returns a copy of the value of the | accounting |
js7CheckHistoryQueryJob | String | Returns the value of the Returns a copy of the value of the | my-job |
Authentication
The CheckHistoryJob 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.
To this purpose the job template makes use of the Agents ./config/private/private.conf
file to find a number of configuration items that allow authentication:
js7 { auth { ... } configuration { ... } job { ... } web { ... } api-server { # API Server URL url = [ "https://joc-2-0-primary:4443" ] # Option 1: use of a Credential Store cs-file=${js7.config-directory}"/private/secret.kdbx" cs-key=${js7.config-directory}"/private/secret.key" cs-password="secret" # Option 1: use of references to credentials username="cs://myAccounts/joc@username" password="cs://myAccounts/joc@password" # Option 2: use of account and password # username="root" # password="root" } }
Explanation:
- The
api-server
configuration section specifies authentication details for the CheckHistoryJob and can occur in any position directly within thejs7
configuration block. - Configuration items available from this configuration section are explained with the following chapters.
Certificate Based Authentication
JS7 - Certificate based Authentication is configured with the ./config/private/private.conf
file:
- The
url
configuration item is required that specifies the URL of the JS7 REST Web Service API. Typically this corresponds to the JOC Cockpit URL.- Users can set up a number of JOC Cockpit instances that are clustered for automated fail-over.
- Users can set up a load balancer that routes requests to a number of available JOC Cockpit instances.
- For use with the CheckHistoryJob template both active and standby JOC Cockpit instances can be used.
- No further configuration items are used.
- The Client Authentication Certificate has to be available from the keystore file indicated with the
js7.web.https.keystore
orjs7.web.https.client_keystore
settings.- This includes that JOC Cockpit is configured to use a truststore that holds the Root CA Certificate and Intermediate CA Certificate that was used to sign the Agent's Client Authentication Certificate.
- For details see JS7 - JOC Cockpit HTTPS Connections.
User Account / Password Authentication
User account/password authentication is configured with the ./config/private/private.conf
file:
- The
url
configuration item is required as explained above. - The
username
andpassword
can be specified from the following options:- Option 1: Use of a JS7 - Credential Store
- with the following settings:
cs-file:
Specifies the path to a KeePass database file (required).cs-key
: Specifies the path to a KeePass key file (optional).cs-password
: Specifies the password for the KeePass database file (optional).username
: Specifies the path to the entry in the KeePass database that holds the account name (required).password
: Specifies the path to the entry in the KeePass database that holds the password (required).
- that suggest to preferably use a KeePass key file (
cs-key
) to protect the KeePass database. Basically it is pointless to protect a Credential Store by use of a password (cs-password
) that is similarly visible as putting the key under the mat. Use of a key file allows to apply OS ownership and file permissions to protect to the key file from visibility by 3rd parties.
- with the following settings:
- Option 2: Use of user account and password
- with the following settings:
username
: Specifies the account name (required).password
: Specifies the plain text password (required).
- that include both settings to be visible from the configuration file.
- with the following settings:
- Option 1: Use of a JS7 - Credential Store
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
andworkflow
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:
- Return Variables can be mapped to environment variables like this:
- If the successor job is a JVM job then Return Variables can be accessed directly.
- If the successor job is a Shell job then