RESTful service action

Use a RESTful web service to integrate your form with external applications.

Note 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. On the Web service list, select a web service for your action.

    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 reuse the base URL parameters by copying and pasting it in the base URL parameters of another restful services.

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

  8. On the Verb list, select the action to perform. (Default: GET)

    GET or DELETE

    Select GET to retrieve the data, and DELETE to delete the data, and perform the following steps.

    • Select the Type as XML or JSON. (Default: XML)

    • 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 custom header and click .

      2. For Value, select a dynamic variable or click and enter a static value.

      3. Click OK.

    • Select either of the following on the Response type list:

      • Select Variable(default) and 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.

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

        4. Click Add.

    POST or PUT

    Select POST to insert the data, and PUT to update the data, and perform the following steps:

    • Select the Type as XML or JSON. (Default: XML)

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

    • 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 custom header and click .

      2. For Value, select a dynamic variable or form control or click and enter a static value.

      3. Click OK.

    • Select either of the following on the Response type list:

      • Select Variable(default) and 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.

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

        4. Click Add.

  9. 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.)
  10. To display the Error code, select the global or form variable or form control, or provide a static value.
  11. Click Save.

    The newly created action is added to the table.

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