Skip to end of metadata
Go to start of metadata

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 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:

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.

SyntaxExplanation
<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

FunctionArgumentsDefaultExplanation
isStartedstartedFrom,
startedTo, count
startedFrom=0d, startedTo=0d,  count=1
  • Scope: specifies that the workflow or job started without consideration if it completed or is still running.
  • Default Period: start on the same day.
isCompletedstartedFrom,
startedTo, completedFrom, completedTo, count
completedFrom=0d, completedTo=0d,  count=1
  • Scope: specifies that the workflow or job completed without consideration of success of failure.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.
isCompletedSuccessfulstartedFrom,
startedTo, completedFrom, completedTo, count
completedFrom=0d, completedTo=0d,  count=1
  • Scope: specifies that the workflow or job completed successfully.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.
isCompletedFailedstartedFrom,
startedTo, completedFrom, completedTo, count
completedFrom=0d,  completedTo=0d, count=1
  • Scope: specifies that the workflow or job failed.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.
lastCompletedSuccessfulstartedFrom,
startedTo, completedFrom, completedTo, count
completedFrom=0d,  completedTo=0d, count=1
  • Scope: specifies that the last run of the job completed successfully.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.
lastCompletedFailedstartedFrom,
startedTo, completedFrom, completedTo, count
completedFrom=0d,  completedTo=0d, count=1
  • Scope: specifies that the last run of the workflow or job failed.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.
lastCompletedSuccessful

startedFrom,
startedTo, completedFrom, completedTo, count

completedFrom=0d,  completedTo=0d, count=1
  • Scope: specifies that the last run of the workflow or job completed successfully.
  • Arguments: if the argument startedFrom is specified, then the default value of the startedTo argument is 0d.
  • Default Period: start and completion on the same day.

Arguments

ArgumentDefaultExplanation
startedFrom0dThe workflow or job started after the given date.
startedTo0dThe workflow or job started before the given date.
completedFrom0dThe workflow or job completed after the given date.
completedTo0dThe workflow or job completed before the given date.
count1The 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.
  • 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

ExampleExplanation
isStartedSpecifies that the workflow or job started today.
isCompletedSpecifies that the workflow or job completed today independently from its start date.
isCompletedSuccessfulSpecifies that the workflow or job completed successfully today independently from its start date.
isCompletedFailedSpecifies 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.
lastCompletedSuccessfulSpecifies that the last run of the workflow or job completed successfully.
lastCompletedFailedSpecifies 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:

NameRequiredDefault ValuePurpose
queryyesn/a

Specifies the expression that is used to look up the execution history, for example isCompleted, isCompletedSuccessful etc., for the full list see Queries.

workflow

non/a

Specifies the name of a workflow for which the execution history is looked up. A workflow name or job name has to be specified.

jobnon/aSpecifies the name of a job for which the execution history is looked up. A workflow name or job name has to be specified.
controller_idnon/aThe 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 VariableData TypePurposeExample
js7CheckHistoryResultBoolean

Returns the Boolean result of the query.
Note: The query result is similarly returned with the returnCode return variable and the values 0=true, 1=false.

true, false

js7CheckHistoryResultControllerId

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
js7CheckHistoryResultWorkflowString

Returns the workflow name 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 workflow name of the youngest resulting history entry.

check_history
js7CheckHistoryResultJobString

Returns the job name 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 job name of the youngest resulting history entry.

check-history-job
js7CheckHistoryResultStartedDate

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
js7CheckHistoryResultCompletedDate

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
js7CheckHistoryQueryString

Returns the value of the query argument.

Returns a copy of the value of the query argument that was used with the query.

isStarted

js7CheckHistoryQueryControllerId

String

Returns the value of the controller_id argument.

Returns a copy of the value of the controller_id argument that was used with the query.

controller
js7CheckHistoryQueryWorkflowString

Returns the value of the workflow argument.

Returns a copy of the value of the workflow argument that was used with the query.

accounting
js7CheckHistoryQueryJobString

Returns the value of the job argument.

Returns a copy of the value of the job argument that was used with the query.

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:

Agent private.conf file configuration
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 the js7 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 or js7.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 and password 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.
    • 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.

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.




  • No labels