Populate a Dropdown with Data from a REST API

In this example, we'll guide you through the process of populating a dropdown field with dynamic data fetched from a REST API. This is useful when you need to pull data from external systems or services and provide it as selectable options within your form.

Step-by-Step Guide

1. Define a Script Module

When making a client-side service call, such as calling it from a form, defining a script module is mandatory. This approach helps manage your API integrations in a more organised and reusable manner.

1. Create a Script Module:

   • Name the module according to the integration you are working with. For example, if you're integrating with an ERP system, you might name the module such as ERPNext or SAP. In this example, we'll name the module External since we're fetching data from an external service.

Open

2. Open the Module: After creating the module, open it to write your function.

3. Write the Function to Retrieve Countries:

   • In the script module, define a function named GetCountries. This function will handle the API call to retrieve a list of countries.

   Here's how the function should look:

   function GetCountries() { var client, request, response; client = $Rest.Create('https://restcountries.com/v3.1/all'); request = client.Request(); request.AddHeader('Content-Type', 'application/json'); request.AddHeader('Accept', '*/*'); request.AddParameter('fields', 'cca3,name') try { response = request.Get().ToJson(); } catch (err) { throw err; } return response; } exports.GetCountries = GetCountries;

   Explanation:

   • API URL: We're using the https://restcountries.com/v3.1/all endpoint to retrieve a list of countries.

   • Headers: We specify the content type as application/json and accept any response format with */*.

   • Parameters: We're requesting only the cca3 (country code) and name fields to minimise the data retrieved.

   • Error Handling: The function includes a try-catch block to handle any errors during the API call.

   • Exporting: Finally, the GetCountries function is exported so it can be called from other parts of the platform.

4. Save the Script Module: Ensure you save the module after writing the function.

2. Create a New Dropdown Field in Your Form

With the script module in place, you can now move on to creating the dropdown field that will be populated with the data retrieved by the GetCountries function.

1. Add a new dropdown field: Click the Add New button and select the the dropdown component.

2. Set the dropdown properties: Give it a meaningful label (e.g., "Select a Country").

3. Configure the Data Source by Adding a ScriptDataSource Manually

Currently, in version 8.5, the UI does not allow you to add a ScriptDataSource directly through the dropdown's data source settings. Instead, you'll need to manually edit the XML configuration for the dropdown field.

Open

Setting the Dropdown DataSource

1. Access the XML Configuration:

   • Click on the dropdown field and select the XML button to view and edit the XML configuration.

2. Add the ScriptDataSource:

   • Insert the following XML snippet under the <DataSources> section to manually configure the data source:

   <ScriptDataSource TextFormat="{{name.common}}" ValueFormat="{{cca3}}" Enabled="True"> <Mappings/> <Source> <Content><![CDATA[ return External.GetCountriesAsync(); ]]></Content> </Source> </ScriptDataSource>

   Explanation:

   • TextFormat: Specifies how the country name will be displayed in the dropdown.

   • ValueFormat: Specifies the country code to be used as the value for each dropdown option.

   • Content: Calls the GetCountriesAsync function from the External module to retrieve the data asynchronously.

3. Save the XML: After making the changes, save the XML configuration.

4. Deploy and Test the Form

After configuring the dropdown, save your process and click on the initiating task of the form.

1. Open the form: Ensure the dropdown is populated with the country data fetched from the API.

2. Select a country: Verify that the correct value is captured upon selection.

3. Verify the form data: Check if the Value and Text fields in the XML are set correctly, as shown below:

5. Troubleshooting

If the dropdown does not populate as expected:

• Check the Script Module: Ensure the GetCountries function is correctly defined and exported.

• Make Sure You Added "Async": Double-check that you've appended Async to the method name (GetCountriesAsync) when calling the function from the client-side. This is crucial for making the asynchronous service call work properly.

• Inspect the API call: Confirm that the API endpoint is accessible and returning the expected data.

• Ensure Data Is Returning from the Service: Make sure that the service you are calling is actually returning data. If the service is down or not returning data as expected, the dropdown will not be populated.

• Review the XML Configuration: Double-check the ScriptDataSource configuration in the XML to ensure it's correctly set up.

Download and Try it Yourself

To help you get started quickly, we’ve provided a downloadable definition of the process described in this guide. You can import this into your environment and test the dropdown functionality with the data from the REST API.