Documentation

Using the REST Data Provider to Populate Form Options

Select from List fields can hold many options. Those options can be automatically supplied by using the JSON web services registered in Liferay DXP or any other third party REST web service. To learn more about data providers in general, see Data Providers Overview. To apply a REST data provider to a form, you’ll learn how to invoke a JSON web service, configure the data provider to pull from it, and use the data provider in a form.

Prerequisites

A common need is to populate a Select field with a list of options: for example, a user’s Country is needed when collecting personal information on a form.

  1. Create a form that includes a Single Select field called Country.

  2. Next, use the get-countries JSON web service (there are two—use either one).

    Search for the get-countries web service.

    • Click Invoke.

The list of countries are now ready for use.

Enabling Access to Data on the Local Network

By default, users cannot configure data providers to use URLs on the local network. This is a good default for security in a production environment, but makes testing more difficult.

To enable local network access from data providers:

  1. Navigate to the Control PanelConfigurationSystem Settings.

  2. Click Data Providers (under Content & Data).

  3. Check the Access Local Network checkbox.

    Grant access to the local network.

  4. Click Save when finished.

Adding a Basic REST Data Provider

To add a Countries of the World data provider:

  1. Open the Product Menu (Product Menu) then click the compass icon (Compass) on the Site Administration menu.

  2. Select the site where the form is to be created.

  3. Click Content & DataForms.

  4. Click the Data Providers tab.

    Navigate to the data providers tab.

  5. Click the Add button (Add) and add a REST Data Provider.

  6. Enter this data:

    • Name: Countries of the World

    • URL: http://localhost:8080/api/jsonws/country/get-countries/

    • User Name: adminuser@liferay.com

    • Password: adminuserpass

    • Timeout: 1000

    • Outputs Label: Country Name

    • Outputs Path: $..nameCurrentValue

    • Outputs Type: List

    Enter the values.

  7. Click Save when finished.

Note

$.. before nameCurrentValue is the JsonPath syntax to navigate the JSON data structure and specify the path to the output. Learn more about JsonPath and here.

Using Inputs as Filters for the REST Data Provider

The above example is simple which uses only an Output to populate a Select from List field. Often the response from the REST provider must be filtered before display in the Select from List field. For this, a Data Provider Input field is required.

For example, to apply a region (for example, Americas, Europe, or Oceania) filter for the countries of the world:

  1. Enter this data:

    • Name: restcountries

    • URL: https://restcountries.eu/rest/v2/region/{region}?fields=name(using a different REST provider)

    • Input Label: Region

    • Parameter: Region

    • Input Type: Text

    • Outputs Label: Countries of the World with Regions

    • Outputs Path: $..name

    • Output Type: List

    To understand more about these values, see Data Providers Overview.

Granting Data Provider Permissions

Depending on whether the user is required to be authenticated before filling the form, users may have to grant additional permissions to the Data Provider. For example, if Guests are to fill out the form, they need the View permission, or else they will not be able to see the options provided by the data provider.

To configure the data provider’s permissions:

  1. Navigate to the Site AdministrationContent & DataForms.

  2. Click the Data Providers tab.

  3. Click the Actions button (Actions), then Permissions next to the data provider.

    Grant Guest View Permissions.

  4. Grant the necessary permissions.

  5. Click Save when finished.

Using a Data Provider in a Select Field

Once the Data Provider is configured, use it to populate a Select from List field:

  1. Click Content & DataForms.

  2. Drag a Select from List field onto the form.

  3. Select From Data Provider from the Create List dropdown menu.

  4. Select Countries of the World from the Choose a Data Provider dropdown menu.

  5. Select Country Name from the Choose an Output Parameter dropdown menu.

    Configure the Data Provider values on the Select from List field.

  6. Click Save Form when finished.

The Data Provider now populates a select field for any users accessing the form with the correct permissions.

Form users select an option form the list populated by the Data Provider.

Troubleshooting Data Provider Errors

To uncover errors arising from Data Provider failures, configure log levels for these services:

  1. Navigate to the Control PanelSystemServer Administration.

  2. Click the Log Levels tab.

  3. Add the logging category com.liferay.dynamic.data.mapping.data.provider.internal.DDMDataProviderInvokerImpl and configure it to log at the WARN level. Save when finished.

  4. Add the logging category com.liferay.dynamic.data.mapping.form.field.type.internal.DDMFormFieldOptionsFactoryImpl and configure it to log at the WARN level. Save when finished.

The console now sends warning messages whenever there are errors in the Data Provider.