Introduction

The JITL RESTClientJob template implements a generic job for executing REST requests to web services that uses Basic Authentication (username and password encoded in Base64) or OIDC Client Credentials flow Authentication and supports either HTTP or HTTPS protocols.

Authentication

The job template authenticates using Basic Authentication.

Delimitation

Users who wish to execute REST requests to the JS7 - REST Web Service API can use the JS7 - JITL JS7RESTClientJob.

FEATURE AVAILABILITY STARTING FROM RELEASE 2.8.1

Usage

When defining the job either:

invoke the Job Wizard that is available from the job properties tab in the Configuration view and select the JITL RESTClientJob from the Job Wizard.

or

specify the JITL job class and com.sos.jitl.jobs.rest.RESTClientJob 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 RESTAPIClientJob.

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.
- log_items: Optionally contains the details of which item(request, response) should be logged at the info level.
- username: Optionally contains the username for Basic authentication.
- password: Optionally contains the password for Basic authentication.
- client_id: Optionally contains the Client Id for Client Credential flow authentication.
- client_secret: Optionally contains the Client Secret for Client Credential flow authentication.
- encipherment_private_key_path: Optionally specifies the path to the private key used for decryption of encrypted username and password values. The file must be accessible to the Agent executing the job.
- keystore_file: Optionally holds the path to the private key used for decryption of encrypted username and password values. The file must be accessible to the Agent executing the job.
- keystore_alias: Specifies the path to a PKCS12 keystore file holding the private key and certificate used for HTTPS communication or mutual TLS (mTLS) authentication. This parameter can be referenced dynamically using a Job Resource.
- keystore_password: Specifies the password used to access the keystore file. This password protects the keystore integrity.
- keystore_key_password: Optionally holds the password for accessing the private key within the keystore. This is required if the private key is protected separately from the keystore password.
- truststore_file: Specifies the truststore file in PKCS12 format that holds the CA certificates used to verify the identity of remote HTTPS servers.
- truststore_password: Specifies the password for accessing the truststore file that contains CA certificates.
- credential_store_file: Specifies the path to a KeePass database file (*.kdbx) used as a Credential Store. This parameter is required if credentials (username/password) are retrieved from KeePass
- credential_store_file: Specifies the key file used to unlock the KeePass database. Depending on your setup, you might use a key file, a password, or both.
- credential_store_file: Specifies the password required to access the KeePass credential store. You can use a password, a key file, or both depending on how your KeePass database is configured.
Note that the the checkbox provided with each argument has to be selected to add the argument to your instance of the RESTClientJob.

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: Using Basic Authentication

Importing the Example

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

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

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

The following objects are included:
- Workflow: Example-RESTClientJob-Workflow implements the RESTClientJob to add order to the Example-OrderAdded.
- Workflow: Example-OrderAdded is a simple workflow that sleeps for a few seconds.

Workflow: Example-RESTClientJob-Workflow

The workflow looks like this:

The first job get-access-token will fetch the access-token by logging in a new JS7 session and return it using return_variable argument.
The second job Add-order will add order to the workflow Example-OrderAdded.
Now the order will be in waiting state because of the sleep instruction.

Checking the first job: get-access-token

When clicking the first job get-access-token, then the job properties are displayed like this:

Argument: request
Argument: return_value

Argument: request

The request argument looks like this:

The http://centostest-secondary.sos:4446/joc/api/authentication/login full url in endpoint is specified.
The method is specified as POST.
The headers array is empty as it contains authentication details for the api/url, which is available from the workflow variable with the variable name username, password.
The request body is empty as per the api requirement.
The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.

JSON document of request argument

{
  "endpoint": "http://centostest-secondary.sos:4446/joc/api/authentication/login",
  "method": "POST",
  "headers": [],
  "body": {}
}

Argument: return_variable

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

The accessToken property value is assigned the accessToken variable.

JSON document of return_variable argument

[
  {
    "name": "accessToken",
    "path": ".accessToken"
  }
]

Checking the second job: Add-order

When clicking the second job Add-order, then the job properties are displayed like this:

Argument: request
Argument: return_variable

Argument: request

The request argument looks like this:

The http://centostest-secondary.sos:4446/joc/api/orders/add full url in endpoint is specified.
The method is specified as POST.
The headers array have been added by the get-access-token job. The job's return_variable argument did specify the accessToken variable that holds the new session's access token and that is specified as the value of the accessToken element.
The request body includes
- the Controller ID that is available from the built-in js7ControllerId variable.
- 1 order details are specified from an array in orders.
- 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.

JSON document of request argument

{
  "endpoint": "http://centostest-secondary.sos:4446/joc/api/orders/add",
  "method": "POST",
  "headers": [
{
      "key": "x-access-token",
      "value": ${accessToken}
    }
  ],
  "body": {
    "controllerId": "${js7ControllerId}",
    "orders": [
      {
        "workflowPath": "${workflow}",
        "orderName": "",
        "forceJobAdmission": false,
        "priority": 0,
        "tags": [],
        "arguments": {},
        "scheduledFor": "now"
      }
    ],
    "auditLog": {
        "comment": "1 order 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 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.

JSON document of return_variable argument

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

Checking the third job: get-orders

When clicking the third 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 http://centostest-secondary.sos:4446/joc/api/orders endpoint is specified.
The method is specified as POST.
The headers array have been added by the get-access-token job. The job's return_variable argument did specify the accessToken variable that holds the new session's access token and that is specified as the value of the accessToken element.
The request body includes
- The Controller ID that is available from the built-in js7ControllerId variable.
- The method is
- The array of Order IDs that have been added by the Add-order job. The job's return_variable argument did specify the order_ids variable that holds newly added Order ID 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.

JSON document of request argument

{
  "endpoint": "http://centostest-secondary.sos:4446/joc/api/orders",
  "method": "POST",
  "headers": [
{
      "key": "x-access-token",
      "value": ${accessToken}
    }
],
  "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.

JSON document of return_variable argument

[
  {
    "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"
  }
]

Checking the fourth job: logout

When clicking the fourth job logout, then the job properties are displayed like this:

Argument: request

Argument: request

The request argument looks like this:

The http://centostest-secondary.sos:4446/joc/api/authentication/logout endpoint is specified.
The method is specified as POST.
The headers array have been added by the get-access-token job. The job's return_variable argument did specify the accessToken variable that holds the new session's access token and that is specified as the value of the accessToken element.
The request body is empty as per the
The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.

JSON document of request argument

{
  "endpoint": "http://centostest-secondary.sos:4446/joc/api/authentication/logout",
  "method": "POST",
  "headers": [
    {
      "key": "x-access-token",
      "value": ${accessToken}
    }
  ],
  "body": {}
}

Workflow: Example-OrderAdded

The workflow is minimalistic and includes a JS7 - Sleep Instruction only. Order is added to this workflow by the Add-order job of the Example-OrderAdded.

Example: Using Client Credentials Flow Authentication

Importing the Example

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

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

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

The following objects are included:
- Workflow: Keycloak-OIDC-Workflow implements the RESTClientJob to get the username of Keycloak.
- Job Resource: Encipherment-Private-Key is a job resource that contains the encipherment private key path( needs to be updated) for the encrypted values used in the above workflow.

Workflow: Keycloak-OIDC-Workflow

The workflow looks like this:

The first job get-access-token will fetch the access-token by using sending the rest call and return it using return_variable argument.
The second job get-username will fetch the username by sending the request and return it for the further downstream jobs.
The third and last job show-username will show the username.

Checking the first job: get-access-token

When clicking the first job get-access-token, then the job properties are displayed like this:

Argument: request
Argument: return_value

Argument: request

The request argument looks like this:

The https://localhost:8443/realms/js7-realm/protocol/openid-connect/token full url in endpoint is specified.
The method is specified as POST.
The headers array containing the content type that is getting shared in the body.
The request body is shared as per the api requirement containing the client credentials details ( these values can also be shared as a single argument with the same key see StartingfromtheJobWizard).
The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.

JSON document of request argument

{   
    "endpoint": "https://localhost:8443/realms/js7-realm/protocol/openid-connect/token",   
    "method": "POST",   
    "headers": [     
       {       
           "key": "Content-Type",       
           "value": "application/x-www-form-urlencoded"     
       }   
    ],   
    "urlEncodedData": {     
       "grant_type": "client_credentials",     
       "client_id": "%{encrypted_client_id}",     
       "client_secret": "%{encrypted_client_secret}"   
    } 
}

Argument: return_variable

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

The access_token property value is assigned the accessToken variable. The Output Processing Instruction -r will returns the raw value of the variable, for details see JS7 - JITL jq Interface#UsingReturnVariables.

JSON document of return_variable argument

[   
   {     
      "name": "accessToken",     
      "path": ".access_token || -r"   
   } 
]

Checking the second job: get-username

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

Argument: request
Argument: return_variable

Argument: request

The request argument looks like this:

The https://localhost:8443/admin/realms/js7-realm/users?max=100 full url in endpoint is specified.
The method is specified as GET.
The headers array have been added by the get-access-token job. The previous job's return_variable argument did specify the accessToken variable that holds the access token and that is specified as the value of the access_token element.
The request argument is created by using the JS7 - JITL REST Editor or by manually adding the argument value.

JSON document of request argument

{
  "endpoint": "https://localhost:8443/admin/realms/js7-realm/users?max=100",
  "method": "GET",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer $accessToken"
    }
  ]
}

Argument: return_variable

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

The tostring property value is assigned the username variable.

JSON document of return_variable argument

[
  {
    "name": "username",
    "path": "tostring"
  }
]

Checking the third job: show-username

When clicking the third job show-username, then the job properties are displayed like this: containing the user name fetched from above job

Environment Variables : uname - containing the username fetched from the previous job

JSON document of request argument

echo ${uname}

Variable Encryption

Importing the Example

For example, the following archive file can be imported into the JOC Cockpit inventory:

Download: RESTClientJob-VariableEncryption.zip
For import see JS7 - Inventory Export and Import.

In the above Workflow it is demonstrated how an confidential value can be used after encryption in the workflow variables for the security purpose. In the workflow the encrypted value of the hostname as %{encrypted_hostname} is used in the request JSON. Please refer to the following article JS7 - JITL Common Variable Substitution for more information Variable Substitution in the JITL job.
The encrypted values can be used from all the available options(JS7 - Variables) of specifying the variables.

Documentation

The Job Documentation including the full list of arguments is available from: https://www.sos-berlin.com/doc/JS7-JITL/RESTClientJob.xml

Authentication

Authentication is specific for the 3rd-party REST Web Service.

The job is executed with an Agent and requires a network connection to the REST Web Service.
The job can use Authentication Settings, for the related configuration see JS7 - JITL Common Authentication.

Arguments

The RESTClientJob template accepts the following arguments:

Category	Name	Required	Default Value	Purpose
	`request`	yes	n/a	Specifies the REST request in JSON format. The argument is preferably managed from the JS7 REST Editor.
	`return_variable`	no	n/a	Maps values from a REST response JSON to variables. It accepts a JSON array where each object has a `name` (the variable name) and a `path` (a jq query to extract the value from response JSON). These variables are created dynamically and can be used in subsequent jobs. It's best configured via the JS7 REST Editor.
	`url`	no	n/a	Specifies the complete URL of the API endpoint (e.g., https://example.com/user/details). Can be provided directly in the Workflow variables or referenced from a Job Resource.
	`log_items`	no	request:body	Specifies details of which item(request, response) should be logged at the info level.
Authentication	`username`	no	n/a	Specifies the username for Basic authentication.
	`password`	no	n/a	Specifies the password for Basic authentication.
	`client_id`	no	n/a	Optionally contains the Client Id for Client Credential flow authentication.
	`client_secret`	no	n/a	Optionally contains the Client Secret for Client Credential flow authentication.
	`encipherment_private_key_path`	no	n/a	Specifies the path to the private key used for decryption of encrypted username and password values. The file must be accessible to the Agent executing the job. For more details, see: JS7 – Encryption and Decryption.
Certificate Store				Settings in the section are applied if certificates are used for HTTPS connection. For more details, see: JS7 - How to add SSL TLS Certificates to Keystore and Truststore
	`keystore_file`	no	n/a	Specifies the path to the private key used for decryption of encrypted username and password values. The file must be accessible to the Agent executing the job.
	`keystore_alias`	no	n/a	Specifies the path to a `PKCS12` keystore file holding the private key and certificate used for HTTPS communication or mutual TLS (mTLS) authentication. This parameter can be referenced dynamically using a Job Resource.
	`keystore_password`	no	n/a	Specifies the password used to access the keystore file. This password protects the keystore integrity.
	`keystore_key_password`	no	n/a	Specifies the password for accessing the private key within the keystore. This is required if the private key is protected separately from the keystore password.
	`truststore_file`	no	n/a	Specifies the truststore file in `PKCS12` format that holds the CA certificates used to verify the identity of remote HTTPS servers.
	`truststore_password`	no	n/a	Specifies the password for accessing the truststore file that contains CA certificates.
Credential Store				A Credential Store is a compliant database that centrally manages credentials. It provides a single, secure copy of all credentials and sensitive data. See : JS7 - Credential Store
	`credential_store_file`	no	n/a	Specifies the path to a KeePass database file (`*.kdbx`) used as a Credential Store. This parameter is required if credentials (username/password) are retrieved from KeePass
	`credential_store_file`	no	n/a	Specifies the key file used to unlock the KeePass database. Depending on your setup, you might use a key file, a password, or both.
	`credential_store_file`	no	n/a	Specifies the password required to access the KeePass credential store. You can use a password, a key file, or both depending on how your KeePass database is configured.

Argument: request

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

The request argument holds a JSON document that specifies the request to be sent to an Web service API, like this:

JSON request variable example

{
  "endpoint": "http://example.com/user/details",
  "method": "POST",
  "headers": [
{
      "key": "Authorization",
      "value": "Basic dXNlcjpfzZWNyZXQ="
    }
  ],
  "body": {
     "id": "2",
    "details": { 
         "name": "John", 
         "age": "50", 
         "email": "example@gmail.com" 
    }
  }
}

Explanations:

endpoint: Specifies the complete url with protocol, host and endpoint of the Web Service API.
- Base URL should be specified with the request or can be added to the url argument, in the Job resources and attached to the workflow.
- The target URL for REST requests is created like this:
  - The URL includes <protocol>://<host>:<port>. , for example https://api.example.com.
  - Follows the endpoint, for example /user/details.
  - Example for the resulting URL: https://api.example.com/users.
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}
- To use encrypted values in variables, the variable should be specified using the syntax : %{variable_name}
- The body can be shared in the following formats:
  - urlEncodedData (application/x-www-form-urlencoded)
  - body (application/json)
  - formData (multipart/form-data)
- 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 RESTClientJob then variables will be substituted from any sources used. This includes JS7 - Job Resources and dynamic variables created by predecessor jobs.

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:

JSON return_variable example

[
  {
    "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.

Argument: url

The complete URL of the Web Service API to which the REST call will be sent. The URL generally includes the protocol, host, and an optional port.

Argument: username

The variable username contains the username for Basic authentication. Supported formats:

Plain text
Encrypted value
Reference to a credential from a Credential Store

Argument: password

The variable password contains the password for Basic authentication. Supported formats:

Plain text
Encrypted value
Reference to a credential from a Credential Store

Argument: client_id

The variable client_id contains the client id for Client Credential flow authentication. Supported formats:

Plain text
Encrypted value
Reference to a credential from a Credential Store

Argument: client_secret

The variable client_secret contains the client secret for Client Credential flow authentication. Supported formats:

Plain text
Encrypted value
Reference to a credential from a Credential Store

Space shortcuts

Page tree

JS7 - JITL RESTClientJob

Introduction

Usage

Starting from the Job Wizard

Starting from the Example: Using Basic Authentication

Importing the Example

Workflow: Example-RESTClientJob-Workflow

Checking the first job: get-access-token

Argument: request

Argument: return_variable

Checking the second job: Add-order

Argument: request

Argument: return_variable

Checking the third job: get-orders

Argument: request

Argument: return_variable

Checking the fourth job: logout

Argument: request

Workflow: Example-OrderAdded

Example: Using Client Credentials Flow Authentication

Importing the Example

Workflow: Keycloak-OIDC-Workflow

Checking the first job: get-access-token

Argument: request

Argument: return_variable

Checking the second job: get-username

Argument: request

Argument: return_variable

Checking the third job: show-username

Variable Encryption

Importing the Example

Documentation

Authentication

Arguments

Argument: request

Argument: return_variable

Argument: url

Argument: username

Argument: password

Argument: client_id

Argument: client_secret

Further Resources