Page History
...
- Any operations that can be performed on orders, workflows, jobs and related objects such as cancelling, suspending and resuming orders are performed by the JS7 - REST Web Service API.
- Consider that any operation offered by the JOC Cockpit GUI makes use of the REST Web Service API.
- Find the Technical Documentation of the REST Web Service API.
- In addition, a PowerShell module is available for simplified access to the REST Web Service API, see JS7 - PowerShell Module.
- The REST Web Service API can be accessed from Shell utilities such as curl.
Usage
- The REST Web Service API is called by using an HTTP client that sends JSON based requests and that receives JSON based responses.
- The following REST Web Service API requests are supportedavailable:
- URL
joc/api/authentication/login
- The first operation of a client should be is call to this URL in order to authenticate and to retrieve an access token.
- A valid account and password have to be provided by the client for HTTP authentication. The account and permissions for the command(s) to be executed are configured with the
shiro.ini
configuration file. See the Authentication and Authorization - Configuration article and the exampleapi_user
configuration for further information.Use thejoc/api/authentication/joc_cockpit_permissions
URL to retrieve the permissions for the current userFor HTTPS connections in addition or alternatively JS7 - Certificate based Authentication can apply, for details see JS7 - Identity and Access Management. - Permissions apply as explained by JS7 - Management of User Accounts, Roles and Permissions.
- URL
joc/api/*
- Subsequent calls to URLs can e.g. for example retrieve the inventory and current information about workflows and ordersof workflow.
- Find the respective URLs from the Technical Documentation of the REST Web Service API
- The JS7 REST Web Service API will return returns the respective JSON response indicated with the docs.
- URL
joc/api/authentication/logout
- The last operation of a client should be is a call to this URL in order to logout from the REST Web Service API.
- URL
- Requirements
- REST Web Service API requests should use HTTP POST or GET operations as indicated.
- Should an the idle timeout of 15 minutes between two web service requests be exceeded then the current session is invalidated and exceed the JOC Cockpit session timeout then a login has to be performed. The timeout value can be adjusted with
shiro.ini
.
...
- , see JS7 - Settings.
Examples for Curl
- Example: Get the list of orders scheduled until a given date
- Find attached example order_list_sample.sh for use with curl. We do not consider curl to be perfectly prepared to handle web service requests, however, it shows the building blocks:
Code Block language bash title Example for use with curl to get list of orders scheduled until a given date linenumbers true collapse true #!/bin/sh # ---------------------------------------- # Protocol, host and port of JOC Cockpit JS7_URL="http://localhost:7446" # Identification of JS7 instance JS7_CONTROLLER_ID="testsuite" # Date up to that scheduled orders are returned JS7_DATETO="+1d" # Base64 encoded string "user:password" for authentication. The below string represents "root:root" JS7_BASIC_AUTHENTICATION="`echo "root:root" | base64`" JS7_BASIC_AUTHENTICATION="${JS7_BASIC_AUTHENTICATION:0:${#JS7_BASIC_AUTHENTICATION}-4}" # ----------------------------------------- # ----------------------------------------- # Perform login echo "" echo "PERFORMING LOGIN" JS7_JSON="`curl -k -s -S -X POST -i -m 15 -H "Authorization: Basic $JS7_BASIC_AUTHENTICATION" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/authentication/login`" JS7_ACCESS_TOKEN=$(echo $JS7_JSON | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" ) # ----------------------------------------- # ----------------------------------------- # Get the list of orders for a date range echo "" echo "Get the list of orders for date range: $JS7_DATETO" # Execute web service request JS7_REST_BODY="{ \"controllerId\": \"$JS7_CONTROLLER_ID\", \"compact\": true, \"dateTo\": \"$JS7_DATETO\" }" JS7_JSON="`curl -k -s -S -X POST -d "$JS7_REST_BODY" -i -m 15 -H "X-Access-Token: $JS7_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS7_URL/joc/api/orders`" echo $JS7_JSON # ----------------------------------------- # ----------------------------------------- # Perform logout echo "" echo "PERFORMING LOGOUT" curl -k -s -S -X POST -i -m 15 -H "X-Access-Token: $JS7_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/authentication/logout # ----------------------------------------- echo ""
Explanations
- Line 4: Depending on your JOC Cockpit installation the protocol will be http or https. The default port is 4446 but might have been modified during setup.
- Line 7: The Controller ID is specified during installation of the Controller and identifies a Controller standalone instance or a Controller cluster.
- Line 10: Specify the relative date up to that you want the list of scheduled orders to be returned.
- Line 13, 14: Default credentials after installation include the account "root" and password "root". The credentials might have been changed after setup of JOC Cockpit.
- Line 22: Consider to use Basic HTTP authentication
- Line 23: The request to the /authentication/login web service returns an access token that is used with further requests.
- Line 32, 33: Consider the JSON body created for the request and the URL including the path
/joc/api/orders
used to return order information. - Line 42: Always perform a logout and consider the session idle timeout.
- Find attached example order_list_sample.sh for use with curl. We do not consider curl to be perfectly prepared to handle web service requests, however, it shows the building blocks:
- Example: Suspend an order
- Find attached example order_suspend_sample.sh for use with curl. We do not consider curl to be perfectly prepared to handle web service requests, however, it shows the building blocks:
Code Block language bash title Example for use with curl to suspend an order linenumbers truecollapse true #!/bin/sh # ---------------------------------------- # Protocol, host and port of JOC Cockpit JS7_URL="http://localhost:7446" # Identification of JS7 instance JS7_CONTROLLER_ID="testsuite" # ID of order that should be suspended JS7_ORDER_ID="#2021-03-20#T6232717382-root" # Base64 encoded string "user:password" for authentication. The below string represents "root:root" JS7_BASIC_AUTHENTICATION="`echo "root:root" | base64`" JS7_BASIC_AUTHENTICATION="${JS7_BASIC_AUTHENTICATION:0:${#JS7_BASIC_AUTHENTICATION}-4}" # ----------------------------------------- # ----------------------------------------- # Perform login echo "" echo "PERFORMING LOGIN" JS7_JSON="`curl -k -s -S -X POST -i -m 15 -H "Authorization: Basic $JS7_BASIC_AUTHENTICATION" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/authentication/login`" JS7_ACCESS_TOKEN=$(echo $JS7_JSON | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" ) # ----------------------------------------- # ----------------------------------------- # Suspend a specific order identified by its ID echo "" echo "SUSPENDING ORDER WITH ID: $JS7_ORDER_ID" JS7_REST_BODY="{ \"controllerId\": \"$JS7_CONTROLLER_ID\", \"orderIds\": [ \"$JS7_ORDER_ID\" ] }" echo "Request Body: $JS7_REST_BODY" # Execute web service request curl -k -s -S -X POST -d "$JS7_REST_BODY" -i -m 15 -H "X-Access-Token: $JS7_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/orders/suspend echo "" echo "" echo "... sleep 3 seconds to check results" sleep 3 # ----------------------------------------- # ----------------------------------------- # Get order state information echo "" echo "GETTING STATE INFORMATION FOR ORDER WITH ID: $JS7_ORDER_ID" # Execute web service request JS7_REST_BODY="{ \"controllerId\": \"$JS7_CONTROLLER_ID\", \"compact\": true, \"orderIds\": [ \"$JS7_ORDER_ID\" ] }" JS7_JSON="`curl -k -s -S -X POST -d "$JS7_REST_BODY" -i -m 15 -H "X-Access-Token: $JS7_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS7_URL/joc/api/orders`" echo "Request Body: $JS7_REST_BODY" echo $JS7_JSON # ----------------------------------------- # ----------------------------------------- # Perform logout echo "" echo "PERFORMING LOGOUT" curl -k -s -S -X POST -i -m 15 -H "X-Access-Token: $JS7_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/authentication/logout # ----------------------------------------- echo ""
- Explanations
- Line 31: Suspending an order includes to specify the Controller ID and an array of order IDs..
- Line 38: The operation to suspend an order works asynchronously as the request is forwarded to the Controller and from the Controller to the Agent that holds the order. More elaborate solutions to wait for completion of an suspend operation than just to wait a few seconds include to repeatedly check the order state.
- Line 47: The request to retrieve the order state information is sent to the
/joc/api/orders
URL. - Line 58: Always perform a logout and consider the session idle timeout.
- Find attached example order_suspend_sample.sh for use with curl. We do not consider curl to be perfectly prepared to handle web service requests, however, it shows the building blocks:
- Example: Run test cases for a number of orders
- Find attached example invoke_testrun.sh for use with curl. We do not consider curl to be perfectly prepared to handle web service requests, however, it shows the building blocks.
- The script can be parameterized to run a number of orders for a given set of workflows.
Code Block language bash title Example for use with curl to run a number of orders for a given set of workflows collapselinenumbers true #!/bin/bash # ---------------------------------------- # JS7 Test Test Case Invocation # ---------------------------------------- # Examples # ./invoke_testrun.sh --url=http://joc-2-0-primary:7446 --id=testsuite --time-zone=Europe/Berlin --count=1 --workflows=/TestRuns/Test0000000070/tcpForkBalanced_001,/TestRuns/Test0000000070/tcpForkNestedLevel1_001 # ./invoke_testrun.sh --url=https://joc-2-0-primary:7443 --cacert=./certs/root-ca.crt --account=root --password=root --id=testsuite --time-zone=Europe/Berlin --workflows=/TestRuns/Test0000000070/tcpForkBalanced_001,/TestRuns/Test0000000070/tcpForkNestedLevel1_001 --batch-size=10 --count=1 # Protocol, host and port of JOC Cockpit JS7_URL="http://localhost:4446" # CA certificate for TLS/SSL connection JS7_CACERT="" # Account and password if no client authentication certificate is used JS7_ACCOUNT="root" JS7_PASSWORD="root" # Identification of JS7 Controller JS7_CONTROLLER_ID="" # Number of test runs, number of orders per batch in a test run, test case directory and workflow paths JS7_TEST_COUNT=1 JS7_TEST_BATCH_SIZE=100 JS7_TEST_CASE_WORKFLOWS=() JS7_TEST_CASE_SCHEDULED_FOR="now" JS7_TEST_CASE_TIME_ZONE="Etc/UTC" JS7_VERBOSE=0 # ---------------------------------------- for option in "$@" do case "$option" in -v) JS7_VERBOSE=1 ;; --url=*) JS7_URL=`echo "$option" | sed 's/--url=//'` ;; --cacert=*) JS7_CACERT=`echo "$option" | sed 's/--cacert=//'` ;; --account=*) JS7_ACCOUNT=`echo "$option" | sed 's/--account=//'` ;; --password=*) JS7_PASSWORD=`echo "$option" | sed 's/--password=//'` ;; --id=*) JS7_CONTROLLER_ID=`echo "$option" | sed 's/--id=//'` ;; --count=*) JS7_TEST_COUNT=`echo "$option" | sed 's/--count=//'` ;; --batch-size=*) JS7_TEST_BATCH_SIZE=`echo "$option" | sed 's/--batch-size=//'` ;; --workflows=*) JS7_TEST_CASE_WORKFLOWS=(`echo "$option" | sed 's/--workflows=//' | sed -r 's/[,]+/ /g'`) ;; --scheduled-for=*) JS7_TEST_CASE_SCHEDULED_FOR=`echo "$option" | sed 's/--scheduled-for=//'` ;; --time-zone=*) JS7_TEST_CASE_TIME_ZONE=`echo "$option" | sed 's/--time-zone=//'` ;; *) echo "unknown argument: $option" exit 1 ;; esac done # ----------------------------------------- JS7_Login() { echo -e "\n" echo "PERFORMING LOGIN" # Base64 encoded string "user:password" for authentication. The below string represents "root:root" js7_basic_authentication="`echo "$JS7_ACCOUNT:$JS7_PASSWORD" | base64`" js7_basic_authentication="${js7_basic_authentication:0:${#js7_basic_authentication}-4}" js7_curl_options=(-k -s -S -X POST -i -m 15) if [ "$JS7_CACERT" != "" ] then js7_curl_options+=(--cacert $JS7_CACERT) fi if [ $JS7_VERBOSE -ne 0 ] then echo "curl ${js7_curl_options[@]} -H \"Authorization: Basic $js7_basic_authentication\" -H \"Accept: application/json\" -H \"Content-Type: application/json\" $JS7_URL/joc/api/authentication/login" fi js7_json="`curl ${js7_curl_options[@]} -H "Authorization: Basic $js7_basic_authentication" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/authentication/login`" rc=$? if [ $rc -eq 0 ] then js7_access_token=$(echo $js7_json | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" ) if [ $JS7_VERBOSE -ne 0 ] then echo -e "Response:\n$js7_json" fi else echo "ERROR OCCURRED: $rc" echo $js7_json exit $rc fi js7_access_token=$(echo $js7_json | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" ) } # ----------------------------------------- JS7_Logout() { rc=$? echo -e "\n" if [ "$js7_access_token" != "" ] then echo "PERFORMING LOGOUT" js7_curl_options=(-k -s -S -X POST -i -m 15) if [ "$JS7_CACERT" != "" ] then js7_curl_otions+=(--cacert $JS7_CACERT) fi js7_json="`curl ${js7_curl_options[@]} -H "X-Access-Token: $js7_access_token" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/authentication/logout`" exit_code=$? if [ $exit_code -eq 0 ] then js7_access_token="" if [ $JS7_VERBOSE -ne 0 ] then echo -e "Response:\n$js7_json" fi else echo "ERROR OCCURRED: $exit_code" echo $js7_json fi echo -e "\n" fi exit $rc } # ----------------------------------------- JS7_AddOrder() { echo -e "\n" js7_order_count=0 for i in $(seq 1 $JS7_TEST_COUNT) do for workflow in ${JS7_TEST_CASE_WORKFLOWS[@]} do echo "ADDING ORDERS TO WORKFLOW: count=$i batch-size=$JS7_TEST_BATCH_SIZE workflow=$workflow" js7_rest_body="{ \"controllerId\": \"$JS7_CONTROLLER_ID\", \"orders\": [ " for j in $(seq 1 $JS7_TEST_BATCH_SIZE) do js7_order_count=$((js7_order_count+1)) js7_rest_body="$js7_rest_body { \"workflowPath\":\"$workflow\", \"orderName\":\"$RANDOM\", \"scheduledFor\":\"$JS7_TEST_CASE_SCHEDULED_FOR\", \"timeZone\":\"$JS7_TEST_CASE_TIME_ZONE\" } " if [ $j -lt $JS7_TEST_BATCH_SIZE ] then js7_rest_body="$js7_rest_body," fi done js7_rest_body="$js7_rest_body ] }" if [ $JS7_VERBOSE -ne 0 ] then echo "Request Body:\n$js7_rest_body" fi # Execute web service request js7_curl_options=(-k -s -S -X POST -i -m 15) if [ "$JS7_CACERT" != "" ] then js7_curl_options+=(--cacert $JS7_CACERT) fi js7_json="`curl ${js7_curl_options[@]} -d "$js7_rest_body" -H "X-Access-Token: $js7_access_token" -H "Accept: application/json" -H "Content-Type: application/json" $JS7_URL/joc/api/orders/add`" rc=$? if [ $rc -eq 0 ] then if [ $JS7_VERBOSE -ne 0 ] then echo -e "Response:\n$js7_json" fi else echo "ERROR OCCURRED: exit code $rc" echo -e "Response:\n$js7_json" exit $rc fi echo -e "orders added: $js7_order_count" done done } # ----------------------------------------- trap 'JS7_Logout EXIT' EXIT trap 'JS7_Logout SIGTERM' SIGTERM trap 'JS7_Logout SIGINT' SIGINT JS7_Login JS7_AddOrder JS7_Logout # -----------------------------------------
...
Overview
Content Tools