Using the REST Data Provider to Populate Form Options

Select from List fields can hold many options. Those options can be supplied automatically 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. To apply a REST data provider to a form, 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).

   • If you’re running Liferay locally, navigate to http://localhost:8080/api/jsonws.
   • Search for “get-countries”.

   

   • 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 Panel → Configuration → System Settings.

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

3. Check the Access Local Network checkbox.

   

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 () then click the compass icon () on the Site Administration menu.

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

3. Click Content & Data → Forms.

4. Click the Data Providers tab.

   

5. Click 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: [e-mail]
   • Password: adminuserpass
   • Timeout: 1000
   • Outputs Label: Country Name
   • Outputs Path: $..nameCurrentValue
   • Outputs Type: List

   

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 uses only a single Output to populate a Select from List field. To filter the response from the REST provider, use the Input field.

This example uses a different data provider and applies a region (for example, Americas, Europe, or Oceania) filter for the countries of the world:

1. Enter this data:

   • Name: restcountries
   • URL: https://restcountries.com/v3.1/region/{region}?fields=name
   • Input Parameter: region
   • Input Type: Text
   • Input Label: Region
   • Output Path: $..name.common
   • Output Type: List
   • Output Label: Country Name

   To understand more about these values, see Data Providers.

Because this example uses an input parameter, you must provide the input to the data provider for the API call to resolve properly. You can set up an Auto-fill rule that sends the value of a text field into the data provider as input. See the Auto-fill Rule documentation for an example.

Granting Data Provider Permissions

Users must have view permission on a data provider to see the options it provides. For example, if Guests must fill out a form, grant them the view permission.

To configure the data provider’s permissions:

1. Navigate to the Site Administration → Content & Data → Forms.

2. Click the Data Providers tab.

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

   

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 & Data → Forms.

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

3. Select From Data Provider from the Create List drop-down menu.

4. Select Countries of the World from the Choose a Data Provider drop-down menu.

5. Select Country Name from the Choose an Output Parameter drop-down menu.

   

6. Click Save Form when finished.

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

Troubleshooting Data Provider Errors

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

1. Navigate to the Control Panel → System → Server 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.

Related Topics

• Data Providers
• Using the Auto-fill Rule