› Workflow › Business processes › Design a basic process › Add an activity › Activity types › Other activities › RESTful service activity › Configure a RESTful service activity

Configure a RESTful service activity

Use the following procedure to configure a RESTful service activity.

To use RESTful service activities, you must first set up a RESTful service reference. See Create a Web service reference.

  1. Add an activity to the map.

    By default, the Configuration tab is open in the properties panel of the activity.

  2. Change the default name of the activity to something meaningful.
  3. On the Type list, select Other > RESTful service.
  4. Configure other details as given below and save the process.

Configuration

Perform the following steps for configuration.

Web service
On this list, select either of the following.

A preconfigured RESTful web API

Depending on the selected RESTful service, the preconfigured Base URL appears.

The custom headers that are defined in the RESTful web API appear under the Custom header.

You can whitelist a web service reference. If the "Allow all" system setting is not selected, you can only use the whitelisted web service references. See Configure the server URLs and database connection strings.

A preconfigured RESTful Open API web service. See Create a Web service reference

The custom headers that are defined in the RESTful service appear under the Custom header.

The Configure link for the Parameters becomes available.

  1. Click Configure. The Base URL that is preconfigured in the Integration for the selected RESTful service is displayed.

  2. On the Class list, select a class. The methods available for the selected class appear.

  3. On the Method list, select a method. The list of parameters with the parameter types is displayed.

  4. Map the parameters with inline values or variables.

    • To allow the binary content of a document to be optionally used (instead of the document instance ID), map the document variable as input or output to a binary stream or byte array type parameter and specify the mime type. A document's binary data can be of different mime types (such as PDF, TIFF, or JPEG). Therefore, you need to specify the mime type of the binary data to be correctly retrieved or updated in the capture document content at runtime.

    • If the document variable is mapped to a string variable type, it is possible to retrieve or update the document by specifying the binary data as a base64 string instead of the instance ID. The "Data as Base64 string" or "Instance id " options are available if a document variable is mapped to a string variable, as input or output. By default, the " Instance id" is selected as the mapping type. If the data is set as a base64 string, you must specify a mime type. If the specified mime type is not available in the document, the system reports an error at runtime.

      See the mime types supported by TotalAgility. The "XLT" mime type is not applicable for a RESTful service activity.

When executing a RESTful service activity, for an input parameter, the document data is read and passed as byte[] or binary stream to the mapped API parameter. For an output parameter, the document data is set from the supplied byte[] or a stream. If the document variable points to an existing capture document, a new document is created instead of updating the old document data.

Base URL
Depending on the selected RESTful service, the preconfigured Base URL appears.
URL parameter
Optional. Specify the URL parameters (parameters of type String that influence the returned results) by doing one of the following:

  • To provide static parameters, enter the required text.

  • To dynamically get the information at the time of execution and display it to the user at runtime, right-click in the URL parameters rule editor and select the process or server variables.

  • Use a combination of static text and dynamic values.

You can reuse the base URL parameters by copying and pasting them into the base URL parameters of another restful service.

Verb
Select one of the options:
Type
Select the content type of the returned response:

  • XML (default)

  • JSON

Edit the default custom header

The custom headers are defined when creating a web service reference and their default values are displayed under the Custom header when you select that web service.

You can edit the default value of a custom header.

  1. Under the Custom header group, double-click the row or select the row and click .
  2. For Value, select a dynamic variable or clickand enter a static value.
  3. Click OK.

    When a job is created on the process, the custom values defined are passed to the Third-party web service. If no mapping or the inline value is provided in the activity, the default value defined in the RESTful service definition is used.

Handle a response

You can handle the response from a web service based on the status code returned by a REST service and can handle the response differently if needed.

HTTP response status codes indicate whether a specific HTTP request has been completed.

You can define a range of status codes, description, and response mapping (using variables or expressions). For example, you can define a range of 100 to 399, a description as "OK", and map variable A, and then define the second range of 400 to 599, a description as 'Problem', and map an expression to pull out the error message.

  1. Under the Response group, click . The Response dialog box is displayed.
  2. In the HTTP Status Code From and HTTP Status Code To boxes, specify a range of the status codes to handle.
    • The range is inclusive. For example, a range of 100 to 199 handles responses for status codes from 100 to 199.

    • You can define a response mapping for a specific code by defining the range as one number. For example, a range of 200 to 200 will handle the response for status code 200.

  3. In the Description box, enter a description such as "All responses".
  4. On the Response type list, select whether the response received from the RESTful service should be stored as a variable or expression and configure the value accordingly.

    Variable (default)

    On the Value list, select a process or server variable of type String, XML, or data object variable to store the entire output to a single variable.

    If the response is in JSON, then you can map a data object variable to hold the return value.

    When you execute the activity, the JSON string returned from the RESTful service is used to populate the variable based on the underlying data model.

    When debugging an activity that is using a data object variable, the value displayed is a JSON string.

    Expression

    Do the following:

    1. Click.

    2. To define the elements to extract from the expression, provide the correct Path.

      • If the response is XML, use XPath.

      • If the response is JSON, use JSONPath.

    3. On the Value list, select a process or server variable.

    4. Click Add.

Define a response header

You can access the response headers that are returned by a RESTful service and use these values if needed.

There are standard headers such as server and content-type, but there can be custom headers specific to the service. For example, the Microsoft Forms Recognizer service returns an Operation-Location header whose value is needed to extract data from a document.

You can define a list of response headers as key-value pairs by providing a name (inline text), and a String variable to hold the return value.

  1. Under the Response header group, click.
  2. In the Name box, enter a name for the response header.
  3. On the Value list, select a process or server variable to hold the return value.
  4. Click Add.
  5. On the Status code list, select a process or server variable. The job will be completed even if an error is found, and the selected status code is displayed at runtime. This helps a user to handle errors manually.

Configure error handling

Specify how to handle the returned status code under Error handling.

Suspend job on error

Select this check box to allow the job to be suspended on error.