Skip to main content

​
Overview

Selection option formulas let you compute dropdown options dynamically at runtime instead of defining a static list. When a user opens a document, the formula evaluates for each data object and populates the dropdown with context-aware options. When referenced attributes change, the formula re-evaluates automatically and the dropdown updates in real time. Common use cases:
  • Load options from an external reference system via service bridges
  • Filter options based on sibling attribute values (e.g., show subcategories for the selected category)
  • Compute options based on document context

​
Configuration

Two properties on a taxon enable formula-driven options: 
- name: department
  label: Department
  taxonType: SELECTION
  useSelectionOptionFormula: true
  selectionOptionFormula: |
    serviceBridgeCall("myorg/reference-data", "list-departments", {
      region: getAttribute("region")
    })

​
Properties

​
useSelectionOptionFormula
boolean
default:"false"
When true, the formula is used instead of the static selectionOptions list to populate the dropdown.
​
selectionOptionFormula
string
JavaScript expression evaluated by the GoJA runtime. Must return an array of options (see Return Format below).
You can define both static selectionOptions and a selectionOptionFormula on the same taxon. The formula takes precedence when useSelectionOptionFormula is true. This is useful for having a fallback list during development.

​
Return Format

The formula must return an array. Two formats are accepted: Object format (recommended): 
[
  { label: "Engineering", value: "ENG" },
  { label: "Marketing", value: "MKT" },
  { label: "Human Resources", value: "HR" }
]
String format (simple): 
["Engineering", "Marketing", "Human Resources"]
When using string format, both label and value are set to the string. Returning null or an empty array [] clears the dropdown options. The distinction is preserved: null means “no data available” while [] means “explicitly empty list.”

​
How It Works

Key points:
  • Options are computed and persisted on the DataObject (not the attribute) — they survive page reloads
  • Change detection uses canonical JSON comparison (sorted keys) to avoid unnecessary updates
  • During initial load, events are suppressed to prevent a flood — the UI reads options from the WASM layer directly
  • After initial load, real-time changes emit selectionOptions:computed events that update the UI reactively

​
Referencing Sibling Attributes

Formulas can read the current data object’s attribute values to parameterize API calls: 
serviceBridgeCall("myorg/reference-data", "get-subcategories", {
  category: getAttribute("category"),
  region: getAttribute("region"),
  active: true
})
When any referenced attribute changes, the formula automatically re-evaluates.

​
Service Bridge Integration

Most selection option formulas call a service bridge to fetch options from an external system: 
- name: subcategory
  label: Subcategory
  taxonType: SELECTION
  useSelectionOptionFormula: true
  selectionOptionFormula: |
    serviceBridgeCall("myorg/reference-data", "get-subcategories", {
      category: getAttribute("category"),
      active: true
    })
The serviceBridgeCall() function is a convenience wrapper available in formula contexts. For the full service bridge API, see Calling Service Bridges from Scripts.

​
Grid Child Formulas

When a SELECTION taxon is a child of a group (grid row), the formula evaluates per data object instance. Each row can have different dropdown options based on its own attribute values: 
- name: line_items
  label: Line Items
  group: true
  children:
    - name: country
      label: Country
      taxonType: STRING

    - name: region
      label: Region
      taxonType: SELECTION
      useSelectionOptionFormula: true
      selectionOptionFormula: |
        serviceBridgeCall("myorg/geo-data", "regions-by-country", {
          country: getAttribute("country")
        })
In this example, each line item row gets its own region dropdown based on its own country value.

​
Examples

Fetch a static reference list from an external system on document open.
- name: currency
  label: Currency
  taxonType: SELECTION
  useSelectionOptionFormula: true
  selectionOptionFormula: |
    serviceBridgeCall("myorg/reference-data", "get-currencies", {})
Filter team members based on a selected department. When the user changes the department, the contact dropdown updates automatically.
- name: team_lead
  label: Team Lead
  taxonType: SELECTION
  useSelectionOptionFormula: true
  selectionOptionFormula: |
    serviceBridgeCall("myorg/directory", "get-team-members", {
      departmentId: getAttribute("department_id")
    })
Use multiple attributes as dependencies and provide a fallback when the external call returns nothing.
- name: priority_level
  label: Priority Level
  taxonType: SELECTION
  useSelectionOptionFormula: true
  selectionOptionFormula: |
    var amount = getAttribute("total_amount");
    var region = getAttribute("region");
    if (!amount || !region) return [];
    return serviceBridgeCall("myorg/rules-engine", "get-priority-levels", {
      amount: amount,
      region: region
    }) || [{ label: "Standard", value: "STD" }];

​
Troubleshooting

Empty dropdownCheck that the service bridge is configured and the endpoint returns data. Use log("debug", ...) in script steps to test the bridge response.
Options don’t updateVerify that useSelectionOptionFormula is true. Check that the attribute names in getAttribute() match the taxon names exactly.
Timeout errorsSelection option formulas have a 2-second timeout. If your external API is slow, consider caching results in the service bridge configuration.
Stale options after page reloadOptions are persisted on the DataObject. If the external system’s data changed, trigger a recalculation by editing one of the dependent attributes.