Inbound REST Extension 1.0.0.2 and 1.0.0.3

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>`	Creates 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`

New Features in 1.0.0.2

With version 1.0.0.2, you can:

Cancel process recurrences.
Update processes with an external completion strategy.
Choose what fields are returned when submitting a Process Definition.
Reply to an Operator Message.
Reply to a User Message.
Reply to an Alert.
Start/stop/restart a Process Server.
Import a CAR file.
Download the contents of a process file.
Enable/disable Alert Sources.
GET, Create (POST), Update (PUT), and DELETE Credentials.
Updated Queue Provider handling for Process Servers. Now, Queue Providers are ignored on PUT/POST requests to the Process Server endpoints. Use POST/PUT/DELETE methods to the Queue Provider resource to create, update, or delete Queue providers.

Prerequisites

Version 9.2.9 or later
API Key Authentication Extension 1.0.0.2 or later (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>

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.
updateJob: Update Status, Description, JobNotes, or Job Parameters for jobs with an External completion strategy.

Operator Messages

<url>/OperatorMessage/<operatormessage_id>/<action>

reply: Replies to an Operator Message. Send a JSON object in the request body with this syntax:

{ "Reply": "MyReplyChoice" }

User Messages

<url>/UserMessage/<usermessage_id>/<action>

reply: Replies to a User Message. Send a JSON object in the request body with this syntax:

{ "Response": “MyResponseChoice“, "ReplyComment": "My reply comment" }

Alerts

<url>/Alert/<alert_id>/<action>

reply: Replies to an Alert. Send a JSON object in the request body with this syntax:

{ "Response": “Acknowledge“ }

Process Servers

<url>/ProcessServer/<partition>.<name>/<action>

stop: Stops a Process Server.
start: Starts a Process Server.
restart: Restarts a Process Server.

Alert Sources

Process Server Alert Sources: <url>/ProcessServerAlertSource/<partition>.<name>/<action>

Process Alert Sources: <url>/JobDefinitionAlertSource/<partition>.<name>/<action>

enable: Enables the alert source.
disable: Disables the alert source.

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.

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

Special Cases

Submitting a Process Definition:
- POST to <url>/Job/<job_definition_partition>.<job_definition_name>/submit
Raising an Event:
- POST to <url>/Event/<event_definition_partition>.<event_definition_name>
Importing a CAR file:
- POST to <url>/Import
- Headers :
  - content-type=application/octet-stream
- Query Parameters (all are optional):
  - TargetPartition: The name of the Partition to import into
  - WaitForCompletion: true|false: When true, the request will wait until the import completes before returning. If it completes successfully, you will receive a 200 response code. If it fails, you will receive a 500 response code. When false, the request will return immediatley after starting the import. It will return 200 if the import is started successfully, but that does not guarantee that the import completed successfully.
  - ImportRuleSet: PARTITION.Name format. The importruleset to apply to the import.
  - fileName: The name of the CAR file being imported. This is only used for logging.
- Request Body: The CAR file in binary format.

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/submit?fields=uniqueId,jobId,status"

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/submit?fields=uniqueId,jobId,status"

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/09/01 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"
#}

PUT to Update a Process with an External Completion Strategy

These examples illustrate updating the status, description, process notes, and parameters for the process with ID 12345.

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}/Job/12345/updateJob" -d - <<EOF
{
  "Status": "Completed",
  "JobNotes": [
    "Note 1",
    "Note 2"
  ],
  "JobParameters": [
   {
      "Name": "OutString",
      "OutValue": "My String Value"
    },
    {
      "Name": "OutNumber",
      "OutValue": 12345
    }
  ]
}
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=@'
{
  \"Status\": \"Completed\",
  \"JobNotes\": [
    \"Note 1\",
    \"Note 2\"
  ],
  \"JobParameters\": [
   {
      \"Name": \"OutString\",
      \"OutValue": \"My String Value\"
    },
    {
      \"Name\": \"OutNumber\",
      \"OutValue\": 12345
    }
  ]
}
'@

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

GET the Contents of a Process File

These examples illustrate fetching the contents of a process file with unique ID = 12345.

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 GET -H "${API_KEY}" "${URL}/JobFile/<jobFile_unique_id>/content"

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}/JobFile/<jobFile_unique_id>/content"