JobScheduler - REST Web Service

Scope

The JobScheduler comes with a powerful REST Web Service interface for access by external applications. This interface is used for tasks such as adding orders, adding events and retrieving job and order status information.

• The JobScheduler REST Web Service is a replacement for the retired XML Interface.
• The REST Web Service is used by the JOC Cockpit and by external applications for interaction with a JobScheduler Master:
  • The REST Web Service offers access to objects such as jobs, job chains and orders and their respective operations, e.g. to add an order to a job chain.
  • Access to the REST Web Service is restricted by permissions, see Authentication and Authorization - Permissions for the JobScheduler REST Web Service

Usage

• The REST Web Service is called by using an HTTP client.
• 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/jobscheduler/command 
    • Subsequent XML Commands can be sent by use of this URL. 
    • The XML command is added to the body of the web service request.
    • The JobScheduler REST Web Service will return the respective XML 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
  • All REST Web Service requests should use an HTTP POST operation.
  • 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.

Specification

The documentation is available from http://test.sos-berlin.com/JobScheduler/raml-doc/JobScheduler-REST-web-services/ and includes the RAML specification.

XML Commands

Find the list of XML Commands from the Reference Documentation.

The following table states the available XML commands for the JobScheduler REST Web Service, deprecated XML commands show a red background.

Examples

Example for authentication request

As the REST Web Service requires authentication therefore the first request could look like this:

POST /joc/api/security/login HTTP/1.1
Host: localhost:4446
Authorization: Basic YXA6YXA=
Content-Type: application/json
Cache-Control: no-cache

Explanations

• The JobScheduler REST Web Service (and the JOC Cockpit) are operated on the localhost with port 4446.
• The URL in use is http://localhost:4446/joc/api/security/login
• The Authorization header is used for HTTP Authentication, i.e. the constant value Basic and the base64 encoded user name and password separated by a colon.
• Consider use of the Content-Type header application/json.
• No body is required for this request.

The REST Web Service response is provided in JSON format and could look like this:

{
  "enableTouch": true,
  "sessionTimeout": 1500000,
  "user": "ap",
  "accessToken": "c96a8563-5910-4d76-bc2a-4bc969a88d05",
  "hasRole": false,
  "isAuthenticated": true,
  "isPermitted": false
}

Explanations

• The sessionTimeout property provides the idle timeout in milliseconds, i.e. the session will be expire should no requests be performed during the duration specified by the timeout.
• The accessToken is a token provided by the Web Service that has to be used for authentication of subsequent requests.

Example for retrieval of status information

After successful authentication with the REST Web Service subsequently XML Commands can be sent to JobScheduler:

POST /joc/api/jobscheduler/command HTTP/1.1
Host: localhost:4446
access_token: c96a8563-5910-4d76-bc2a-4bc969a88d05
Content-Type: application/xml
Cache-Control: no-cache
<jobscheduler_commands jobschedulerId='scheduler111'><show_state/></jobscheduler_commands>

Explanations

• The JobScheduler REST Web Service (and the JOC Cockpit) are operated on the localhost with port 4446.
• The URL in use is http://localhost:4446/joc/api/jobscheduler/command
• The value for the access_token has been retrieved from a previous authentication request.
• Consider use of the Content-Type header application/xml.
• The body contains the effective XML commands wrapped in a <jobscheduler_command jobschedulerId="..."/> element where jobschedulerId is the JobScheduler ID of the respective JobScheduler Master.

Example for adding an order

Adding a temporary ad hoc order to JobScheduler could look like this:

POST /joc/api/jobscheduler/command HTTP/1.1
Host: localhost:4446
access_token: ce31fb8f-9f5a-4e3e-805d-72c71d0547ce
Content-Type: application/xml
Cache-Control: no-cache
Postman-Token: 88bd687a-586d-fd93-d203-bcd7e71a6a85
<jobscheduler_commands jobschedulerId='scheduler111'><add_order job_chain="/some_folder/some_chain"><params><param name="first" value="1st"/><params name="second" value="2nd"/></params></add_order></jobscheduler_commands>

Explanations

• The JobScheduler REST Web Service (and the JOC Cockpit) are operated on the localhost with port 4446.
• The URL in use is http://localhost:4446/joc/api/jobscheduler/command
• The value for the access_token has been retrieved from a previous authentication request.
• Consider use of the Content-Type header application/xml.
• The body contains the effective XML commands wrapped in a <jobscheduler_commands jobschedulerId="..."/> element where jobschedulerId is the JobScheduler ID of the respective JobScheduler Master. The effective XML Command <add_order/> is used to to add a temporary order to a job chain and optionally to add parameters to the order.

References

Change Management References

Documentation

• Authentication and Authorization
  • Authentication and Authorization - Permissions for the JobScheduler REST Web Service
• JobScheduler Reference Documentation:
  • XML commands
• JobScheduler REST Web Services
  • REST Web Services Technical Documentation (RAML Specification)