Populating Drop Down Options with JavaScript

The JavaScript Code Source field type gives users a drop down list whose options are produced by one of your saved JavaScript functions. Each time the field needs its options, ProcessPlan runs your function and displays the list it returns. That means the choices can come from a calculation, an external system, or anything else your code can reach.

Use it when a static Drop Down List isn’t enough: options that change over time, options that depend on the value of another field, or options pulled from an outside service.

Create the function first

JavaScript functions are created and managed under Administration > Integrations > Code / Functions - see Creating JavaScript Functions. To serve as an option source, your function must return an array of objects, each with a text and a value property:

async function execute(event, helpers) {
  // event contains the parameter values configured on the field
  return [
    { text: 'Small', value: 'S' },
    { text: 'Medium', value: 'M' },
    { text: 'Large', value: 'L' },
  ];
}

• text - What the user sees in the list. Display text is limited to 100 characters

• value - Stored along with the text when the user selects that option

Tip

Use the Run Test button on the function’s page to confirm it returns the list you expect before connecting it to a field.

Set up the field

1. Open the desired template by clicking Administration > Processes > Template Diagrams > The card of the process you want to edit

2. Click the Process field icon in the menu in the top right > New Process Field

3. Give your field a name and select JavaScript Code Source as the field type

4. Expand the Javascript Code section and select your function under JavaScript Source Function

5. Each parameter defined on the function appears as its own input. Enter a value for each parameter, or leave it blank to use the default value defined on the function

6. Click the Save icon at the top of the panel

Making options depend on other fields

Parameter values can contain field tokens. Click the token button next to a Parameter Value input to insert the value of another process field, exactly as described in Field Tokens.

When a parameter references another field, the option list is rebuilt whenever that field’s value changes. This lets you create cascading drop downs: for example, a “Country” field feeds a parameter of the function behind a “City” field, so choosing a country reloads the city options.

Filtering options as the user types

For long lists, your function can return only the options that match what the user has typed so far. Add a parameter to your function (for example, search), and on the field set that parameter’s value to the Current Field Text token using the token button next to the parameter input.

Each time the user types in the drop down, ProcessPlan re-runs your function with the token replaced by the typed text, so your code can look up and return just the matching options:

async function execute(event, helpers) {
  const typed = typeof event.search === 'string' ? event.search : '';
  // Look up and return only the options that match `typed`
}

When the field first opens and nothing has been typed yet, the parameter arrives as empty text - return your default list in that case.

Good to know

• The function must finish within 35 seconds. If it fails or times out, the field simply shows no options; there is no separate static list to fall back on

• The options are fetched fresh each time the field loads them, so the list always reflects your function’s latest result

• These are the same saved functions used by the JavaScript Function action type, so one function can both populate options and power automated actions