Built-in Outbound REST Interface

The HTTP Job 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. 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 a 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 characters.
  • json: Escape the Parameter so that it can be included inside of a JSON string.
  • url: Escape using URL escaping. Assumes 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 a Parameter is null or empty, then nothing will be substituted. If the expansion refers to a Parameter that doesn't exist, this will be left in the source (for example, ${ParamThatDoesntExist} will remain as-is 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 can use SOAP Credentials with the outgoing REST API. The endpoint must match the server's hostname and optionally port (<server_name>[:<port>]), the Job Server will first search for a Credential with the port and hostname provided in the HTTP_URL Parameter, then fall back to the hostname.

Required Parameters

When you create HTTP REST Job Definitions, you may need to create the following two Parameters.

Name Direction Type
HTTP_URL In String
HTTP_Method In String

Procedure

  1. Navigate to Configure > Automate > Job Definitions.
  2. Click New.
  3. Choose HTTP REST service programs from the Type dropdown list.
  4. Optionally configure the Source field.
  5. On the Parameters tab, create (if necessary) and configure the required Parameters.
  6. Click Save & Close.

Example

Redwood REST API Example

Assume you want to close a Queue in a remote RunMyJobs instance using the REST API.

  1. Navigate to Configure > Automate > Job Definitions.
  2. Click New.
  3. Enter REST_Redwood_Example in the Name field.
  4. Choose HTTP REST service programs from the Type dropdown list.
  5. Enter the code below in the Source field.
  6. On the Parameters tab, create (if necessary) the required Parameters and configure them as follows:
    • HTTP_URL: https://redwood.example.com/redwood/api-rest/xml
    • HTTP_Method: PUT
  7. Create a Parameter named Held with Simple Constraint Type set to List and Simple Constraint Data set to true,false.
  8. Click Save & Close.
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

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

  1. Create a SOAP Credential.
  2. Enter the Jira username in the Real User field and the password in the Password field.
  3. Fill jira.example.com into the Endpoint field.
  4. Click Save & Close.
  5. Navigate to Configure > Automate > Job Definitions and create a new Job Definition.
  6. Select HTTP REST service programs from the Type dropdown list.
  7. Enter REST_Jira_Example in the Name field.
  8. Paste the code below into the Source field.
  9. Enter the Real User value specified in the SOAP Credential in the Run As User field.
  10. On the Parameters tab, create (if necessary) the required Parameters and configure them as follows:
    • HTTP_URL: https://jira.example.com/rest/api/2/issue/QA-31
    • HTTP_Method: PUT
  11. Click Save & Close.
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

Assume you have been issued a bearer token to connect to a REST service.

  1. Navigate to Configure > Automate > Job Deifinitions.
  2. Click New.
  3. Enter REST_Example_Bearer in the Name field.
  4. Choose HTTP REST service programs from the Type dropdown list.
  5. Paste the code below in the Source field.
  6. On the Parameters tab, create (if necessary) the required Parameters and configure them as follows:
    • HTTP_URL: https://rest.example.com/rest/api/some/service?q="hello world!"
    • HTTP_Method: PUT
  7. Click Save & Close.
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