Introduction

The JITL JS7RESTClientJob job template can be used to create jobs that execute REST requests to JOC Cockpit, see JS7 - REST Web Service API.

• For the available REST API see https://www.sos-berlin.com/JOC/latest/raml-doc/JOC-API/index.html
• The JOC Cockpit GUI supports creating requests for a number of relevant REST APIs, see JS7 - JITL REST Editor.

Authentication

• The job template authenticates with the JS7 - REST Web Service API by use of user account/password, by use of certificates etc., for details see JS7 - Authentication.
• For details about configuration items see JS7 - JITL Common Authentication.

Delimitation

• Users who wish to execute REST API requests to 3rd-party web services, can use the JS7 - JITL RESTClientJob.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.0

Usage

When defining the job either:

• invoke the Job Wizard that is available from the job properties tab in the Configuration view of JOC Cockpit and select the JITL JS7RESTClientJob from the Job Wizard.

or

• specify the JITL job class and com.sos.jitl.jobs.rest.JS7RESTClientJob Java class name and add related arguments..

Starting from the Job Wizard

In JOC Cockpit's Configuration->Inventory view users can invoke the Job Wizard and can paramterize thier job

• Add a workflow or use an existing workflow.
• Add an empty job from the instruction panel.
• Specify a name and a label for the job.
• Select an Agent.

In a next step invoke the Job Wizard that you find in the upper right corner of the job property editor. The Job Wizard brings up the following popup window:

Explanation:

• From the list of available Job Templates select the JS7RESTAPIClientJob.

The job does not require arguments by default. However, hitting the Next button will make the Job Wizard display available arguments:

Explanation:

• Required Arguments
  • request:  Specifies the REST request in JSON format. The argument is preferably managed from the JS7 - JITL REST Editor.
• Optional Arguments
  • return_variable:  Optionally the values of the response to a REST request can be mapped to variables that are dynamically created and that are available to subsequent jobs and instructions in a workflow. This argument is preferably managed from the JS7 REST Editor.
  • All other optional arguments can be used for specifying authentication details see JS7 - JITL Common Authentication.
• Note that the the checkbox provided with each argument has to be selected to add the argument to your instance of the JS7RESTClientJob.

When hitting the Submit button, the wizard adds the selected arguments to the job.

The job arguments can be specified:

• from individual variables as configured using the job wizard,
• by using JS7 - Job Resources.

Starting from the Example

Importing the Example

Users who wish to start from an example find the following archive file for import into the JOC Cockpit inventory:

• Download: JS7RESTClient.zip
• For import see JS7 - Inventory Export and Import.

When importing the archive file, then the JS7RESTClient folder will be created in the JOC Cockpit inventory that should look like this:

• The following objects are included:
  • Workflow: Example-AddOrder implements the JS7RESTClientJob to add orders to the Example-AddOrder-Workflow.
  • Workflow: Example-AddOrder-Workflow is a simple workflow that sleeps for a few seconds.
  • Job Resource: Example-AuthenticationSettings holds connection settings and authentication credentials to access the JS7 REST Web Service.

Workflow: Example-AddOrders

The workflow looks like this:

• The first job add-orders will create 5 orders.
• The second job get-orders will check the status of newly added orders.
• The workflow is assigned the Example-AuthenticationSettings job resource.
  
  

Checking the first job: add-orders

When clicking the first job add-orders, then the job properties are displayed like this:

• Argument: request
• Argument: return_value
  
  

Argument: request

The request argument looks like this:

• The /orders/add endpoint is specified.
• The request body includes
  • the Controller ID that is available from the built-in js7ControllerId variable.
  • 5 orders specified from an array.
  • the workflowPath property specifies the name of the workflow to which orders will be added and which is available from the workflow variable with the same name.
• The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.
  
  

{
  "endpoint": "/orders/add",
  "method": "POST",
  "headers": [],
  "body": {
    "controllerId": "${js7ControllerId}",
    "orders": [
      {
        "workflowPath": "${workflow}",
        "orderName": "AddOrders-1",
        "forceJobAdmission": false,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      },
      {
        "workflowPath": "${workflow}",
        "orderName": "AddOrders-2",
        "forceJobAdmission": false,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      },
      {
        "workflowPath": "${workflow}",
        "orderName": "AddOrders-3",
        "forceJobAdmission": false,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      },
      {
        "workflowPath": "${workflow}",
        "orderName": "AddOrders-4",
        "forceJobAdmission": false,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      },
      {
        "workflowPath": "${workflow}",
        "orderName": "AddOrders-5",
        "forceJobAdmission": false,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      }
    ],
    "auditLog": {
        "comment": "5 orders added to workflow [${workflow}] by workflow: ${js7WorkflowPath}"
    }
  }
}

Argument: return_variable

The return_variable argument extracts values from the REST response and maps them to dynamic workflow variables like this:

• The deliveryDate property value is assigned the delivery_date variable.
• The orderIds array values are assigned the order_ids variable
• the number of orders added is assiged the order_added_count variable.
  
  

[
  {
    "name": "delivery_date",
    "path": ".deliveryDate"
  },
  {
    "name": "order_ids",
    "path": ".orderIds"
  },
  {
    "name": "order_added_count",
    "path": ".orderIds | length"
  }
]

Checking the second job: get-orders

When clicking the second job get-orders, then the job properties are displayed like this:

• Argument: request
• Argument: return_variable

Argument: request

The request argument looks like this:

• The /orders endpoint is specified.
• The request body includes
  • the Controller ID that is available from the built-in js7ControllerId variable.
  • the array of Order IDs that have been added by the add-orders job. The job's return_variable argument did specify the order_ids variable that holds newly added Order IDs and that is specified as the value of the orderIds element.
• The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.
  
  

{
  "endpoint": "/orders",
  "method": "POST",
  "headers": [],
  "body": {
    "controllerId": "${js7ControllerId}",
    "orderIds": ${order_ids}
  }
}

Argument: return_variable

The return_variable argument extracts values from the REST response and maps them to dynamic workflow variables like this:

• The deliveryDate property value is assigned the delivery_date variable.
• The orderIds are assigned the order_ids variable
• the number of orders found is assiged the order_get_count variable. The jq query filters orders that are in the RUNNING or BLOCKED (not yet started) state. Find details about use of jq for processing return variables from the JS7 - JITL jq Interface article.
  
  

[
  {
    "name": "delivery_date",
    "path": ".deliveryDate"
  },
  {
    "name": "order_ids",
    "path": ".orders[].orderId"
  },
  {
    "name": "order_get_count",
    "path": "[ .orders[] | select([.state._text] | inside([\"RUNNING\",\"WAITING\"])) | .orderId ] | length"
  }
]

Workflow: Example-AddOrders-Workflow

The workflow is minimalistic and includes a JS7 - Sleep Instruction only. Orders are added to this workflow by the add-orders job of the Example-AddOrders workflow.

Job Resource: Example-AuthenticationSettings

JS7 - Job Resources are used to store settings and crredentials to connect and to authenticate with the REST Web Service API. The Example-AuthenticationSettings job resource is assigned the Example-AddOrders workflow. The following settings are used:

• js7.api-server.url: Specification of the URL is required and has to be adjusted:
  • The hostname in the example is localhost. This will match only if JOC Cockpit and Agent are operated for the same server. Users should specify the hostname of the server for which JOC Cockpit is operated. If more than one JOC Cockpit instance is available, then they can be specified spearated by a pipe character |.
  • The port in the example is 4446. The port might be different depending on JOC Cockpit installation.
• js7.api-server.username: The account that is used to authenticate with JOC Cockpit.
• js7.api-server.password: The password used by the account.

The example is simplistic. The JS7 supports a number of more secure ways of authentication, for details see JS7 - JITL Common Authentication.

Documentation

The Job Documentation including the full list of arguments can be found from: https://www.sos-berlin.com/doc/JS7-JITL/JS7RESTClientJob.xml

Authentication

The Job makes use of the JS7 - REST Web Service API that is available from JOC Cockpit. 

• The job is executed with an Agent and requires a network connection to JOC Cockpit initiated by the Agent.
• The job has to authenticate with JOC Cockpit, for the related configuration see JS7 - JITL Common Authentication.

Arguments

The JS7RESTClientJob template accepts the following arguments:

Argument: request

The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.

Example for JSON request adding orders

The  request argument holds a JSON document that specifies the request to add an order like this:

{
  "endpoint": "/orders/add",
  "method": "POST",
  "headers": [],
  "body": {
    "controllerId": "testsuite",
    "orders": [
      {
        "workflowPath": "apTestWorkflow",
        "orderName": "AddOrders-1",
        "forceJobAdmission": false,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      }
    ],
    "auditLog": {
      "comment": "order added to workflow"
    }
  }
}

Explanations:

• endpoint: Specifies the JS7 - REST Web Service API endpoint, for example /orders/add, see the version of the documentation that matches the JS7 release in use.
  • No base URL is specified with the request to keep the job portable across environments. Instead, the base URL is specified from the js7.api-server.url argument, see JS7 - JITL Common Authentication  that is provided for example by JS7 - Job Resources.
  • The target URL for REST requests is created like this:
    • The base URL includes <protocol>://<host>:<port>. , for example http://centostest-secondary.sos:4446.
    • Follows the path /joc/api that will be automatically added.
    • Follows the endpoint, for example /orders/add.
    • Example for the resulting URL: http://centostest-secondary.sos:4446/joc/api/orders/add
• method: One of the HTTP methods offered by the REST Editor that matches the method accepted by the related REST API.
• headers: An array of key/value objects that corresponds to headers required or accepted by the related REST API.
• body: the request body as required or accepted by the related REST API.
  • The body can include workflow variables that are specified from the syntax: ${variable}
  • Users should be aware of the scope in which body variables are substituted:
    • When executed with the REST Editor using the Send Request button, then workflow variables are resolved. This means any variables specified with the workflow.
    • When executed with the JS7RESTClientJob then variables will be substituted from any sources used. This includes JS7 - Job Resources and dynamic variables created by predecessor jobs.

Example for JSON request exporting inventory objects

If users intend to export inventory data from the JS7 REST API by sending a REST request for example to the /inventory/export/folder endpoint, then an additional header is required. 

• The "X-Export-Directory" header specifies the directory to which the export file will be written.
  • Sub-directories in the path to a directory can be separated using forward slash or baskslash, for example C:\MyFiles and  C:/MyFiles are the same.
  • An absolute path can be specified such as /tmp or C:\MyFiles etc.
  • A relatvie path such as ./export or .\export can be specified that starts from the Agent's working directory which typically is the Agent's <agent-data> directory specified during installation.
• An existing file with the same name as the export file will be overwritten.

The following request will export all object types from the /Test inventory folder to the /tmp/test.zip export file on the Agent's machine. 

{
  "endpoint": "/inventory/export/folder",
  "method": "POST",
  "headers": [
    {
      "key": "X-Export-Directory",
      "value": "/tmp"
    }
  ],
"body":{
    "useShortPath": false,
    "exportFile": {
        "filename": "test.zip",
        "format": "ZIP"
    },
    "shallowCopy": {
        "objectTypes": [
            "WORKFLOW",
            "FILEORDERSOURCE",
            "JOBRESOURCE",
            "NOTICEBOARD",
            "LOCK",
            "REPORT",
            "INCLUDESCRIPT",
            "SCHEDULE",
            "WORKINGDAYSCALENDAR",
            "NONWORKINGDAYSCALENDAR",
            "JOBTEMPLATE"
        ],
        "folders": [
            "/Test"
        ],
        "recursive": true,
        "onlyValidObjects": false,
        "withoutDrafts": false,
        "withoutDeployed": false,
        "withoutReleased": false
    }
  }
}

Argument: return_variable

The job returns variables specified with its return_variable argument. Return variables are available to any subsequent jobs and instructions in the workflow.

The return_variable argument can be created by using the JS7 - JITL REST Editor or by manually adding the argument value.

The argument holds a JSON document that can look like this:

[
  {
    "name": "delivery_date",
    "path": ".deliveryDate"
  },
  {
    "name": "order_ids",
    "path": ".orderIds"
  },
  {
    "name": "order_added_count",
    "path": ".orderIds | length"
  }
]

Explanations:

• name: Holds the name of the return variable that will be created and will be used in the workflow.
• path: Holds the jq query to extract the desired value fromhe the response JSON. for details see JS7 - JITL jq Interface.
  • The jq query language is provided by jackson-jq, the Java implementation of jq.
  • Users can check the jq manual for relevant explanations how to extract data from the JSON response.

Resources

• JS7 - JITL Common Authentication
• JS7 - JITL Common Variables
• JS7 - JITL REST Editor
• JS7 - JITL jq Interface