Built-in Outbound REST Interface

The HTTP Process Definition Type lets you call REST services.

Note: RunMyJobs also offers the Inbound REST Extension, which lets you use API key authentication.

Built-in Parameters

  • HTTP_URL: The URL of the REST service.
  • HTTP_Method: The HTTP method used to call the REST server. Defaults to GET if this parameter is missing.
  • HTTP_Version: The HTTP version to use for the request.
  • HTTP_Content-Type: The Content-Type header to set for the request.

Out and In/Out Parameters

If XML or JSON data is returned, RunMyJobs tries to map that data to Out and In/Out parameters by name. If a parameter of type Array matches the name of a JSON array, the parameter is populated with the contents of the JSON array.

The default JSONPath used is $..<fieldname>, where <fieldname> is taken from the parameter name. You can specify a custom JSONPath in the Process Format field of the parameter.

Syntax

Copy 
<text>
[headers]
Content-Type=application/json
  • <text> (optional): The data to send to the server.
  • [headers]: A list of headers with the syntax <header_name>=<header_value>.

Sending Files

To send a file with an HTTP call, add an In or In/Out File parameter, use the following syntax.

Copy 
[File:nameOfFileParameter]
Name=${nameOfFileParameter}

[Headers]
Content-Type=text/plain

For example, assume you've created an In parameter of type File named xmlFile, and the file to be passed to the parameter is an XML file. Your Source might look like this:

Copy 
[File:xmlFile]
Name=${xmlFile}

[Headers]
Content-Type=application/xml

You can send multiple files at one type by using multiple File parameters. For example:

Copy 
[File:xmlFile]
Name=${xmlFile}
Content-Type=application/xml

[File:jsonFile]
Name=${jsonFile}
Content-Type=application/json

Multipart/form-data Syntax

Copy 
--<boundary>
 Content-Disposition: form-data; name="<name>" [filename="<name>"]
 Content-Type: <content-mime-type-1>[;<content-encoding-1>]
<data-1>
[--<boundary>--
 Content-Disposition: form-data; name="<name>" [filename="<name>"]
 Content-Type: <content-mime-type-n>[;<content-encoding-n>]
<data-n>
<boundary>--]+
[Headers]
Content-Type=multipart/form-data; boundary=<boundary>
  • <boundary>: The boundary delimiter cannot appear inside any of the encapsulated parts, you may have to enclose the "boundary" parameter values in quotes in the Content-Type header field.
  • <name>: The name of the content should be unique, you should avoid parts with the same name.
  • filename="<name>: Optional file name, if the content is to be used as a file.
  • <content-mime-type-n>[;<content-encoding-n>]: MIME type and, optionally, encoding of the part.
  • <data-n>: Data must be of the media type specified in the Content-Type declaration for the part (MIME type and, if specified, the encoding).
  • [ .. ]+: There can be more than two parts, each must have its unique name and the correct Content-Type header for the data.

Parameter Substitution

The syntax for parameter substitution is:

Copy 
${parameter[:<encoding>]}

The following parameter escape and encoding strategies are available:

  • xml: escape using XML 1.1 character escaping rules, the result will also use character entities for any non-ASCII character
  • json: escape the parameter so that it can be included inside of a JSON string
  • url: escape using URL escaping, assuming a UTF-8 character set
  • html: escape using HTML character escaping rules
  • base64: encode using base64

These can also be combined to allow multiple escapes to be applied in order. If the value of the parameter is null or empty, then nothing will be substituted, and if the expansion refers a parameter that doesn't exist, this will be left in the source, for example, ${ParamThatDoesntExist} will get left in the Source field.

This example sets a parameter named GREETING to &greeting="Hello World".

Copy 
X-My-Token=${GREETING} is evaluated as &greeting="Hello World"
X-My-Token0=${GREETING:url} is evaluated as %26greeting%3d%22Hello%20World%22
X-My-Token1=${GREETING:xml} is evaluated as &amp;greeting=&quot;Hello World&quot;
X-My-Token2=${GREETING:json} is evaluated as &greeting=\"Hello World\"
X-My-Token3=${GREETING:html} is evaluated as &amp;greeting=&quot;Hello World&quot;
X-My-Token3=${GREETING:base64} is evaluated as JmdyZWV0aW5nPSJIZWxsbyBXb3JsZCI=

Credentials

You use credentials of protocol SOAP with the outgoing REST API; the endpoint must match the server's hostname and optionally port (<server_name>[:<port>]), the Process Server will first search for a credential with the port and hostname provided in the HTTP_URL parameter, then fall back to the hostname.

Procedure

  1. Navigate to Definitions > Processes.
  2. From the context menu, choose New Process Definition, select REST/HTTP.
  3. Fill the Name field.
  4. Fill the Source field (optional).
  5. On the Parameters tab, you fill the HTTP_URL and HTTP_Method parameters.
  6. Click Save & Close.

Example

Redwood REST API Example

You wish to close a Queue in a remote Redwood Server central server using the REST API.

  1. Navigate to Definitions > Processes.
  2. From the context menu, choose New Process Definition, select REST/HTTP.
  3. You fill REST_Redwood_Example in the Name field.
  4. You fill the below text in the Source field.
  5. On the Parameters tab, you set HTTP_URL to https://redwood.example.com/redwood/api-rest/xml.
  6. On the Parameters tab, you set HTTP_Method to PUT.
  7. On the Parameters tab, you create a parameter named Held with Simple Constraint Type set to List and Simple Constraint Data set to true,false.
Copy 
<?xml version='1.0'?>
<Queue>
  <Comment />
  <Description>Queue for REST API</Description>
  <Name>REST_Queue</Name>
  <Partition type="Partition" path="GLOBAL" />
  <ParentApplication />
  <ExecutionSize />
  <Held>${Held}</Held>
  <HoldLevel />
  <Inclusive>false</Inclusive>
  <InclusiveConsoleJobs>true</InclusiveConsoleJobs>
  <Overdue>false</Overdue>
  <QueueTimeZone />
  <TimeWindow />
</Queue>
[Headers]
Authorization=Basic V2h5IGFyZSB5b3Ugd2FzdGluZyB5b3VyIHRpbWU/Cg

Jira Example

You want to update an issue in Atlassian Jira, your issue tracking system.

  1. Navigate to Security > Credentials.
  2. Choose New Credential from the context menu.
  3. Select soap as credential protocol.
  4. Fill the username into the Real User field, the password into the Password field, repeat.
  5. Fill jira.example.com into the Endpoint field.
  6. Navigate to Definitions > Processes.
  7. From the context menu, choose New Process Definition, select REST/HTTP.
  8. Fill REST_Jira_Example in the Name field.
  9. Fill the below text in the Source field.
  10. Fill the Real User as specified in your credential in the Run As User field.
  11. On the Parameters tab, you set HTTP_URL to https://jira.example.com/rest/api/2/issue/QA-31.
  12. On the Parameters tab, you set HTTP_Method to PUT.
  13. Click Save & Close.
  14. Locate the newly created Process Definition and select Submit from its context menu.
  15. Select Next then Submit.
Copy 
{
   "update": {
   "description": [
         {
            "set": "JIRA should also come with a free pony"
         }
      ],
      "comment": [
         {
            "add": {
               "body": "This request was originally written in French, which most of our developers can't read"
            }
         }
      ]
   }
}
[Headers]
Content-Type=application/json

Bearer Authentication Example

You have been issued a bearer token to connect to a REST service.

  1. Navigate to Definitions > Processes.
  2. From the context menu, choose New Process Definition, select REST/HTTP.
  3. You fill REST_Example_Bearer in the Name field.
  4. You fill the below text in the Source field.
  5. On the Parameters tab, you set HTTP_URL to https://rest.example.com/rest/api/some/service?q="hello world!".
  6. On the Parameters tab, you set HTTP_Method to GET.
  7. Click Save & Close.
  8. Locate the newly created Process Definition and select Submit from its context menu.
  9. Select Next then Submit.
Copy 
[Headers]
Authorization=Bearer AAAAAAAAAAAAAAAAAAAAAGlHGAEAAAAAV2h5I%3GFyZSB5b3Ugd2Fzd
Content-Type=application/x-www-form-urlencoded

Multipart

The following is a multipart form data request consisting of a JSON document and an XML document. The A300B4a350xw is a boundary marker that can be freely chosen but that should not be present in the data, in this example the JSON or XML you send.

Copy 
--A300B4a350xw
 Content-Disposition: form-data; name="jsondata"
 Content-Type: application/json; charset=UTF-8
{
  "Name" : [
    "John",
    "Joe" : "apple",
    "Pete" : "orange"
  ]
}
--A300B4a350xw--
 Content-Disposition: form-data; name="xmldata"
 Content-Type: application/xml; charset=UTF-8
<?xml version="1.0" encoding="UTF-8"?>
<xml id="test" version="1.0">
  <content>
    <empty ref="simple" />
    <child>
      <plan partitions="3" />
    </child>
  </content>
</xml>
A300B4a350xw--
[Headers]
Content-Type=multipart/form-data; boundary=A300B4a350xw