JOC Cockpit REST Web Service Interface

Scope

The JOC Cockpit comes with a REST Web Service interface for JSON. This interface is used for access to the job inventory and the job history as well as individual objects such as jobs, job chains and orders and provides current status information.

• The JOC Cockpit REST Web Service provides the API for the JOC Cockpit user interface.
  • The API might change along minor releases with the requirements of future JOC Cockpit development.
  • The JOC Cockpit REST Web Service comes in addition to the JobScheduler - REST Web Service that is considered as a replacement for the retired XML Interface.
• The REST Web Service is used by the JOC Cockpit for interaction with a JobScheduler Master:
  • Access to the REST Web Service is restricted by permissions, see Authentication and Authorization - Permissions for the JOC Cockpit Web Service

Usage

• The REST Web Service is called by using an HTTP client that sends JSON based requests and that receives JSON based responses.
• The following REST Web Service requests are supported:
  • URL joc/api/security/login
    • The first operation of a client should be 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 example api_user configuration for further information.
    • Use the joc/api/security/joc_cockpit_permissions URL to retrieve the permissions for the current user.
  • URL  joc/api/* 
    
    • Subsequent calls to URLs can retrieve the job inventory and current information about jobs and job chains.
    • The JOC Cockpit REST Web Service will return the respective JSON response.
  • URL joc/api/security/logout
    • The last operation of a client should be a call to this URL in order to logout from the web service.
• Requirements
  • REST Web Service requests should use HTTP POST or GET operations as indicated.
  • Should an idle timeout of 15 minutes between two web service requests be exceeded then the current session is invalidated and a login has to be performed.
• Example: Get status information about a job chain and job
  • Find attached example joc_cockpit_curl_status_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:

    
    

    Sample for use with curl to get status information on job chains and jobs Expand source

    #!/usr/bin/sh
    
    # -----------------------------------------
    # MODIFY FOR YOUR ENVIRONMENT
    
    # Protocol, host and port of JOC Cockpit
    JS_URL="https://localhost:4446"
    
    # Identification of JobScheduler instance
    JS_ID="apmacwin_4444"
    
    # Path and name of Job Chain
    JS_JOB_CHAIN="/product_demo/shell_chain"
    
    # Path and name of Job
    JS_JOB="/product_demo/shell_job"
    
    # Base64 encoded string "user:password" for JOC Cockpit authentication. The below string represents "root:root"
    JS_BASIC_AUTHENTICATION="`echo "root:root" | base64`"
    JS_BASIC_AUTHENTICATION="${JS_BASIC_AUTHENTICATION:0:${#JS_BASIC_AUTHENTICATION}-4}"
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Perform login
    echo ""
    echo "PERFORMING LOGIN"
    JS_JSON="`curl -k -s -S -X POST -i -m 15 -H "Authorization: Basic $JS_BASIC_AUTHENTICATION" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/security/login`"
    JS_ACCESS_TOKEN=$(echo $JS_JSON | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" )
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Get the status of a job chain
    echo ""
    echo "Get the status of a job chain"
    # Execute web service request
    JS_REST_BODY="{ \"jobschedulerId\": \"$JS_ID\", \"compact\": true, \"jobChain\": \"$JS_JOB_CHAIN\" }"
    JS_JSON="`curl -k -s -S -X POST -d "$JS_REST_BODY" -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS_URL/joc/api/job_chain`"
    echo $JS_JSON
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Get the status of a job
    echo ""
    echo "Get the status of a job"
    # Execute web service request
    JS_REST_BODY="{ \"jobschedulerId\": \"$JS_ID\", \"compact\": true, \"job\": \"$JS_JOB\" }"
    JS_JSON="`curl -k -s -S -X POST -d "$JS_REST_BODY" -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS_URL/joc/api/job`"
    echo $JS_JSON
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Perform logout
    echo ""
    echo "PERFORMING LOGOUT"
    curl -k -s -S -X POST -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/security/logout
    # -----------------------------------------
    echo ""
    

  • Explanations
    • Line 7: 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 10: The JobScheduler ID is specified during installation of the Master and identifies a Master standalone instance or a Master cluster.
    • Line 13, 16: Specify the full path and name to the job chain and job that you want to receive status information for
    • Line 19, 20: Default credentials after installation include the account "root" and password "root". The credentials might have been changed after setup of JOC Cockpit.
    • Lin 27: Consider to use Basic HTTP authentication
    • Line 28: The request to the /security/login web service returns an access token that is used with further requests.
    • Line 38, 39: Consider the JSON body created for the request and the URL used for status information about job chains.
    • Line 49, 50: Consider the JSON body created for the request and the URL used for status information about jobs.
    • Line 59: Always perform a logout and consider the session idle timeout.
• Example: Suspend an order
  • Find attached example joc_cockpit_curl_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:

    
    

    Sample for use with curl to suspend an order Expand source

    #!/usr/bin/sh
    
    # -----------------------------------------
    # MODIFY FOR YOUR ENVIRONMENT
    
    # Protocol, host and port of JOC Cockpit
    JS_URL="http://localhost:4446"
    
    # Identification of JobScheduler instance
    JS_ID="apmaccs_4444"
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Base64 encoded string "user:password" for JOC Cockpit authentication. The below string represents "root:root"
    # JS_BASIC_AUTHENTICATION="cm9vdDpyb290"
    
    # Alternatively base64 encode and strip the last 4 bytes
    JS_BASIC_AUTHENTICATION="`echo "root:root" | base64`"
    JS_BASIC_AUTHENTICATION="${JS_BASIC_AUTHENTICATION:0:${#JS_BASIC_AUTHENTICATION}-4}"
    # -----------------------------------------
    
    # -----------------------------------------
    # Perform login
    echo ""
    echo "PERFORMING LOGIN"
    JS_JSON="`curl -k -s -S -X POST -i -m 15 -H "Authorization: Basic $JS_BASIC_AUTHENTICATION" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/security/login`"
    JS_ACCESS_TOKEN=$(echo $JS_JSON | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" )
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Suspend a specific order identified by its ID from a given job chain specified by its full path
    echo ""
    echo "SUSPENDING AN ORDER"
    JS_REST_BODY="{ \"jobschedulerId\": \"$JS_ID\", \"orders\": [{ \"orderId\": \"order1\", \"jobChain\": \"/agent/job_chain1\" }] }"
    
    # Execute web service request
    curl -k -s -S -X POST -d "$JS_REST_BODY" -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/orders/suspend
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Perform logout
    echo ""
    echo "PERFORMING LOGOUT"
    curl -k -s -S -X POST -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/security/logout
    # -----------------------------------------
    echo ""

    
    

  • Explanations
    • Line 7: 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 10: The JobScheduler ID is specified during installation of the Master and identifies a Master standalone instance or a Master cluster.
    • Line 19, 20: Default credentials after installation include the account "root" and password "root". The credentials might have been changed after setup of JOC Cockpit.
    • Lin 27: Consider to use Basic HTTP authentication
    • Line 28: The request to the /security/login web service returns an access token that is used with further requests.
    • Line 36, 39: Suspending an order includes to specify with the request body the JobSchedulerID, the order id and the full path of the job chain.
    • Line 47: Always perform a logout and consider the session idle timeout.
• Example: List suspended orders

  • Find attached example suspended_orders.sh for use with curl
    
    

    Sample for use with curl to list suspended orders Expand source

    # ----------------------------------------
    # Protocol, host and port of JOC Cockpit
    JS_URL="http://localhost:5446"
    
    # Identification of JobScheduler instance
    JS_ID="testsuite"
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Base64 encoded string "user:password" for JOC Cockpit authentication. The below string represents "root:root"
    JS_BASIC_AUTHENTICATION="`echo "root:root" | base64`"
    JS_BASIC_AUTHENTICATION="${JS_BASIC_AUTHENTICATION:0:${#JS_BASIC_AUTHENTICATION}-4}"
    
    # -----------------------------------------
    # Perform login
    echo ""
    echo "PERFORMING LOGIN"
    JS_JSON="`curl -k -s -S -X POST -i -m 15 -H "Authorization: Basic $JS_BASIC_AUTHENTICATION" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/security/login`"
    JS_ACCESS_TOKEN=$(echo $JS_JSON | grep -Po '"accessToken":.*?[^\\]"' | awk -F ':' '{print $2}' | tr -d \" )
    # -----------------------------------------
    
    
    # -----------------------------------------
    # Get orders with status "suspended"
    echo ""
    echo "Get suspended orders"
    # Execute web service request
    JS_REST_BODY="{ \"jobschedulerId\": \"$JS_ID\", \"compact\": true, \"processingStates\": [\"SUSPENDED\"] }"
    JS_JSON="`curl -k -s -S -X POST -d "$JS_REST_BODY" -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/xml" $JS_URL/joc/api/orders`"
    echo $JS_JSON
    # -----------------------------------------
    
    
    # -----------------------------------------
    
    # -----------------------------------------
    # Perform logout
    echo ""
    echo "PERFORMING LOGOUT"
    curl -k -s -S -X POST -i -m 15 -H "X-Access-Token: $JS_ACCESS_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" $JS_URL/joc/api/security/logout
    # -----------------------------------------
    echo ""

    
    

  • Explanations
    • Line 29: The request body specifies the JobScheduler ID and the processing state "SUSPENDED", for details see API Documentation.

Specification

• The specification is available from JOC Cockpit REST Web Services Technical Documentation (RAML Specification).

References

• Authentication and Authorization: Permissions for the JOC Cockpit Web Service
• Specification JOC Cockpit REST Web Services Technical Documentation (RAML Specification)