Purpose

• 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.
  • Consider that any operation offered by the JOC Cockpit GUI makes use of the REST Web Service.
  • Find the Technical Documentation of the REST Web Service.
• In addition, a PowerShell module is available for simplified access to the REST Web Service, see JS7 - PowerShell Module.

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/authentication/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/authentication/joc_cockpit_permissions URL to retrieve the permissions for the current user.
  • URL  joc/api/* 
    
    • Subsequent calls to URLs can retrieve the inventory and current information about workflows and jobs.
    • The JS7 REST Web Service will return the respective JSON response.
  • URL joc/api/authentication/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. The timeout value can be adjusted with shiro.ini.
• 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:

    
    

    • Sample for use with curl to get list of orders scheduled until a given date Expand source

      #!/usr/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 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 Controller ID is specified during installation of the Controller and identifies a Controler standalone instance or a Controller cluster.
      • Line 13, 16: Specify the relative date up to that you want the list of scheduled orders to be returned.
      • 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 /authentication/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 59: Always perform a logout and consider the session idle timeout.
  • xx
  • 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:

      
      

  • xx
  • x
  • x