Introduction

The JS7 offers to perform operations on JOC Cockpit, Controllers and Agents by use of the JS7 - REST Web Service API.
- For detailed information see the Technical Documentation of the REST Web Service API.
- For available CLI operations see JS7 - Unix Shell Command Line Interface.
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 Git Deployment Script offered for Unix Shell can be applied to perform frequently used deployment operations on Git repositories.

Git Deployment Script

Command	Object	Documentation
list-item / store-item / update-item / delete-item	Scheduling Objects such as Workflows	JS7 - Inventory Git Integration JS7 - Profiles - Git Management JS7 - How To - Git Integration
clone / checkout	Git Repository
add / commit / push / pull
get-credentials / store-credentials / delete-credentials

The script is offered for download and can be applied for frequently used deployment operations:

The script is available for Linux and MacOS® using bash shell.
The script terminates with exit code 0 to signal successful execution, 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 objects 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. Examples make use of JS7 Release 2.7.2, bash 4.2, curl 7.29.0 and jq 1.6.0.

Prerequisites

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

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

Download

Download: JS7 - Download (Section: Unix Shell ClI)

Usage

Invoking the script without arguments displays the usage clause:

Usage

Usage: deploy-git.sh [Command] [Options] [Switches]

  Commands:
    list-item           --folder [--recursive] [--local]
    store-item         [--path]  [--type] [--folder] [--recursive] [--local] [--controller-id] 
                                 [-no-draft] [--no-deployed] [--no-released]
    update-item        [--path]  [--type] [--folder] [--recursive] [--local]
    delete-item        [--path]  [--type] [--folder] [--local]
    clone               --folder [--local] --remote-url
    checkout            --folder [--local] [--branch | --tag]
    add                 --folder [--local]
    commit              --folder [--local] --message
    push                --folder [--local]
    pull                --folder [--local]
    get-credentials
    store-credentials   --server --user-account --user-name --user-mail 
                                [--user-password | --user-access-token | --user-private-key]
    delete-credentials  --server

  Options:
    --url=<url>                        | required: JOC Cockpit URL
    --controller-id=<id>               | 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
    --timeout=<seconds>                | optional: timeout for request, default: 60
    --folder=<folder[,folder]>         | optional: inventory folders holding objects
    --path=<path[,path]>               | optional: inventory paths to objects
    --type=<type>                      | optional: object type such as WORKFLOW, SCHEDULE
    --branch=<identifier>              | optional: Git branch identified by name, default: master
    --tag=<tag[,tag]>                  | optional: Git branch identified by tags
    --message=<text>                   | optional: Git commit message
    --server=<host>                    | optional: Git server
    --user-account=<account>           | optional: Git authentication user account
    --user-name=<text>                 | optional: Git authentication user name
    --user-mail=<e-mail>               | optional: Git authentication user e-mail address
    --user-password=<password>         | optional: Git authentication user password
    --user-access-token=<token>        | optional: Git authentication user access token
    --user-private-key=<path>          | optional: Git authentication user private key file
    --remote-url=<url>                 | optional: Git remote repository URL
    --audit-message=<string>           | optional: audit log message
    --audit-time-spent=<number>        | optional: audit log time spent in minutes
    --audit-link=<url>                 | optional: audit log link
    --log-dir=<directory>              | optional: path to directory holding the script's log files

  Switches:
    -h | --help                        | displays usage
    -v | --verbose                     | displays verbose output, repeat to increase verbosity
    -p | --password                    | asks for password
    -l | --local                       | uses repository for local objects
    -r | --recursive                   | specifies folders to be looked up recursively
    -u | --user-password               | asks for Git account password
    --no-draft                         | excludes draft objects
    --no-deployed                      | excludes deployed objects
    --no-released                      | excludes released objects
    --show-logs                        | shows log output if --log-dir is used
    --make-dirs                        | creates directories if they do not exist

Commands

list-item
- Returns the list of scheduling objects from JOC Cockpit's Git repository. The list will be returned in JSON format.
- The command is used alternatively
  - with the --path and --type options to specify an individual object. One of the following object types has to be specified:
    - Deployable object types: WORKFLOW, FILEORDERSOURCE, JOBRESOURCE, NOTICEBOARD, LOCK
    - Releasable object types: INCLUDESCRIPT, SCHEDULE, WORKINGDAYSCALENDAR, NONWORKINGDAYSCALENDAR, JOBTEMPLATE, REPORT
  - with the --folder option to include all objects in the related folder to be returned. The --recursive switch can be used to process sub-folders recursively.
store-item
- Stores scheduling objects of JOC Cockpit's inventory to JOC Cockpit's Git repository.
- The following switches can be used to limit objects that should be stored:
  - The --no-draft switch excludes draft objects from being stored to JOC Cockpit's Git repository.
  - The --no-deployed switch excludes deployed objects from being stored to JOC Cockpit's Git repository.
  - The --no-released switch excludes released objects from being stored to JOC Cockpit's Git repository.
- Later commit and push commands will apply changes.
update-item
- Updates the JOC Cockpit inventory from scheduling objects available in JOC Cockpit's Git repository.
delete-item
- Deletes scheduling objects from JOC Cockpit's Git repository. The operation does not affect existence of objects in JOC Cockpit's inventory.
- Later commit and push commands will apply changes.
clone
- Clones a remote Git repository to a JOC Cockpit Git repository.
- The command is used with the --remote-url option to identify the remote Git repository. Frequently the syntax git@<git-server>:<owner>/<repository> is used, for example: git@github.com:sos-berlin/js7-demo-inventory-rollout-test
checkout
- A specific branch from the remote Git repository is checked out using the --branch or --tag options to identify the branch.
add
- Adds changes to JOC Cockpit's Git repository.
commit
- Commits changes to JOC Cockpit's Git repository.
- The command is used with the --folder option to specify the inventory folder that is mapped to the Git repository. The --message option is used to specify a message that typically becomes visible when displaying commits to a repository in a Git Server.
- The command returns the commit hash created by Git when committing changes.
push
- Pushes objects from JOC Cockpit's Git repository to the remote Git repository.
- The command is used with the --folder option to specify the inventory folder that is mapped to the Git repository.
pull
- Pulls objects from the remote Git repository to JOC Cockpit's Git repository. Objects in JOC Cockpit's Git repository will be removed, added or updated.
- The command is used with the --folder option to specify the inventory folder that is mapped to the Git repository.
get-credentials
- Reads Git credentials from the user's profile in JOC Cockpit.
- If credentials for more than one Git Server are available then they will be returned.
store-credentials
- Stores Git credentials to the user's profile in JOC Cockpit.
- The command is used with the --server option to specify the Git Server for which credentials will be stored.
- For authentication with Git one of the --user-password, --user-access-token or --user-private-key options must be used.
  - The location of a private key file must be specified from an absolute path that is readable for the JOC Cockpit service.
  - Users have to store the private key file to the related location.
delete-credentials
- Deletes Git credentials from the user's profile in JOC Cockpit.
- The command is used with the --server option to specify the Git Server for which credentials will be deleted.

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 for login to JOC Cockpit.
- Password input from the command line is considered insecure.
  - Consider use of the -p switch offering a secure option for interactive keyboard input.
  - Consider use of the encrypt command to encrypt a password: ./deploy-controller.sh encrypt --in=root --cert=encrypt.crt.
    - The encryption result will include the prefix enc: followed by the encrypted symmetric key, initialization vector and encrypted secret separated by space.
    - If an encrypted password is specified, then it will be decrypted using the Private Key file: ./deploy-controller.sh <command> --password="enc:BF8J8KP7TPlxy..." --key=encrypt.key.
--ca-cert
- Specifies the path to a file in PEM format 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 file in PEM format that holds the Client Certificate if HTTPS mutual authentication is used..
--client-key
- Specifies the path to a file in PEM format that holds the Client Private Key if HTTPS mutual authentication is used..
--timeout
- Specifies the maximum duration for requests to the JS7 REST Web Service. Default: 60 seconds.
--controller-id
- Specifies the identification of the Controller.
--folder
- When used with commands, specifies the JOC Cockpit's inventory folder to which the command is applied.
  - For use with the update-item, store-item and delete-item commands more than one folder can be specified separated by comma, for example: --folder=/TestRepo/Accounting,/TestRepo/Reporting
- The --recursive switch is used If sub-folders should be processed recursively.
--path
- When used with the store-item , update-item and delete-item commands, specifies the path of an object including folder, sub-folders and object name.
- Use of the --path option requires specification of the --type option to determine the object type.
- The option is used alternatively to specification of a folder using the --folder option.
--type
- When used with the store-item , update-item and delete-item commands and the --path option, specifies the type of object that should be processed:
  - Deployable object types: WORKFLOW, FILEORDERSOURCE, JOBRESOURCE, NOTICEBOARD, LOCK
  - Releasable object types: INCLUDESCRIPT, SCHEDULE, WORKINGDAYSCALENDAR, NONWORKINGDAYSCALENDAR, JOBTEMPLATE, REPORT
- Use of the option is required if the --path option is used.
--branch
- When used with the checkout command specifies the name of the Git repository branch to be checked out.
--tag
- When used with the checkout command specifies the tag that identifies the Git repository branch to be checked out. If more than one tag is used, they are separted by comma, for example: --tag=prod,v1.12
--message
- When used with the commit command, specifies the message that explains the purpose of the commit operation.
--server
- When used with the store-credentials and delete-credentials commands, specifies the hostname of the Git Server.
- Git credentials are stored on a per Git Server basis.
--user-account
- When used with the store-credentials command, specifies the account used for authentication with the Git Server.
--user-name
- When used with the store-credentials command, specifies the user name used for authentication with the Git Server.
--user-mail
- When used with the store-credentials command, specifies the e-mail address used for authentication with the Git Server.
--user-password
- When used with the store-credentials command, specifies the password used for authentication with the Git Server.
- Password input from the command line is considered insecure.
  - Consider use of the -u switch that asks for interactive keyboard input of the password.
  - The switch is used for secure interactive input as an alternative to use of the --user-password=<password> option.
- Only one of --user-password, --user-access-token or --user-private-key options can be used.
--user-access-token
- When used with the store-credentials command, specifies the access token used for authentication with the Git Server.
- Only one of --user-password, --user-access-token or --user-private-key options can be used.
--user-private-key
- When used with the store-credentials command, specifies the path to a private key file used for authentication with the Git Server.
  - The location of a private key file must be specified from an absolute path that is readable for the JOC Cockpit service.
  - Users have to store the private key file to the related location.
- Only one of --user-password, --user-access-token or --user-private-key options can be used.
--remote-url
- When used with the clone command, specifies the URL of the repository to be cloned.
- Frequently the syntax git@<git-server>:<owner>/<repository> is used, for example: git@github.com:sos-berlin/js7-demo-inventory-rollout-test
--audit-message
- Specifies a message that is made available to the Audit Log.
- Specification of Audit Log messages can be enforced on a per user basis and for a JS7 environment.
--audit-time-spent
- Specifies the time spent to perform an operation which is added to the Audit Log.
- The option can be specified if the --audit-message option is used.
--audit-link
- Specifies a link (URL) which is added to the Audit Log.
- The option can be specified if the --audit-message option is used.
--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: deploy-controller.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
- For example: deploy-controller.2022-03-19T20-50-45.log

Switches

-h | --help
- Displays usage.
-v | --verbose
- Displays verbose log output that includes requests and responses with the JS7 REST Web Service.
- When used twice as with -v -v then curl verbose output will be displayed.
-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>.
-l | --local
- Specifies a JOC Cockpit Git repository of type "local" to be used:
  - Repositories of type "local" hold object types that are specific for a scheduling environment and should not be deployed using Git and are stored to a separate repository.
    - Location: <jetty-base>/resources/joc/repositories/local
  - Repositories of type "rollout" hold object types that should be deployed using Git.
    - Location: <jetty-base>/resources/joc/repositories/rollout
  - Which object types make it for which repository type can be specified from settings, see JS7 - Inventory Git Integration.
- If the switch is not specified, then the repository type "rollout" is assumed.
-r | --recursive
- When used with the --folder option, specifies that sub-folders should be processed recursively.
-u | --user-password
- Asks the user for interactive keyboard input of the password used for authentication with a Git Server when using the store-credentials command.
- The switch is used for secure interactive input as an alternative to use of the --user-password=<password> option.
--no-draft
- Specifies that draft objects will be excluded from Git operations.
--no-deployed
- Specifies that deployed objects will be excluded from Git operations.
- This applies to deployable object types such as WORKFLOW, FILEORDERSOURCE, JOBRESOURCE, NOTICEBOARD, LOCK.
--no-released
- Specifies that released objects will be excluded from Git operations.
- This applies to releasable object types such as INCLUDESCRIPT, SCHEDULE, WORKINGDAYSCALENDAR, NONWORKINGDAYSCALENDAR, JOBTEMPLATE, REPORT.
--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: operation successful
1: argument errors
3: no objects found
4: JS7 REST Web Service is not reachable or reports errors

Examples

The following examples illustrate use cases for automated deployment to Git repositories.

Managing Git Credentials

Credentials for a Git Server can be managed from the JOC Cockpit GUI using JS7 - Profiles - Git Management.

Example for Managing Git Credentials

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# get credentials
./deploy-git.sh get-credentials    "${request_options[@]}"

# store credentials
./deploy-git.sh store-credentials  "${request_options[@]}" --server=github.com --user-account=community \
                                   --user-name="Community" --user-mail="community@sos-berlin.com" \
                                   --user-private-key=/var/sos-berlin.com/js7/joc/resources/joc/repositories/private/sos-community.rsa

# delete credentials
./deploy-git.sh delete-credentials "${request_options[@]}" --server=github.com

Cloning a Git Repository

A remote Git repository is cloned to a JOC Cockpit Git repository and is mapped to a JOC Cockpit inventory folder.

Example for Cloning a Git Repository

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# clone repository
./deploy-git.sh clone    "${request_options[@]}" --folder=/TestRepo --remote-url="git@github.com:sos-berlin/js7-demo-inventory-rollout-test"

# optionally checkout repository if a specific branch should be used
./deploy-git.sh checkout "${request_options[@]}" --folder=/TestRepo --branch=main

Managing Scheduling Objects in a Git Repository

Listing Scheduling Objects from a Git Repository

The operation will return the list of scheduling objects available in JOC Cockpit's Git repository.

Example for Listing Objects from a Git Repository

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# list items from JOC Cockpit rollout repository
./deploy-git.sh list-item    "${request_options[@]}" --folder=/TestRepo --recursive

# list items from JOC Cockpit local repository
./deploy-git.sh list-item    "${request_options[@]}" --folder=/TestRepo --recursive --local

Storing Scheduling Objects to a Git Repository

The operation will store scheduling objects from JOC Cockpit's inventory to JOC Cockpit's Git repository.

Examples for Storing Scheduling Objects to a Git Repository

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# store items to JOC Cockpit rollout repository: folder
./deploy-git.sh store-item  "${request_options[@]}" --folder=/TestRepo --recursive

# store items to JOC Cockpit rollout repository: object path and type of deployed object
./deploy-git.sh store-item  "${request_options[@]}" --path=/TestRepo/03_VariablesPassing/jdwVariablesAdHoc --type=WORKFLOW --no-draft

# store items to JOC Cockpit local repository: object path and type of draft object
./deploy-git.sh store-item  "${request_options[@]}" --path=/TestRepo/03_VariablesPassing/jdjVariablesJobResource --type=JOBRESOURCE --no-deployed --local

# store items to JOC Cockpit rollout repository: object path and type of deployed or draft object
./deploy-git.sh store-item  "${request_options[@]}" --path=/TestRepo/51_JobTemplates/51_JobTemplate --type=JOBTEMPLATE

# store items to JOC Cockpit rollout repository: folder limited to draft objects
./deploy-git.sh store-item  "${request_options[@]}" --folder=/TestRepo --recursive --no-released --no-deployed

# store items to JOC Cockpit rollout repository: folder limited to deployed objects
./deploy-git.sh store-item  "${request_options[@]}" --folder=/TestRepo --recursive --no-released --no-draft

# store items to JOC Cockpit rollout repository: folder limited to released objects
./deploy-git.sh store-item  "${request_options[@]}" --folder=/TestRepo --recursive --no-deployed --no-draft

Deleting Scheduling Objects from a Git Repository

The operation will delete objects from JOC Cockpit's Git repository.

Examples for Deleting Scheduling Objects from a Git Repository

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# delete items from JOC Cockpitrollout repository: folder
./deploy-git.sh delete-item "${request_options[@]}" --folder=/TestRepo/03_VariablesPassing

# delete items from JOC Cockpit rollout repository: object path and type
./deploy-git.sh delete-item "${request_options[@]}"  --path=/TestRepo/03_VariablesPassing/jdwVariablesAdHoc --type=WORKFLOW

# delete items from JOC Cockpit rollout repository: object path and type
./deploy-git.sh delete-item "${request_options[@]}"  --path=/TestRepo/51_JobTemplates/51_JobTemplate --type=JOBTEMPLATE

# delete items from JOC Cockpit local repository: object path and type
./deploy-git.sh delete-item "${request_options[@]}"  --path=/TestRepo/03_VariablesPassing/jdjVariablesJobResource --type=JOBRESOURCE --local

Updating the JOC Cockpit Inventory from a Git Repository

The operation will update JOC Cockpit's inventory from scheduling objects available in JOC Cockpit's Git repository.

Examples for Updating the JOC Cockpit Inventory from a Git Repository

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# update inventory items from JOC Cockpit rollout repository: folder
./deploy-git.sh update-item "${request_options[@]}" --folder=/TestRepo

# update inventory items from JOC Cockpit local repository: folder
./deploy-git.sh update-item "${request_options[@]}" --folder=/TestRepo --local

# update inventory items from JOC Cockpit rollout repository: path and object type
./deploy-git.sh update-item "${request_options[@]}" --path=/TestRepo/03_VariablesPassing/jdwVariablesAdHoc --type=WORKFLOW

Deploying Scheduling Objects from a Git Repository

The operation will update the JOC Cockpit's Git repository from inventory items and will push changes to the remote Git repository.

Example for Deploying Objects from a Git Repository

# common options for connection to JS7 REST API
request_options=(--url=http://localhost:4446 --user=root --password=root --controller-id=controller)

# store inventory items to JOC Cockpit rollout repository: folder
./deploy-git.sh store-item    "${request_options[@]}" --folder=/TestRepo --recursive

# add items to JOC Cockpit rollout repository
./deploy-git.sh add           "${request_options[@]}" --folder=/TestRepo

# commit changes to JOC Cockpit rollout repository and keep commit hash
hash=$(./deploy-git.sh commit "${request_options[@]}" --folder=/TestRepo --message="v.1.23.34")

# pull changes from remote repository to JOC Cockpit rollout repository
./deploy-git.sh pull          "${request_options[@]}" --folder=/TestRepo

# push changes from JOC Cockpit rollout repository to remote repository
./deploy-git.sh push          "${request_options[@]}" --folder=/TestRepo

Resources

API
- JS7 - REST Web Service API
- JS7 - PowerShell Module
Controller Status Operations
- JS7 - Unix Shell CLI for Controller Status Operations
Controller Deployment Operations
- JS7 - Unix Shell CLI for Controller Deployment
Workflow Deployment Operations
- JS7 - Unix Shell CLI for Workflow Deployment
Workflow Status Operations
- JS7 - Unix Shell CLI for Workflow Status Operations
Identity Service Deployment Operations
- JS7 - Unix Shell CLI for Identity Service Deployment
JOC Cockpit Status Operations
- JS7 - Unix Shell CLI for JOC Cockpit Status Operations

Space shortcuts

Page tree

Introduction

Git Deployment Script

Prerequisites

Download

Usage

Commands

Options

Switches

Exit Codes

Examples

Managing Git Credentials

Cloning a Git Repository

Managing Scheduling Objects in a Git Repository

Listing Scheduling Objects from a Git Repository

Storing Scheduling Objects to a Git Repository

Deleting Scheduling Objects from a Git Repository

Updating the JOC Cockpit Inventory from a Git Repository

Deploying Scheduling Objects from a Git Repository

Resources

Space shortcuts

Page tree

JS7 - Unix Shell CLI for Git Deployment

Introduction

Git Deployment Script

Prerequisites

Download

Usage

Commands

Options

Switches

Exit Codes

Examples

Managing Git Credentials

Cloning a Git Repository

Managing Scheduling Objects in a Git Repository

Listing Scheduling Objects from a Git Repository

Storing Scheduling Objects to a Git Repository

Deleting Scheduling Objects from a Git Repository

Updating the JOC Cockpit Inventory from a Git Repository

Deploying Scheduling Objects from a Git Repository

Resources