Page History
...
Introduction
- 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.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.
- 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 REST Web Service API can also be accessed from Shell utilities such as curl. Find the JS7 - Unix Shell Command Line Interface that implements most frequently used operations on Controllers and Agents, Workflows, jobs and orders.
Usage
- The REST Web Service API is called by using a HTTP client that sends JSON based requests and that receives JSON based responses.
- The following REST Web Service API requests are available:
- URL
joc/api/authentication/login
- The first operation a client carries out is a 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. For HTTPS connections in addition or alternatively JS7 - Certificate based Authentication can apply - for details see the JS7 - Identity and Access Management article.
- Permissions apply as explained in the JS7 - Management of User Accounts, Roles and Permissions article.
- URL
joc/api/*
- Subsequent calls to URLs can, for example, retrieve the inventory of workflow.
- The relevant URLs can be found in the Technical Documentation of the REST Web Service API
- The JS7 REST Web Service API returns the relevant JSON response as indicated in the docs.
- URL
joc/api/authentication/logout
- The last operation a client carries out 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 the idle timeout between two web service requests exceed the JOC Cockpit session timeout then a login has to be performed, see the JS7 - Settings article for more information.
Examples
...
using Curl
- Example: Get the list of orders scheduled until a given date.
- The attached example order_list_sample.sh is for use with curl. We do not consider curl to be perfect for handling 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 JS7JS_URL="http://localhost:7446" # Identification of JS7 instance JS7JS_CONTROLLER_ID="testsuitecontroller" # Date up to that scheduled orders are returned JS7JS_DATE_DATETOTO="+1d" # Base64Authentication 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}" (default account) JS_USER=root JS_PASSWORD=root # ----------------------------------------- # ----------------------------------------- # Perform login echo "" echo "PERFORMING LOGIN" JS7JS_JSON="`curl$(curl -k -L -s -S -X POST -i -m 15 --Huser "Authorization: Basic $JS7_BASIC_AUTHENTICATION$JS_USER:$JS_PASSWORD" -H "Accept: application/json" -H "Content-Type: application/json" $JS7$JS_URL/joc/api/authentication/login`"login) JS7JS_ACCESS_TOKEN=$(echo $JS7"$JS_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$JS_DATE_DATETOTO" # Execute web service request JS7JS_REST_BODY="{ \"controllerId\": \"$JS7$JS_CONTROLLER_ID\", \"compact\": true, \"dateTo\": \"$JS7$JS_DATE_DATETOTO\" }" JS7JS_JSON="`curl$(curl -k -L -s -S -X POST -m 15 -d "$JS7$JS_REST_BODY" -i -m 15 -H "X-Access-Token: $JS7$JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS7$JS_URL/joc/api/orders`"orders) echo $JS7"$JS_JSON" # ----------------------------------------- # ----------------------------------------- # Perform logout echo "" echo "PERFORMING LOGOUT" curl -k -L -s -S -X POST -i -m 15 -H "X-Access-Token: $JS7$JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS7$JS_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 which 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 the JOC Cockpit.
- Line 22: Note the use of Basic HTTP authentication
- Line 23: The request to the /authentication/login web service returns an access token which is used with further requests.
- Line 32, 33: Note 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.
- The attached example order_list_sample.sh is for use with curl. We do not consider curl to be perfect for handling web service requests. However, it shows the building blocks:
...
- Example: Run test cases for a number of orders.
- The attached example invoke_testrun.sh is 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 linenumbers true collapse 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 # -----------------------------------------
- Find a more elaborate example from the JS7 - How to update a Job Resource using Unix Shell articleUnix Shell Command Line Interface for a collection of frequently used operations.
Overview
Content Tools