› 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. 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 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 Custom header.

  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 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 or 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 use 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 object are populated with the data returned. You can view these values at runtime or when 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 is 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 does 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 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.
  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.

      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.