JS7 JobScheduler

Space shortcuts

Page tree

Introduction

  • The JS7 offers to perform any operation on orders, workflows, jobs and related objects by the JS7 - REST Web Service API.
  • The REST Web Service API can be accessed from Shell utilities such as curl.
  • In addition, a PowerShell module is available for simplified access to the REST Web Service API. This is described in the JS7 - PowerShell Module article.

The script introduced in this article can be used to cancel orders depending on a number of criteria, for example to clean up a past JS7 - Daily Plan.

Cancel Orders Script

The script is provided for download and can be used to automate cancellation of orders.

  • The script is available for Linux and MacOS® using bash shell.
  • The script terminates with exit code 0 to signal successful cancellation, with exit code 1 for command line argument errors and with exit code 4 for non-recoverable errors. Exit code 3 signals that no matching orders have been found.
  • The script is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.

Prerequisites

The Script requires the jq utility to be available from the operating system. 

jq is ships with the MIT license, see https://opensource.org/licenses/MIT.

Download

Download: cancel-orders.sh

Usage

Invoking the script without arguments displays the usage clause:


Usage
Usage: cancel-orders.sh [Options] [Switches]

  Options:
    --url=<url>                   | required: JOC Cockpit URL
    --controller-id=<identifier>  | required: Controller ID
    --user=<account>              | required: JOC Cockpit user account
    --password=<password>         | optional: JOC Cockpit password
    --ca-cert=<path>              | optional: path to CA Certificate used for JOC Cockpit login
    --client-cert=<path>          | optional: path to Client Certificate used for login
    --client-key=<path>           | optional: path to Client Key used for login
    --date-to=<date>              | optional: orders scheduled before the given date will be cancelled, default: now
    --time-zone=<tz>              | optional: specifies the time zone for the given date, default: <time-zone>
                                              see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    --states=<state[,state]>      | optional: list of states limiting orders that will be cancelled, default: SCHEDULED
                                              PLANNED, PENDING, SCHEDULED, INPROGRESS, RUNNING, SUSPENDED, WAITING, PROMPTING, FAILED, BLOCKED, UNKNOWN
    --folders=<path[,path]>       | optional: list of folders holding workflows for which scheduled orders will be cancelled
    --workflows=<path[,path]>     | optional: list of workflows for which scheduled orders will be cancelled
    --log-dir=<directory>         | optional: path to the directory holding the script's batch log files

  Switches:
    -h | --help                   | displays usage
    -v | --verbose                | displays verbose output
    -p | --password               | asks for password
    -r | --recursive              | specifies folders to be looked up recursively
    -k | --kill                   | specifies that tasks of running orders will be killed
    -t | --sigterm                | specifies that tasks of running orders will be sent a SIGTERM signal before SIGKILL
    --show-logs                   | shows log output if --log-dir is used
    --make-dirs                   | creates directories if they do not exist

Options

  • --url
  • --controller-id
    • Specifies the identification of the Controller that holds related orders.
  • --user
    • Specifies the user account for login to JOC Cockpit. If JS7 - Identity Services are available for Client authentication certificates that are specified with the --client-cert and --client-key options then their common name (CN) attribute has to match the user account.
    • If a user account is specified then a password can be specified using the --password option or interactive keyboard input can be prompted using the -p switch.
  • --password
    • Specifies the password used for the account specified with the --user option to login to JOC Cockpit.
    • Consider use of the -p switch offering a secure option for interactive keyboard input.
  • --cacert
    • Specifies the path to a .pem file that holds the Root CA Certificate and optionally Intermediate CA Certificates to verify HTTPS connections to JOC Cockpit.
  • --client-cert
    • Specifies the path to a .pem file that holds the Client Certificate if HTTPS mutual authentication is used..
  • --client-key
    • Specifies the path to a .pem file that holds the Client Privae Key if HTTPS mutual authentication is used..
  • --date-to
    • Specifies the date and time in ISO format to which orders have been scheduled. The default value now indicates the current point in time.
      • An absolute date, for example 2023-10-23T14:00:00 will affect all orders scheduled for execution before that date. 
      • A relative date, for example  --date-to=-1d (1 day back), --date-to=-2h (2 hours back), --date-to=-30m (30 minutes back).
    • Dates and times can be calculated from the date command.
      • --date-to="$(TZ=Europe/London date +'%Y-%m-%d')T00:00:00" specifies orders scheduled for a date before the current day in the Europe/London time zone.
      • --date-to="$(TZ=Europe/London date --date="1 day ago" +'%Y-%m-%d')T00:00:00" specifies orders scheduled for execution before yesterday.
  • --time-zone
  • --states
    • Specifies one or more states - separated by comma - for which orders should be cancelled. By default the SCHEDULED state is used.
    • Valid states are PLANNED, PENDING, SCHEDULED, INPROGRESS, RUNNING, SUSPENDED, WAITING, PROMPTING, FAILED, BLOCKED, UNKNOWN.
    • For example --states=SCHEDULED,SUSPENDED,FAILED will cancel orders holding any of the given states.
  • --folders
    • Specifies one or more JOC Cockpit inventory folders from absolute paths - separated by comma - holding workflows for which orders have been scheduled.
    • For example --folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution will cancel orders scheduled for workflows in the given folders.
    • If the --recursive switch is used then sub-folders will be looked up recursively.
  • --workflows
    • Specifies one or more workflows - separated by comma - for which orders have been scheduled.
    • For example --workflows=/ProductDemo/CyclicExecution/Cyclic-Check,/ProductDemo/ScheduledExecution/Daily-EOD will consider orders scheduled for the Cyclic-Check and Daily-EOD workflows from the given folders.
  • --log-dir
    • If a log directory is specified then the script will log information about processing steps to a log file in this directory.
    • File names are created according to the pattern: set_job_resource.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
    • For example: set_job_resource.2022-03-19T20-50-45.log

Switches

  • -h | --help
    • Displays usage.
  • -p | --password
    • Asks the user for interactive keyboard input of the password used for the account specified with the --user option..
    • The switch is used for secure interactive input as an alternative to use of the option --password=<password>.
  • -r | --recursive
    • Specifies that folders will be looked up recursively if the --folders option is used.
  • -k | --kill
    • Specifies that tasks of running orders will be killed.
    • If used without the --sigterm switch then orders are immediately killed using a SIGKILL signal corresponding to the command: kill -9.
  • -t | --sigterm
    • Specifies that a SIGTERM signal will be sent to tasks of running orders if the --kill switch is used.
    • The switch allows shell jobs that implement traps to perform some clean-up and to gracefully terminate before being killed by a SIGKILL signal.
  • -v | --verbose
    • Displays verbose log output.
  • --show-logs
    • Displays the log output created by the script if the --log-dir option is used.
  • --make-dirs
    • If directories are missing that are indicated with the --log-dir option then they will be created.

Exit Codes

  • 0: cancellation of orders successfully initiated
  • 1: argument errors
  • 3: no orders found
  • 4: JS7 REST Web Service is not reachable or reports errors

Examples

The following examples illustrate typical use cases.

Cancel late orders to yesterday's Daily Plan date

Example for Cancelling Orders
./cancel-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller \
    --date-to="$(date +'%Y-%m-%d')T00:00:00"

# cancels orders scheduled for a date before begin of the current day
# limits cancellation to orders in the SCHEDULED state (default) 
# implies that the system time zone is used (default)

Cancel failed and suspended orders to a Daily Plan date two days ago

Example for Cancelling Orders
./cancel-orders.sh \
    --url=https://joc-2-0-primary:7443 \
    --cacert=/home/sos/jstest/certs/root-ca.pem \
    --user=root \
    -p \
    --controller-id=controller \
    --date-to="$(TZ=Europe/London date --date="1 day ago" +'%Y-%m-%d')T00:00:00" \
    --time-zone=Europe/London \
    --states=FAILED,SUSPENDED
 
# cancels orders scheduled for a date before yesterday
# establishes the connection to JOC Cockpit by HTTPS and the Root CA Certificate is specified from the path to a .pem file
# asks the user for interactive keyboard input of the password used for the account specified
# specifies the date from an individual time zone
# limits cancellation to orders in the FAILED and SUSPENDED state

Cancel late orders from a list of folders

Example for Cancelling Orders
./cancel-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller \
    --date-to="$(date +'%Y-%m-%d')T00:00:00" \
    --folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution \
    --recursive

# cancels late orders scheduled for yesterday's Daily Plan date
# limits cancellation to orders in the SCHEDULED state (default) for workflows from the given folders
# looks up sub-folders recursively

Cancel late orders from a list of workflows

Example for Cancelling Orders
./cancel-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller \
    --date-to="$(date +'%Y-%m-%d')T00:00:00" \
    --workflows=/ProductDemo/CyclicExecution/Cyclic-Check,/ProductDemo/ScheduledExecution/Daily-EOD

# cancels late orders scheduled for yesterday's Daily Plan date
# limits cancellation to orders in the SCHEDULED state (default) for the given list of workflows

Further Resources