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.
-
Create a form that includes a Single Select field called Country.
-
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:
-
Navigate to the Control Panel → Configuration → System Settings.
-
Click Data Providers (under Content & Data).
-
Check the Access Local Network checkbox.
-
Click Save when finished.
Adding a Basic REST Data Provider
To add a Countries of the World data provider:
-
Open the Product Menu () then click the compass icon () on the Site Administration menu.
-
Select the site where the form is to be created.
-
Click Content & Data → Forms.
-
Click the Data Providers tab.
-
Click the Add button () and add a REST Data Provider.
-
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
-
Click Save when finished.
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:
-
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 Overview.
- Name:
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 Autofill rule that sends the value of a text field into the data provider as input. See the Autofill 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:
-
Navigate to the Site Administration → Content & Data → Forms.
-
Click the Data Providers tab.
-
Click the Actions button (), then Permissions next to the data provider.
-
Grant the necessary permissions.
-
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:
-
Click Content & Data → Forms.
-
Drag a Select from List field onto the form.
-
Select From Data Provider from the Create List dropdown menu.
-
Select Countries of the World from the Choose a Data Provider dropdown menu.
-
Select Country Name from the Choose an Output Parameter dropdown menu.
-
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:
- Navigate to the Control Panel → System → Server Administration.
- Click the Log Levels tab.
- 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. - 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.