Introduction

• The JS7 offers to perform any operation on orders, workflows, jobs and related objects by the JS7 - REST Web Service API.
  • Note that any operation available with the JOC Cockpit GUI makes use of the REST Web Service API.
  • For detailed information see the Technical Documentation of the 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 Daily Plan 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-dailyplan-orders.sh

Usage

Invoking the script without arguments displays the usage clause:

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

  Options:
    --url=<url>                       | required: JOC Cockpit URL
    --user=<account>                  | required: JOC Cockpit user account
    --password=<password>             | optional: JOC Cockpit password
    --controller-id=<identifier>      | optional: Controller ID
    --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-from=<date>                | optional: orders added to the daily plan starting from the given date will be cancelled, default:
    --date-to=<date>                  | optional: orders added to the given daily plan before the given date will be cancelled, default:
    --workflow-folders=<path[,path]>  | optional: list of folders holding workflows for which orders will be cancelled
    --workflows=<path[,path]>         | optional: list of workflows for which orders will be cancelled
    --schedule-folders=<path[,path]>  | optional: list of folders holding schedules for which orders will be cancelled
    --schedules=<path[,path]>         | optional: list of schedules for which 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
    --show-logs                       | shows log output if --log-dir is used
    --make-dirs                       | creates directories if they do not exist

Options

• --url
  • Specifies the URL by which JOC Cockpit is accessible using <http|https>://<host>:<port>.
  • Example: http://centostest-primary.sos:4446
  • Example: https://centostest-primary.sos:4443
• --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.
• --controller-id
  • Specifies the identification of the Controller that holds related orders.
• --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-from
  • Specifies the date and time in ISO format of the daily plan date, for example 2023-10-23.
  • Dates can be calculated from the date command.
    • --date-to="$(TZ=Europe/London date +'%Y-%m-%d')" specifies the daily plan date before the current day in the Europe/London time zone.
    • --date-to="$(TZ=Europe/London date --date="1 day ago" +'%Y-%m-%d')" specifies the daily plan date before yesterday.
• --date-to
  • Specifies the date and time in ISO format of the daily plan date, for example 2023-10-23. If not specified the the value of the --date-from option is assumed.
  • Dates can be calculated from the date command.
    • --date-to="$(TZ=Europe/London date +'%Y-%m-%d')" specifies the daily plan date before the current day in the Europe/London time zone.
    • --date-to="$(TZ=Europe/London date --date="1 day ago" +'%Y-%m-%d')" specifies the daily plan date before yesterday.
• --workflow-folders
  • Specifies one or more JOC Cockpit inventory folders from absolute paths - separated by comma - holding workflows for which orders will be cancelled.
  • For example --workflow-folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution will cancel orders 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 should be cancelled.
  • 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.
• --schedule-folders
  • Specifies one or more JOC Cockpit inventory folders from absolute paths - separated by comma - holding schedules for which orders will be cancelled.
  • For example --workflow-folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution will cancel orders from schedules in the given folders.
  • If the --recursive switch is used then sub-folders will be looked up recursively.
• --schedules
  • Specifies one or more schedules - separated by comma - for which orders should be cancelled.
  • For example --workflows=/ProductDemo/CyclicExecution/Cyclic-Check,/ProductDemo/ScheduledExecution/Daily-EOD will consider orders created from the Cyclic-Check and Daily-EOD schedules 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 --workflow-folders or --schedule-folders option is used.
• -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 orders from today's Daily Plan

./cancel-dailyplan-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --date-to="$(date +'%Y-%m-%d')"

# cancels orders of today's daily plan
# implies that the system time zone is used (default)

Cancel orders from the Daily Plan two days ago

./cancel-dailyplan-orders.sh \
    --url=https://joc-2-0-primary:7443 \
    --cacert=/home/sos/jstest/certs/root-ca.pem \
    --user=root \
    -p \
    --date-to="$(TZ=Europe/London date --date="2 day ago" +'%Y-%m-%d')" \
    --time-zone=Europe/London
 
# cancels orders from yesterday's daily plan
# 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

Cancel orders from the Daily Plan for a date range

./cancel-dailyplan-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --date-from="$(TZ=Europe/London date --date="10 day ago" +'%Y-%m-%d')" \
    --date-to="$(TZ=Europe/London date --date="2 day ago" +'%Y-%m-%d')" \
    --time-zone=Europe/London
 
# cancels orders from the daily plan between 10 days ago and 2 days ago
# specifies the date from an individual time zone

Cancel orders from the Daily Plan limited by a list of workflow folders

./cancel-dailyplan-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --date-to="$(date +'%Y-%m-%d')" \
    --workflow-folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution \
    --recursive

# cancels orders from today's Daily Plan
# limits cancellation to orders for workflows from the given folders
# looks up sub-folders recursively

Cancel orders from the Daily Plan limited by a list of workflows

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

# cancels orders from today's Daily Plan
# limits cancellation to orders for the given list of workflows

Cancel orders from the Daily Plan limited by a list of schedule folders

./cancel-dailyplan-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --date-to="$(date +'%Y-%m-%d')" \
    --schedule-folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution \
    --recursive

# cancels orders from today's Daily Plan
# limits cancellation to orders created from schedules from the given folders
# looks up sub-folders recursively

Cancel orders from the Daily Plan limited by a list of schedules

./cancel-dailyplan-orders.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --date-to="$(date +'%Y-%m-%d')" \
    --schedules=/ProductDemo/CyclicExecution/Cyclic-Check,/ProductDemo/ScheduledExecution/Daily-EOD

# cancels orders from today's Daily Plan
# limits cancellation to orders created by the given list of schedules

Further Resources

• JS7 - How to clean up the Daily Plan from past Dependencies
• JS7 - How to cancel orders using the REST Web Service API from the Shell
• JS7 - How to delete notices using the REST Web Service API from the Shell