Info: This article is work in progress and subject to change.
An external data source is a named connection to data outside Assets that the Workflow Assistant can use to populate fields. Where a Dropdown’s values list and a Tags suggested list are static — typed in by the admin and frozen at publish — an external data source draws live from a system you control.
Typical uses include a product catalogue, a regional taxonomy, a controlled vocabulary, or any list that lives in another system and that you want users to pick from inside the panel.
Note: External data sources is a special feature that can only be configured by members of the WoodWing Connect Applications team. We hope to bring this feature to be configurable by partners and admin users late 2026
This article covers what external data sources are, how to define one in the Configurator, and how to wire a Field to it.
Where external data sources live
External Data Sources are a separate area in the Configurator, reached from the top-nav. They are not components on a panel — they are configuration objects you define once and then point Fields at.
The lifecycle is:
- Define the source in the External Data Sources area
- Reference it from one or more Fields (the External data source field type, covered in 05a — Fields reference)
- Maintain the source as the underlying data evolves
The same source can be used by any number of Fields across any number of panels, including across tabs and configurations within the same customer.
Defining a source
Open the External Data Sources area and click Add data source (or the equivalent control). Fill in the form:
| Setting | Purpose |
|---|---|
| Name | The identifier you reference from Fields. Pick a clear, short name — it appears in dropdowns when configuring fields |
| Description | A sentence explaining what the source is and where its data comes from. Helps the next admin who configures a field |
| Source URL | The endpoint that returns the data. The Workflow Assistant fetches from this URL when a user opens a Field that points at the source |
| Source format | The shape of the response. Tree for hierarchical data; flat list for searchable dropdowns |
| Authentication | Optional credentials, if the source requires them |
| Refresh policy | How often the Workflow Assistant should re-fetch the source. Options vary by version |
Note: External data sources are fetched live by the Workflow Assistant when needed. A slow source slows down panel rendering. If you depend on a source whose response time is unreliable, consider mirroring it to a faster endpoint maintained by your team.
Connecting a Field to a source
Once a source is defined, point a Field at it.
Step 1. Add a Field of type External data source to a row in your panel.
Step 2. In the options panel:
- Display name — the field label
- Field name — the Assets metadata field that will store the user’s pick
- Data source — pick the source you defined
-
Display method —
TreeorDropdown - Display keys — the source-side fields that will be used as labels for the user
- Default mapping field — the source-side field whose value is written to the Assets metadata when the user picks an entry
- Multi-select — when on, the user can pick more than one entry
- Read only — when on, the field is non-editable but renders the current value
- Start minimised — when on, the field renders collapsed when the user opens the panel
Step 3. Configure the visibility checklist (Applies to) like any Field.
Step 4. Save the panel and verify in a test-user browser window. The field should fetch from the source on first open and display the entries according to your Display method choice.
Display methods
| Display method | When to use it |
|---|---|
| Tree | Hierarchical sources — categories with sub-categories, taxonomies, file-tree-like data. The user can expand and collapse branches |
| Dropdown | Flat or large sources where search beats browsing. The user types into a search box and the dropdown filters in real time |
Use the Tree display only when the source genuinely has a hierarchy worth navigating. For long flat lists, the Dropdown’s search is faster.
Display keys versus default mapping field
The most common source of confusion in external-data-source configuration is the difference between Display keys and Default mapping field.
| Setting | Used for | Example |
|---|---|---|
| Display keys | What the user sees in the dropdown or tree. Multiple display keys are concatenated to form the visible label |
name and code, displayed as Marketing — MKT
|
| Default mapping field | The value written to Assets metadata when the user picks an entry. A single key |
code, so MKT is what is stored |
Two different keys for two different purposes: human-readable display, machine-friendly storage.
Tip: Always pick a stable, unique field for the Default mapping field. Display labels can change over time without breaking existing data; the stored value cannot. A good rule: store IDs, not names.
Failure modes and what to do
| Symptom | Likely cause | What to do |
|---|---|---|
| The field shows “Loading…” indefinitely | Source URL is unreachable or slow | Test the URL directly in a browser. Consider mirroring or caching |
| The field shows “No entries” but you expect entries | Source returned an empty response, or response shape does not match expected format | Check the source format — Tree expects a particular shape, Dropdown expects another. See your version’s reference for the expected response schema |
| The user picks an entry but the Assets metadata is not updated | The Default mapping field is wrong, or the Field is set to Read only | Verify the mapping field exists in the source response, and that the Field’s Read only is off |
| The dropdown shows entries with strange labels | The Display keys are picking the wrong source-side fields | Adjust the Display keys to point at the human-readable fields |
| Performance is slow when opening the panel | The source is fetched live and is slow | Move the source behind a faster mirror, or reduce the refresh policy |
When not to use an external data source
External data sources are powerful but are not the right tool for every list. Two cases where simpler tools win:
- A small fixed list of values — use a Dropdown field with a Values list
- An open-ended user-driven list — use a Tags field
Use an external data source when the list lives in another system, changes more often than panel publishes, or is too large to maintain by hand.
Cross-references
- 05a — Fields reference — for the External-data-source field type and its options
- 02b — Component types — Field is one of three component types
- 04a — A design methodology — including the principle of starting from the user’s job before reaching for any data tool
Revisions
- 8 May 2026: First publication of the manual
Comments
0 comments