Operation Responses

You can use the Response screen of the Edit REST Operation window to configure an Operation to map the response from a REST API call to output parameters in a variety of ways.

Operations support the following response types: None, String, JSON, XML, and File.

None

Use this option if there is no response, or if you want to discard the response.

String

You can use this option to map a plain-text response to a String output parameter. Define the name of the parameter in the Parameter Name field and optionally provide a Parameter Description.

Note: The output parameter will be created automatically using the name you enter here. You do not need to create an Operation Variable.

JSON

If the call response is in JSON format, you can use JSONPath to extract the specific information you need and map it to one or more String output parameters.

To use JSONPath, add one or more rows that specify a path, a Type (String or Number), a Parameter Name, and an optional Parameter Description.

  • To use standard JSONPath to map a field to a single value, enter the path to the parameter you want (for example: $.store.books[0].title).

  • To use a shortcut method, simply enter the name of the element you want (for example: store). RunMyJobs will retrieve the value for the first occurrence of that element.

  • To map multiple values to an array parameter (for example: $.store.books), check Array.

Note: Output parameters will be created automatically using the names you enter. You do not need to create Operation Variables.

If you also want to write the full response body to a String output parameter, check the box at the bottom, define a Parameter Name, and optionally specify a Parameter Description.

XML

If the call response is in XML format, you can use XPath to extract the specific information you need and map it to one or more String output parameters.

To use XPath, add one or more rows that specify a path, a Type (String or Number), a Parameter Name, and an optional Parameter Description.

  • To use standard XPath to map a field to a single value, enter the path to the parameter you want (for example: /store/books[0]/title).

  • To map multiple values to an array parameter (for example: /store/books), check Array.

Note: Output parameters will be created automatically using the names you enter. You do not need to create Operation Variables.

If you also want to write the full response body to a String output parameter, check the box at the bottom, define a Parameter Name, and optionally specify a Parameter Description.

XML Namespaces

The XPath parser used complies with XPath 1.0 conventions. Consequently, the following rules apply for parsing XML that uses namespaces.

No Namespaces

If there are no namespaces in the XML, then no prefix is needed in your XPath queries. So, for example, assume you are querying the following XML:

<bookstore>
  <book>
    <title>MyBook</title>
  </book>
</bookstore>

In this case, you could use the following query to retreive the <title>:

  • /bookstore/book/title

Aliased Namespaces without a Default Namespace

If the XML uses a namespace with an alias, but there is no default namespace, you must use the alias when querying for aliased elements. So, for example, assume you are querying the following XML:

<bookstore xmlns:d="http://schemas.microsoft.com/my/sample/namespace">
  <book>
    <d:title>MyBook</d:title>
    <price>20</price>
  </book>
</bookstore>

In this case, you could use the following queries to retrieve the <title> and <price>:

  • /bookstore/book/d:title (namespaced element requires alias prefix)

  • /bookstore/book/price (other elements require no prefix)

Default Namespaces

If there is a default namespace, then the prefix default: must be used when referencing any element that uses the default namespace. So, for example, assume you are querying the following XML:

<bookstore xmlns="http://schemas.microsoft.com/my/default/namespace" xmlns:d="http://schemas.microsoft.com/my/sample/namespace">
  <book>
    <d:title>MyBook</d:title>
    <price>20</price>
  </book>
</bookstore>

In this case, you could use the following queries to retrieve the <title> and <price>:

  • /default:bookstore/default:book/d:title

  • /default:bookstore/default:book/default:price

File

To save the entire response body to a file, choose the File response type. This will cause the response to be saved as a process file, and you will be able to access it in the Detail View for the executed process in the Process Monitor. The parameters for this option are as follows:

  • Job File Name: The name that should be assigned to the process file. You can use a String Operation Variable to specify the file name when submitting the Process Defintion.

  • Parameter Name: The name of the output parameter that the process file should be assigned to.

  • Parameter Description: An optional description for the file.