› 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 an Open API definition and non-Open API 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 them into the base URL parameters of another restful service.

      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 do the following:
  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. Click Add.

    The newly created action is added to the table.

  10. 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 the Response status are handled as configured.

Configure RESTful service action to retrieve data

You can configure a RESTful service action to retrieve the data.

  1. On the Verb list, select GET to retrieve the data.
  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 handle the response from a web service, based on the status code that is returned by a RESTful service, do the following for Response:
    1. Click .

      The Response dialog box is displayed.

    2. Specify a range of the status code in HTTP Status Code From and HTTP Status Code To.

      • 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 response for status code in the range mentioned.

    3. In the Description box, enter a description such as range.
    4. To specify whether the response received from the RESTful service should be stored in a Form variable or Form control or Global variable, select either of the following on the Response type list.
      Variable (default) Map the entire output to a single variable in the form of Form variable or Form control or Global 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.

      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.

        • If the response is XML, use xPath.

        • If the response is JSON, use JSONPath.

      3. On the Value list, select a Form variable or Form control or Global variable.

      4. Click Add.

  5. To access the response headers that are returned by a RESTful service and to define a list of response headers as key or value pairs, do the following for Response header:
    1. Click .
    2. Enter a Header Name.
    3. On the Value list, select a Form variable or Form control or Global variable to hold the return value.
    4. Click Add.
    5. To display the Status code, select the Global or Form variable or Form control. The action will be completed even if an error is found, and the selected status code is displayed at runtime. This helps a user handle errors manually.

Configure RESTful service action to insert data

You can configure a RESTful service action to insert the data.

  1. On the Verb list, select POST to insert 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)

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

  3. 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 handle the response from a web service, based on the status code that is returned by a RESTful service, do the following for Response:
    1. Click .

      The Response dialog box is displayed.

    2. Specify a range of the status code in HTTP Status Code From and HTTP Status Code To.

      • 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 response for status code in the range mentioned.

    3. In the Description box, enter a description such as range.
    4. To specify whether the response received from the RESTful service should be stored in a Form variable or Form control or Global variable, select either of the following on the Response type list.
      Variable (default) Map the entire output to a single variable in the form of Form variable or Form control or Global 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.

      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.

        • If the response is XML, use xPath.

        • If the response is JSON, use JSONPath.

      3. On the Value list, select a Form variable or Form control or Global variable.

      4. Click Add.

  5. To access the response headers that are returned by a RESTful service and to define a list of response headers as key or value pairs, do the following for Response header:
    1. Click .
    2. Enter a Header Name.
    3. On the Value list, select a Form variable or Form control or Global variable to hold the return value.
    4. Click Add.
    5. To display the Status code, select the Global or Form variable or Form control. The action will be completed even if an error is found, and the selected status code is displayed at runtime. This helps a user handle errors manually.

Configure RESTful service action to update data

You can configure a RESTful service action to update the data.

  1. On the Verb list, select PUT.
  2. From step 2, follow the same procedure as "Configure RESTful service action to insert data".

Configure RESTful service action to delete data

You can configure a RESTful service action to delete the data.

  1. On the Verb list, select DELETE.
  2. From step 2, follow the same procedure as "Configure RESTful service action to retrieve data".

See also: