Introduction
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: pdwNotificationSOSMailPlainText.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 etc., 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 the a function and optional arguments.
Functions
Function | Arguments | Default | Explanation |
---|---|---|---|
isStarted | startedFrom, startedTo, count | startedFrom=0d, count=1 |
|
isCompleted | startedFrom, startedTo, completedFrom, completedTo, count | startedFrom=0d, completedFrom=0d, count=1 |
|
isCompletedSuccessful | startedFrom, startedTo, completedFrom, completedTo, count | startedFrom=0d, completedFrom=0d, count=1 |
|
isCompletedFailed | startedFrom, startedTo, completedFrom, completedTo, count | startedFrom=0d, completedFrom=0d, count=1 |
|
lastCompletedSuccessful | startedFrom, startedTo, completedFrom, completedTo, count | startedFrom=0d, completedFrom=0d, count=1 |
|
lastCompletedFailed | startedFrom, startedTo, completedFrom, completedTo, count | startedFrom=0d, completedFrom=0d, count=1 |
|
lastCompletedSuccessful |
| startedFrom=0d, completedFrom=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 format like this:
2021-12-05
- The date is specified as yyyy-MM-dd
- The time is assumed to be midnight UTC time.
2012-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
2012-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. |
isCompletedSuccessful | Specifies that the workflow or job completed successfully today. |
isCompletedFailed | Specifies that the workflow or job failed today. |
isCompleted( startedFrom=0d ) | Specifies that the workflow or job started today and completed today. It is not considered if 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=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job started after the given point in time. |
isCompletedSuccesful( startedFrom=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job started after the given point in time and completed successfully. |
isCompletedFailed( startedFrom=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job started after the given point in time and failed. |
isCompleted( completedFrom=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job completed after the given point in time. |
isCompletedSuccessful( completedFrom=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job completed successfully after the given point in time. |
isCompletedFailed( completedFrom=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job failed after the given point in time. |
isCompleted( completedFrom=2000-05-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( copmletedFrom=2000-05-05T01:00:00.000Z, completedTo=2022-05-05T01:00:00+02:00 ) | Specifies that the workflow or job completed successfully before the given point in time. |
isCompletedFailed( completedFrom=2000-05-05T01:00:00+02:00, completedTo=2022-05-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 and completed successfully in the given period. |
lastCompletedFailed( startedFrom=-1, startedTo=-1d ) | Specifies that the last run of the workflow or job started and failed in the given period. |
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:
Name | Required | Default Value | Purpose | Example |
---|---|---|---|---|
to | yes | list of mail recipient's e-mail address, multiple e-mail addresses are separated by comma or semicolon | ||
| no | e-mail address used for sending mail |