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 delete notices created by the JS7 - PostNotices Instruction or by user intervention. In a situation when not all notices have been removed by use of the JS7 - ConsumeNotices Instruction in workflows, users might want to clean-up notices from the JS7 - Daily Plan.

Delete Notices Script

The script is provided for download and can be used to automate deletion of notices.

• The script is available for Linux and MacOS® using bash shell.
• The script terminates with exit code 0 to signal successful deletion of notices, 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 notices 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 ships with the MIT license, see https://opensource.org/licenses/MIT.

Download

Download: delete-notices.sh

Usage

Invoking the script without arguments displays the usage clause:

Usage: delete-notices.sh [Options] [Switches]

  Options:
    --url=<url>                   | required: JOC Cockpit URL, default:
    --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=<date>                 | optional: notices created for the given date will be deleted, default: <yesterday>
    --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
    --folders=<path[,path]>       | optional: list of folders holding notice boards for which notices will be deleted
    --notice-boards=<path[,path]> | optional: list of notice boards for which notices will be deleted
    --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
• --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
  • Specifies the date in ISO format for which notices will be deleted. The default value <yesterday> indicates the previous day.
    • An absolute date has to be specified, for example 2023-10-23 will affect notices created for that date. 
  • Dates can be calculated from the date command.
    • --date="$(TZ=Europe/London date --date="1 day ago" +'%Y-%m-%d')" specifies to delete notices created for a date before the current day in the Europe/London time zone.
    • --date="$(TZ=Europe/London date --date="2 day ago" +'%Y-%m-%d')" specifies to delete notices created for execution a day before yesterday.
• --time-zone
  • Specifies the time zone to be used for the --date option. By default the system time zone is used.
  • The time zone is specified from an identifier as explained by https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, for example --time-zone=Europe/London. 
• --folders
  • Specifies one or more JOC Cockpit inventory folders from absolute paths - separated by comma - holding notice boards for which notices have been created.
  • For example --folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution will delete notices created for notice boards in the given folders.
  • If the --recursive switch is used then sub-folders will be looked up recursively.
• --notice-boards
  • Specifies one or more notice boards - separated by comma - from which notices will be deleted.
  • For example --notice-boards=/ProductDemo/CyclicExecution/Begin-of-Day,/ProductDemo/ScheduledExecution/End-of-Day will consider notices from the Begin-of-Day and End-of-Day notice boards in 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: delete-notices.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
  • For example: delete-notices.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.
• -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: deletion of notices successfully initiated
• 1: argument errors
• 3: no notices found
• 4: JS7 REST Web Service is not reachable or reports errors

Examples

The following examples illustrate typical use cases.

Delete notices to yesterday's Daily Plan date

./delete-notices.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller

# deletes notices created for the previous day (default)
# implies that the system time zone is used (default)

Delete notices to a Daily Plan date two days ago

./delete-notices.sh \
    --url=https://joc-2-0-primary:7443 \
    --cacert=/home/sos/jstest/certs/root-ca.pem \
    --user=root \
    -p \
    --controller-id=controller \
    --date="$(TZ=Europe/London date --date="2 day ago" +'%Y-%m-%d')" \
    --time-zone=Europe/London
 
# deletes notices for the Daily Plan date two days ago
# 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

Delete notices from a list of folders

./delete-notices.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller \
    --folders=/ProductDemo/CyclicExecution,/ProductDemo/ScheduledExecution \
    --recursive

# deletes notices created for the previous day (default)
# limits deletion of notices to notice boards from the given folders
# looks up sub-folders recursively

Delete notices from a list of notice boards

./delete-notices.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller \
    --notice-boards=/ProductDemo/CyclicExecution/Begin-of-Day,/ProductDemo/ScheduledExecution/End-of-Daily-EOD

# deletes notices created for the previous day (default)
# limits deletion to notices created by the given list of notice boards

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