› User interface › Forms › Form events and actions › Form actions › RESTful service action

RESTful service action

Use a RESTful web service to integrate your form with external applications. A RESTful web service can have Open API definition and non-OpenAPI REST services. You can use a REST service that has an Open API definition in your form so that you can see the methods/parameters and execute the service successfully.

TotalAgility only supports simple types of RESTful web services; therefore, they should not be used with complex data structures.

  1. On the form modeling bar, click Actions and click New.

    The New action dialog box is displayed.

  2. On the Type list, select RESTful service.
  3. Change the default Name (RESTfulService1) to something meaningful.
  4. Optional. Enter a Description for the action.
  5. Optional. Select Multilingual to configure a unique action for each language separately. See Configure multilingual actions.
  6. The Web service lists all REST service definitions that have an Open API definition and non-OpenAPI REST services. On the Web service list, do either of the following:

    Select the preconfigured RESTful web service reference for your action.

    1. 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.

      You can reuse the base URL parameters by copying and pasting it in the base URL parameters of another restful services.

      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.

    2. Right-click in the URL parameters rule editor and select a single variable (form or global) of type String, or form field, or dynamically define the URL as a combination of static value, variables, and form field.

      URL parameters are optional parameters of type String that influence the returned results.

    3. Configure a RESTful service action to retrieve, delete, insert or update data.

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

    1. The Configure link for the Parameters becomes available. Click Configure.

      The Configure RESTful service action displays the RESTful service details.

    2. The Base URL that is preconfigured in the Integration for the selected RESTful service appears.

    3. On the Class list, select a class.

      The methods available for the selected class appear on the Method list.

    4. Select a Method to display the parameters and the parameter types where you can map inline values/form control/variables (form or global) to the parameters.

    5. Click OK.
    6. Additionally, the custom headers that are defined in the RESTful service appear under Custom header.

  7. You can configure a RESTful service action to retrieve, delete, insert or update data. On the Verb list, select the action to perform. (Default: GET)

    • Configure RESTful service action to retrieve or delete data.

      1. On the Verb list, select GET to retrieve the data, or DELETE to delete the data (Default: GET)

      2. A request to get information returns the response in either JSON or XML format. To specify whether the response should be returned in XML or JSON format, select the Type as XML or JSON. (Default: XML)

      3. The custom headers are 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, double-click the row or select the custom header and click . Then select a dynamic variable or click and enter a static value and then click OK.

      4. To specify whether the response received from the RESTful service should be stored in a variable or as expression, select either of the following on the Response type list:

        Variable (default) Map the entire output to a single variable or form field by selecting a process or server variable or a form control on the Value list.

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

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

        When debugging a form 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.

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

        4. Click Add.

    • Configure RESTful service action to insert or update data.

      1. On the Verb list, select POST to insert the data, and PUT to update the data.

      2. Select the Type as XML or JSON to specify whether the response should be returned in XML or JSON format. (Default: XML)

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

      4. The custom headers are 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, double-click the row or select the custom header and click . Then select a dynamic variable or click and enter a static value and then click OK.

      5. To specify whether the response received from the RESTful service should be stored in a variable or as expression, select either of the following on the Response type list:

        Variable (default)

        Map the entire output to a single variable or form field by selecting a process or server variable or a form control on the Value list.

        If the return type is JSON, you can map one or more data object variables into the request property along with any static text and other variables. The request can accept multiple objects which are combined into a single request before being passed to the service.

        You can also map a data object variable as the response variable. When you execute the action, the content of the request is combined and passed to the RESTful service, and the response from the service is used to populate the variable based on the underlying model with the JSON returned.

        When debugging a form, you can view the values of data object variables.

        Expression

        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 or form control.

        4. Click Add.

  8. To allow a job to suspend if an error is found, select Stop on error. (Default: Clear, this means that the job will be completed even if an error occurs.)
  9. To display the Error code, select the global or form variable or form control, or provide a static value.
  10. Click Add.

    The newly created action is added to the table.

  11. Associate the action with the control to trigger this action. See Configure actions for form control events. Alternatively to call this action for a form event, associate the action with the form. See Associate an action with a form.

    When this action is triggered, the RESTful web service is executed and the output and status code are handled as configured.

See also: