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. On the Web service list, do either of the following:
    • Select the preconfigured RESTful web service reference as needed.

      Depending on the selected RESTful service, the preconfigured Base URL appears. Additionally, the custom headers that are defined in the RESTful service appear under the Custom header.

    • Select the preconfigured RESTful Open API web service. See Create a Web service reference.

      The Configure link for the Parameters becomes available. Click Configure to display the Base URL that is preconfigured in the Integration for the selected RESTful service. Select a Class and the Methods available for the selected class appear. Select a method to display the parameters and the parameter types where you can map inline values/variables to the parameters. Additionally, the custom headers that are defined in the RESTful service appear under the Custom header.

      • 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 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 mapping type. If the data is set as 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.

        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.

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

  5. On the Web service list, select the preconfigured RESTful web service reference as needed.

    Depending on the selected RESTful service, the Base URL appears. Additionally, the custom headers that are defined in the RESTful service 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.
  6. 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 relevant 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 it in the base URL parameters of another restful services.

  7. On the Verb list, select the action to perform: GET, DELETE, POST, PUT (Default: GET)
  8. To specify how to handle the returned status code, do either of the following for Suspend job on error. (Default: Clear)
    • Keep the check box clear and select a process or server variable on the Error code list.

      The job will be completed even if an error is found, and the selected error code is displayed at runtime. This helps a user handle errors manually.

    • Select the check box.

      The job is suspended if an error is found.

  9. Save the process map.

Retrieve or delete data

You can configure the Restful service activity to retrieve and delete data. A request to get information returns the response in either JSON or XML format. You can store the entire output to a single variable of type String, XML or Data object variable. If the response is in JSON, you can use a data object variable to hold the return value. You can use single fields of the data object to configure the request/response, such as SlackUserDetails. ID as a URL parameter or use SlackUserDetails.Channels which is a list with columns/rows.

Once the action is complete, the fields and arrays in the object are populated with the data returned. You can view these values at runtime or when debugging. The following information is displayed for the activity : Node ID, status, type, automatic, performed on, performed by, duration, request URL, request body, request headers, and response body.

  • URL: Shows the URL that was executed including any query string parameters.

  • Request header: Shows the headers that were passed to the service, including custom headers. These can be defined when you set up the REST service integration at the system level and overwritten at the activity level.

  • Request body: Shows the request body in either XML or JSON format depending on the activity configuration. If there is no body, for example, a GET request does not have a body, then it will display 'None'.

  • Response body (Including HTTP code): Shows the response in either XML or JSON format depending on the activity configuration and shows the HTTP status code.

If "Suspend job on error" is selected, the request URL, request body, request headers, and response body information of that activity is not displayed during process debugging.

Ideally the structure of the model and the response match. But in the case that the structure does not match, only the matching fields in the returned data and the matching fields in the data object structure are populated.

  • If any of the data in the response does not have a matching field in the data object structure, then it is ignored.

  • If there are fields in the data object structure that do not have a match in the response, then this is also ignored.

To retrieve or delete the data, perform the following steps:

  1. Select the Type as XML or JSON. (Default: XML)
  2. The custom headers are defined when creating a web service reference and their default values are displayed under the Custom header. To edit the default value of a custom header, do the following
    1. Double-click the row or select the row and click .
    2. For Value, select a dynamic variable or click and 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.
  3. Select either of the following on the Response type list:

    Select Variable (default) and map the entire output to a single variable of type String or XML by selecting a process or server variable on the Value list. You can use a data object variable to receive the response from the service and store it in the variable.

    You can map data object variable or specific fields in the data object variable.

    Select Expression and 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.

Insert or update data

You can configure the Restful service activity to insert and update data. For a POST/PUT, you can map the request and the response to data object variables. The request can accept multiple objects which are combined into a single request before being passed to the REST API call.

You can use single fields of the data object to configure the request/response, such as use SlackUserDetails.Id as a URL parameter or populate using an expression from the response.

To insert or update the data, perform the following steps:

  1. Select the Type as XML or JSON. (Default: XML)
  2. The custom headers defined when creating a web service reference and their default values are displayed under Custom header. To edit the default value of a custom header, do the following

    1. Double-click the row or select the row and click .
    2. For Value, select a dynamic variable or click and 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 inline value was provided in the activity, the default value defined in the RESTful service definition is used

    4. Right-click in the Request rule editor and select a process or server variable.

      You can use a data object variable or its specific fields to send the request to the service.

    5. Select either of the following on the Response type list:

      • Select Variable (default) and map the entire output to a single variable of type String or XML by selecting a process or server variable on the Value list. You can use a data object variable to receive the response from the service and store it in the variable.

        You can map data object variable or specific fields in the data object variable.

      • Select Expression and do the following:

        1. Click .

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

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

        4. Click Add.

    You can reuse the request by copying and pasting it in PUT and POST verb of another RESTful service.