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
Functions and Arguments
Queries are specified from a function and optional arguments.
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. |
Syntax
Syntax | Explanation |
---|---|
<function> | Functions can be used without argument by stating the name of the function. |
<function>( argument[, argument] ) | Functions can optionally be specified with one or more arguments that are separated by commas. |
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=-1, startedTo=-1d ) | Specifies that the last run of the workflow or job started in the given period and completed successfully today. |
lastCompletedFailed( startedFrom=-1, startedTo=-1d ) | Specifies that the last run of the workflow or job started in the given period and failed today. |
lastCompletedSuccessful( completedFrom=-1, completedTo=-1d ) | Specifies that the last run of the workflow or job completed successfully in the given period. |
lastCompletedFailed( completedFrom=-1, 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 under: 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 |
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 |
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 account="/myAccounts/joc@username" password="/myAccounts/joc@password" # Option 2: Use of account and password account="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
For JS7 - Certificate based Authentication 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.
- 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.
User Account / Password Authentication
For user account/password authentication configured with the ./config/private/private.conf
file
- the
url
configuration item is required as explained above. - the user
account
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.cs-key
: Specifies the path to a KeePass key file.cs-password
: Specifies the password for the KeePass database file.account
: Specifies the path to the entry in the KeePass database that holds the account name.password
: Specifies the path to the entry in the KeePass database that holds the password.
- 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 3rd parties.
- with the following settings:
- Option 2: Use of user account and password
- with the following settings:
account
: Specifies the account name.password
: Specifies the plain text password.
- 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 job dependencies
TODO