JS7 JobScheduler

Space shortcuts

Page tree

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 16 Next »

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.
  • In addition, a PowerShell module is available for simplified access to the REST Web Service, see JS7 - PowerShell Module.

Design

  • The REST Web Service implements a stateless API.
    • Except for the fact that a session is started by logging into the REST Web Service and is terminated either by logging out or by expiration any operations performed with the REST Web Service cannot rely on the previous state of an object.
    • For example, retrieving an order at a given time does not prevent this order from transitioning to a subsequent state before the next call to the API is executed.
  • The REST Web Service is asynchronous for most parts.
    • Any operations that affect a Controller or Agent are handled asynchronously. In fact such operations are managed by the JOC Cockpit Proxy Service that forwards them to a Controller, see JS7 - Implementation Architecture.
      • The result of an operation is not returned with the response to the API call but will become available later on. In a situation when JOC Cockpit is not connected to a Controller or if a Controller is not connected to an Agent, e.g. due to network issues, still API calls will work. Such calls are handled by the Proxy Service that will forward them when the Controller becomes available.
      • For example, consider an API call to cancel an existing order. The response to this call will return acceptance/denial of the request. The operation is forwarded to a Controller and to an Agent respectively, however, the result will become available only after acknowledgement by the Agent and the respective response from the Controller.
    • API calls for asynchronous operations pending with the JOC Cockpit Proxy Service will be lost if the JOC Cockpit is restarted. There is no need to restart JOC Cockpit after a connection loss to a Controller as it will reconnect automatically.
    • A few API calls are handled synchronously, mainly when it comes to operations on the inventory. For example, API calls to store objects with the inventory will immediately return results. However, API calls to remove objects from the inventory such as a workflow are handled asynchronously as this operation requires interaction with a Controller to remove the workflow from its journal and from the journals of respective Agents. REST Clients therefore should not rely on any operation to return synchronous results.
  • The REST Web Service is designed for cluster operation.
    • If a Controller cluster is operated then the JOC Cockpit Proxy Service will automatically connect to the active Controller instance. In case of fail-over or switch-over the Proxy Service will connect to the cluster member instance that is the resulting active instance.
    • Any changes to objects caused by API calls are synchronized between the active Controller and the passive Controller. In case of later reconnection the Controller instances will reconcile to have the information about changed object states synchronized.
    • This behavior does not affect a REST Client that makes use of the API, therefore REST clients will continue to work even in case of cluster fail-over or switch-over operations.

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 e.g. retrieve the inventory and current information about workflows and orders.
      • Find the respective URLs from the Technical Documentation of the REST Web Service
      • 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 REST 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.

Examples

  • 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 
        #!/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.
  • 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:
      • Sample for use with curl to suspend an order 
        #!/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.
  • 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.



  • No labels