Introduction

JOC Cockpit implements the JS7 - REST Web Service API to perform operations such as adding orders. In JS7 everything is REST, the JOC Cockpit GUI running in a browser performs REST requests, similarly the JS7 - Unix Shell Command Line Interface and the JS7 - PowerShell Module implement REST clients.

For use with the JS7 - JITL JS7RESTClientJob and JS7 - JITL RESTClientJob the JOC Cockpit offers a REST Editor to simplify creation of REST requests:

• The REST Editor assists users in creating a REST request that will be executed by the related job.
• The REST Editor offers to try out REST requests directly with the current JOC Cockpit instance.
• The REST Editor assists by making the documentation of related REST APIs accessible.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.0

REST Editor

Invoking the REST Editor

Users invoke the REST Editor from the Configuration view for a workflow and job like this:

• The Job Class must be: JITL
• The Class Name must be: com.sos.jitl.jobs.rest.JS7RESTClientJob
• In the upper part of the details panel the API Request button is offered.
  
  

Creating a REST Request

Hitting the API Request button for a job invokes the REST Editor:

• Users must specify the HTTP method and endpoint:
  • For most JS7 REST API requests the POST method is used. Available methods are indicated from the JS7 - REST Web Service API per endpoint.
  • The endpoint starts with a slash "/" and corresponds to the related REST API, for example /orders/add. For specifics use the documentation that matches the JS7 release in use.
• Users can select the Authorization tab and can specify the Authentication Method and Credentials if they intend to use the Send Request button to try out the REST request in the REST Editor.
  • The Credentials will not be used when running the job, they will be used only when trying out the REST request in the REST Editor using the Send Request button. The job will use credentials provided by JS7 - JITL Common Authentication.
  • A number of JS7 - Identity Services support Basic Authentication. This includes the JS7 - JOC Identity Service that is active by default.
  • The REST Editor will use the Credentials to create an Authorization Header with the base64 encoded value of <account>:<password> and will store the header in the Headers tab. Plain text Credentials specified with the Authorization tab will not be persisted.
    • Users should be aware of security implications: base64 is not about encryption, but about encoding: encoded Credentials can be decoded.
    • While it is fine to specify and to store Credentials when developing a job in a test environment, the same is a No-Go in a production environment.

• Users can remove Credentials by dropping the related Authorization Header in the Headers tab of the REST Editor or by removing related elements in the JSON document of the request job argument.
  
  

  
  

The next relevant tab includes Headers:

• Typically the Content-Type header is specified. For most REST APIs the value is application/json as a request body in this format is expected.

• The Authorization header is applied if users intend to use the Send Request button to try out the REST API request with the current JOC Cockpit instance.
  
  

For most REST requests it is required to specify the request body from the Body tab:

• The request body corresponds to the related REST API.
• User can reference variables in the body of a REST request:
  
  • Any variables assigned the workflow and job arguments, variables from JS7 - Job Resources and built-in variables can be used, see JS7 - Expressions for Variables. Such variables will be substituted at run-time by the job.
  • When using the Send Request button of the REST Editor to try out a request, then variables assigned the current workflow will be substituted, variables from other sources will not be substituted.
  • The syntax for referencing variables is: ${variable}
  • For example, a workflow variable ${workflow} is specified in an /orders/add request like this: "workflowPath": "${workflow}"

• A basic /orders/add request body looks like this:
  
  

If users specify Credentials from the Authorization tab, then the Send Request button can be used:

• The REST Editor performs the following actions:
  • execute the /authentication/login request
  • execute the request specified by the endpoint, Headers, Body and optionally query Parameters.
  • execute the /authentication/logout request
• The REST Editor reports success or failure of the related request.
• The details panel holds the response received for the request. For example, the response to an /orders/add request includes an array of Order IDs that have been added.

Specifying Return Variables

Users can pick specific values from the response to make them available from Return Variables to subsequent jobs and instructions in the workflow.

• Double-clicking the related key in the response will invoke  a popup windows in which users can specify the name of the Return Variable that will carry the value.
• When the user applies the Submit button in the REST Editor, then a return_variable argument will be added to the job arguments. The value of the argument will include the variable name and the query to extract the value from the JSON response. Example:
  • Double-clicking the orderIds element in the response panel invokes a popup window specifying the name and path of the Return Variable.
  • The path is specified as .orderIds, with the initial dot indicating the top-level position of the element in the response. The user is expected to type the name of the Return Variable.

When hitting the Variable List button in the right bottom corner of the REST Editor, users can add, update and delete entries from the list of Return Variables .

Resulting Job Arguments

When submitting the configuration, then two job arguments, request and return_variable, will be added to the job. The Return Variables will be created when running the job and can be used in subsequent jobs and instructions.

• Other than using the REST Editor, users can change argument values directly.
• Invoking the Value Editor for the request job argument offers its value for editing like this:
  
  

Invoking the Value Editor for the return_variable job argument offers its value for editing like this:

• The order_ids variable holds the .orderIds value which returns an array of Order IDs. Returning an array can be useful in case that more than one order is added by the job.
• The order_id variable holds the .orderIds[0] value which returns a string carrying the Order ID available from the first element of the array of Order IDs in the response.
  
  

Managing Return Variables

Return Variables can be specified using the REST Editor to pick elements from the JSON response to a request.

• Users a free to specify names of Return Variables.
• The jq query language is available to extract values from a response and to assign them to Return Variables.

Find more explanations about use of from JS7 - JITL jq Interface.

Resources

• JS7 - JITL JS7RESTClientJob
• JS7 - JITL Common Authentication