Documentation

Data Providers Overview

Data providers serve data that can be consumed by the Forms application. The REST Data Provider is included with the Forms application. With it, you can consume data from REST web services to autofill form fields.

One common example is using a REST Data Provider to populate a Select from List field’s options with a list of countries.

Registered JSON Web Services

Some data sources are from third party sources, such as the restcountries.com data provider. Liferay DXP also has its own registered web services. If you are running a local server, see http://localhost:8080/api/jsonws for a list. If populating a list of countries, you’ll find two get-countries JSON web services; either one works. Click Invoke to generate the results.

Warning

To test using Liferay’s web services with data providers in a local testing environment, you must enable local network access. See Enabling Access to Data on the Local Network.

The Result tab shows a list of countries using JSON syntax, like this record for Afghanistan:

[
  {
    "a2": "AF",
    "a3": "AFG",
    "countryId": "20",
    "idd": "093",
    "mvccVersion": "0",
    "name": "afghanistan",
    "nameCurrentValue": "Afghanistan",
    "number": "4"
  },
    ...

Choose the selectable field from the web service. For get-countries it’s most likely nameCurrentValue, because it contains the full, properly capitalized name of the country.

On the URL Example tab, find the URL to use when creating the data provider. It’s the same as the one generated for accessing the get-countries JSON web service. Users can find the URL for any registered JSON web service using this same procedure.

The URL Example tab displays the corresponding the JSON web service.

Data Provider Configuration Reference

You can configure data providers from the Forms application by going to Site AdministrationContent & DataForms. Click the Data Provider tab then the (Add icon) icon to begin. There are several fields to fill out when configuring a data provider.

This data service returns countries.

URL

Enter the URL of an internal or external REST service endpoint. The example above shows the REST service at https://restcountries.com/ which contains an endpoint to find countries by region:

https://restcountries.com/rest/v2/region/{region}

Data provider URLs can take two parameter types: path parameters and query parameters.

Path parameters are part of the URL calling the REST web service and are added using the pattern https://service-url.com/service/{path_parameter_name}:

For example, the restcountries.com service’s region endpoint’s path parameter is {region}. Path parameters are mandatory parts of the URL, so make sure you specify an Input (see below) with a Parameter field value matching the path parameter from the URL.

Query parameters are complementary parts of the URL that filter the output of the service call, following the pattern ?query_parameter=query_parameter_value:

https://restcountries.com/rest/v2/all?fields=capital

Unlike path parameters, query parameters are optional.

User Name and Password

Enter the credentials used to authenticate to the REST Web Service, if necessary.

Cache data on the first request

If the data is cached, a second load of the select list field is much faster, since a second call to the REST service provider is unnecessary.

Timeout

Enter the time (in ms) to wait for a response to the REST call before aborting the request.

Inputs

Configure path or query parameters from the REST service to filter the REST service’s response. Specify the Label, Parameter, and Type (Text or Number), and choose whether the input is required to use the data provider.

Outputs

The Outputs are the Parameters to display in Select from List or Text fields with autocomplete enabled. You can add multiple Outputs. Outputs can be filtered by inputs (see above) but can also be displayed without configuring input filtering. Specify the Label, Path, and Type (Text, Number, or List).

You can add multiple Inputs. To provide a way to specify the input value, use an Autofill Form Rule. Users enter input into one field, and their input is sent to the REST service. The REST service’s response data is filtered by the input parameter.

The Output Path field is specified in JsonPath syntax, so it must always start with a $. The type of data returned by the Path must match the type you choose in the Type field. Using the restcountries.com service, specify the name field as an Output by entering enter $..name in the Path field. If you have a more complex JsonPath expression to construct (for example, you need the names of all countries with a population over 100 million—$..[?(@.population>100000000)].name with the restcountries.com service), consider using a JsonPath evaluator, like this one or this one.

Tip

To display one value but persist another in the database, enter both into the Paths field, separated by a semicolon: $..name;$..numericCode

If using the restcountries.com data provider, the name of the country appears for the User, while the numeric country code is stored in the database.