Skip to content

Populate a Dropdown with Data from a REST API

Scenario

Use this walkthrough when a form dropdown should load its selectable values from an external REST service instead of a static list.

Prerequisites

  • a process definition with a form you can edit
  • permission to create or edit a script module
  • access from the Emakin runtime to the target REST service

Steps

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.
  2. Name it according to the integration you are working with. In this example, the module is named External.

Script module editor with the module used to call the external REST service.

  1. Open the module and define a function named GetCountries to call the external service.

Use a function like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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;

This example:

  • calls https://restcountries.com/v3.1/all
  • requests only the cca3 and name fields
  • returns the JSON response to the caller
  • exports the function so it can be reused elsewhere in the process definition

Save the script module before continuing.

Create the Dropdown

  1. Open the form you want to edit.
  2. Add a new dropdown widget.
  3. Give it a meaningful label such as Select a Country.

Configure the Data Source

The note below reflects the UI behavior documented for version 8.5 and may differ in newer versions.

If ScriptDataSource is not available directly in the dropdown designer, edit the widget XML manually.

Dropdown XML editor used to add a ScriptDataSource manually.

  1. Open the dropdown widget.
  2. Select XML to edit the widget markup.
  3. Insert the following snippet under <DataSources>:
1
2
3
4
5
6
7
8
<ScriptDataSource TextFormat="{{name.common}}" ValueFormat="{{cca3}}" Enabled="True">
    <Mappings/>
    <Source>
        <Content><![CDATA[
                return External.GetCountriesAsync();
                ]]></Content>
    </Source>
</ScriptDataSource>

In this example:

  • TextFormat displays the country name
  • ValueFormat stores the country code
  • the <Content> block calls External.GetCountriesAsync()

Info

Even though the function in your script module is named GetCountries, when making a client-side call from the form, you must append Async to the function name (GetCountriesAsync). This is required to ensure that the data is fetched asynchronously in the client-side environment.

Save the XML after making the change.

Test the Form

  1. Save and deploy the process definition.
  2. Open the initiating task.
  3. Confirm the dropdown is populated with values from the REST service.
  4. Select one option and inspect the resulting XML.

The stored value should follow this pattern:

1
2
3
4
5
6
7
8
<Data>
    <ApplicationInfo>
        <Country>
            <Value>CHE</Value>
            <Text>Switzerland</Text>
        </Country>
    </ApplicationInfo>
</Data>

Result

The dropdown now loads its selectable values from an external REST API through a reusable script module.

Troubleshooting

If the dropdown does not populate as expected:

  • Check that GetCountries is defined and exported from the script module.
  • Make sure the form calls GetCountriesAsync, not GetCountries.
  • Confirm that the API endpoint is reachable from the Emakin runtime.
  • Verify that the service returns data in the expected structure.
  • Review the ScriptDataSource XML and make sure the TextFormat and ValueFormat match the response payload.

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 Populate dropdown from REST.xml into your environment and test the dropdown functionality with the data from the REST API.