Inbound REST Extension 1.0.0.0 and 1.0.0.1

The Inbound REST Extension adds a REST interface that supports API key authentication.

Note: RunMyJobs also offers the Built-in Inbound REST Interface, which lets you use only basic authentication.

The following actions are supported.

Syntax	Description	Example
`GET <object>/<business_key>`	Retrieves a JSON representation of an object.	`GET /api-extension/External/REDWOOD/Redwood_RestService/rest/v1/JobDefinition/System_Sleep`
`POST <object>/<business_key>`	Changes an object, based on the JSON you post. For `Job`, if you specify a Process Definition name, it will create a new process from the Process Definition, with default parameters.	`POST /api-extension/External/REDWOOD/Redwood_RestService/rest/v1/JobDefinition/System_Sleep`
`PUT <object>/<business_key>[/<action>]`	Performs an action on an existing object.	`PUT /api-extension/External/REDWOOD/Redwood_RestService/rest/v1/Job/123/hold`
`DELETE <object>/<business_key>`	Deletes an existing object.	`DELETE /api-extension/External/REDWOOD/Redwood_RestService/rest/v1/Job/123`

Prerequisites

API Key Authentication Extension (this dependency is handled automatically by the Catalog).
Privileges Required to Use REST services.
Connectivity between RunMyJobs and the REST host on its port.
Connectivity from the Secure Gateway to the REST host on its port.

Setup

To set up the REST Inbound Extension, locate REST Inbound in the Catalog and install it.

Contents of the Component

Object Type	Name
Application	`GLOBAL.Redwood/REDWOOD.RestService`
Extension Point	`REDWOOD.Redwood_RestService`
Library	`REDWOOD.Redwood_RestService`

Specifying an API Key

To use an API key, specify its value the X-API-KEY header. For examples of how to do this, see the cURL examples.

URL Syntax

URL syntax is as follows:

http[s]://<server>[:<port>]/<context>/api-extension/External/REDWOOD/Redwood_RestService/rest/v1

<server>: The FQDN of the Redwood server.
<port> (optional): The port the server is listening on. Defaults to the default port of the protocol (80 for HTTP, 443 for HTTPS).
<context>: The server context. This should be redwood by default for on-site installations, or <company_name>/<environment> for cloud environments.

For example:

https://s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1
https://s1.example.local:8443/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1
https://dublin.runmyjobs.cloud/example/test/api-extension/External/REDWOOD/Redwood_RestService/rest/v1

Swagger Documentation

Swagger documentation is available at the below URL. No API key required to access the documentation. The syntax for accessing the Swagger documentation is as follows.

http[s]://<server>[:<port>]/<context>/api-extension/External/REDWOOD/Redwood_RestService/rest/swagger.yml

For example:

https://redwood.example.com/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/swagger.yml
https://dublin.runmyjobs.cloud/example/test/api-extension/External/REDWOOD/Redwood_RestService/rest/swagger.yml

GET

GET retrieves a JSON representation of objects.

Note: You must have view privileges on objects you retrieve and any objects they reference.

Syntax

<url>/<object_type>/<partition>.<name>

PUT

PUT lets you use zero or more JSON formatted properties to update an object. It also lets you perform actions on processes.

Note: You must have the privileges necessary to update the object.

Syntax

<url>/<object_type>/<partition>.<name>

For Process Definitions: <url>/Job/<job_id>/<action>

cancel: Cancels a process in a pre-running state. You can use the cancelRecurrence=true parameter to also cancel all recurrences for the job, like so: /Job/<job_id>/cancel?cancelRecurrence=true
kill: Kills a process in a running state.
unknown: Sets a process to status Unknown.
hold: Holds a process in a pre-running state.
release: Releases a held process.
disable: Disables a Step or Chain Process in a Chain.
enable: Enables a Step or Chain Process in a Chain.
restart: Restarts a process.
resubmit (default): Resubmits a process. Any process properties provided in JSON are applied to the process.
runnow: Forces a process to ignore any events, locks, and schedules, and start running immediately.

POST

POST takes a JSON body and creates an object.

Note: You must have the privileges necessary to perform the actions.

Syntax

<url>/<object_type>/<partition>.<name>

For Process Definitions: <url>/Job/<job_definition_name>

For Event Definitions: <url>/EventDefinition/<event_definition_name>/<event_definition_action>

For Events: <url>/Event/<event_id>/<event_action>

<url>: The base URL.
<object_type>: The technical name of the object type. For example, JobDefinition for Process Definition, JobChain for Chain Definition, EventDefinition for event definition, or TimeWindow for Time Window.
<partition>: The name of the Partition of the object.
<name>: The name of the object.
<job_definition_name>: The name of a Process Definition. Uses the format <partition>.<name>.
<event_definition_name>: The name of an event definition. Uses the format <partition>.<name>.
<event_definition_action>: The action to perform on the event definition. The actions supported are clear (to clear the currently raised event from the event definition) and clearAllPending (to clear all pending events based on this event definition).
<event_id>: The ID of the event. Uses the format <name><raise_sequence>.
<event_action>: The action to perform on the event (in this case, clear).

Note: There must be an object of the specified type with the specified partition and name, except for Job and Event.

DELETE

DELETE deletes an object.

Note: You must have the privileges necessary to perform the actions.

Syntax

<url>/<object_type>/<partition>.<name>

cURL Examples

POST to Job

These examples illustrate submitting the System_Sleep Process Definition with default parameters. You can use the fields query parameter to control what fields are returned, or omit it to return all fields.

Bash

Copy

#!/bin/bash
API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
curl -X POST -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/System_Sleep"

PowerShell

Copy

#Windows Powershell and Windows' curl.exe

$API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
$URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"

curl.exe -X POST -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/System_Sleep"

PUT to Job

These examples illustrate resubmitting process 123 at 5PM Paris time on 2023/11/16.

Bash

Copy

#!/bin/bash

API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"

curl -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123/resubmit" -d - <<EOF
{
  "RequestedStartTime": "2023/11/16 17:00:00,000 Europe/Paris",
  "Description": "Submitted from REST Services using cURL"
}
EOF

PowerShell

Copy

#Windows Powershell and Windows' curl.exe

$API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
$URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
$JSON=@'
{
  \"RequestedStartTime\": \"2023/11/16 17:00:00,000 Europe/Paris\",
  \"Description\": \"Submitted from REST Services using cURL\"
}
'@

curl.exe -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123/resubmit" -d "$JSON"

PUT to Resubmit a Process Setting a Parameter

These examples illustrate resubmitting process 123 at 5PM Paris time on 2023/11/16 with parameter MilliSeconds set to 10000.

Bash

Copy

#!/bin/bash

URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"

curl -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123" -d - <<EOF
{
  "RequestedStartTime": "2023/11/16 17:00:00,000 Europe/Paris",
  "Description": "Submitted from REST Services using cURL",
  "JobParameters": [
   {
      "InValueDate": null,
      "InValueNumber": 10000,
      "InValueString": "1000",
      "JobDefinitionParameter": "JobDefinitionParameter:GLOBAL.System_Sleep.MilliSeconds",
      "OutValueDate": null,
      "OutValueNumber": null,
      "OutValueString": null
    }
  ]
}
EOF

PowerShell

Copy

#Windows Powershell and Windows' curl.exe

$API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
$URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
$JSON=@'
{
  \"RequestedStartTime\": \"2023/11/16 17:00:00,000 Europe/Paris\",
  \"Description\": \"Submitted from REST Services using cURL\",
  \"JobParameters\": [
   {
      \"InValueDate\": null,
      \"InValueNumber\": 10000,
      \"InValueString\": \"1000\",
      \"JobDefinitionParameter\": \"JobDefinitionParameter:GLOBAL.System_Sleep.MilliSeconds\",
      \"OutValueDate\": null,
      \"OutValueNumber\": null,
      \"OutValueString\": null
    }
  ]
}
'@

curl.exe -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123" -d "${JSON}"

PUT to Modify a Queue

These examples illustrate closing queue MyQueue.

Bash

Copy

#!/bin/bash

API_KEYk="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"

curl -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Queue/MyQueue" -d - <<EOF
{
  "Held": true
}
EOF

PowerShell

Copy

#Windows Powershell and Windows' curl.exe

$API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
$URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
$JSON=@'
{
  \"Held\": true
}
'@

curl.exe -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Queue/MyQueue" -d "{JSON}"

PUT to Modify a Queue Provider

These examples illustrate closing Queue provider for MyProcessServer serving MyQueue.

Bash

Copy

#!/bin/bash

API_KEYk="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"

curl -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/QueueProvider/Global.MyProcessServer.Global.MyQueue" -d - <<EOF
{
  "Held": true
}
EOF

PowerShell

Copy

#Windows Powershell and Windows' curl.exe

$API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
$URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
$JSON=@'
{
  \"Held\": true
}
'@

curl.exe -X PUT -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/QueueProvider/Global.MyProcessServer.Global.MyQueue" -d "{JSON}"

Delete a Process

This example shows how to delete a Process Definition.

Copy

API_KEY="X-API-KEY: Nluw0OaBA9T+3wgmv6fx1ZSIsBMt+NCfEUbQsveswBgGZyul+qZ75mIemTzgVyqsGPzpNg9O46B1//TMwh4edekD"
URL="https:/s1.example.local/redwood/api-extension/External/REDWOOD/Redwood_RestService/rest/v1"
curl -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123" | jq ."Description",."Documentation"

#This call retrieves the process and jq extracts the Definition and Documentation fields, for example:
# "DeleteMe"
# "Example process to be deleted"

#Actual deletion, note that we get no response for successful deletions
curl -X DELETE -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123"

#Now we try to retrieve it and we get an HTTP 404 - it was successfully deleted
curl -H "${API_KEY}" -H "Content-Type: application/json" "${URL}/Job/123"
# This call would return this
#{
#  "code":"404",
#  "message":"Unable to find object Job:123"
#}