Skip to main content
An automated picklist sources its options from the approved records of another taxonomy instead of a hand-authored list. As records are approved in the source taxonomy, they become selectable options here automatically, with no governance-model change. With one level it is a plain dropdown. With two or more levels it becomes a set of cascading dropdowns.

​
When to use it

  • The valid values for a dropdown already exist as records in another taxonomy (clients, campaigns, products, assets).
  • You want the option list to grow as that taxonomy grows, without an admin adding each value by hand.
  • You want a cascade (parent then child) whose levels are driven by fields on those records, not by a hand-linked static hierarchy.
Do not use an automated picklist when the options are a fixed vocabulary the admin owns. Use a static picklist instead. Submitters cannot propose new values on an automated picklist; new options only appear when records are approved in the source taxonomy.

​
How it works

An automated picklist has type: automated and carries no options of its own. Instead it names a source taxonomy with source_taxonomy_id, then describes its dropdown levels in settings. The shape that matters is settings.levels: an ordered, root-first array. Each entry names a field on the source taxonomy.
  • levels[0] is the root dropdown. Its options are the distinct values of that field across the source taxonomy’s approved records.
  • Each later level narrows by every selection above it. levels[1] only offers values whose records also match the level-0 selection, and so on down the chain. This is what produces cascading dropdowns.
  • A single-level automated picklist is just a plain dropdown.
When a submitter opens a form with a dropdown on an automated picklist, the option list is built from the source taxonomy’s records:
  1. Every record in the source taxonomy is considered, except records whose status is deleted.
  2. For a given level, the value of that level’s source_field_id becomes the option’s code.
  3. If that level sets label_field_id, its value is the display label. Otherwise the code is shown as its own label.
  4. Values are de-duplicated, so a value shared by many records appears once.
  5. Any settings.additional_fields are carried along on the chosen option as read-only context from its source record (useful for reporting on the submission).
Cascading levels connect to the form the same way a hierarchical static picklist does: the child dropdown field sets depends_on to the parent field, and each child option carries an ancestor_path of the codes selected above it, so the child only offers options that match. The difference is only the source: the options come from records rather than a linked list.

​
Settings reference

SettingRequiredDefaultDescription
idYesNoneStable picklist identifier.
nameYesNoneHuman-readable name.
typeYesautomatedAlways the literal string automated.
source_taxonomy_idYesNoneThe taxonomy whose approved records supply the options. It cannot be the same taxonomy that contains the field using this picklist.
settings.levelsYes (at least one)NoneOrdered, root-first array of cascade levels. One level is a plain dropdown. Two or more create cascading dropdowns.
settings.levels[].source_field_idYes on each levelNoneThe source-taxonomy field this level renders. The distinct values of this field become the level’s option codes.
settings.levels[].label_field_idNoNoneA source-taxonomy field whose value is shown as this level’s label. When omitted, the code is used as the label.
settings.additional_fieldsNo[]Source-taxonomy field IDs carried onto the selected option as read-only metadata from its record.
An automated picklist has no options array, no parent_id, and no allow_additions.
Cascading is configured with settings.levels, not with additional_fields. additional_fields only carries extra display values; it never narrows the list.

​
Worked example

Suppose a Clients taxonomy holds one record per client, with a client_name field and a region field. You want campaigns to pick a region first, then a client in that region, both sourced live from Clients. Two levels produce that cascade: 
- id: client_picklist
  name: Clients
  type: automated
  source_taxonomy_id: clients_taxonomy
  settings:
    levels:
      - { source_field_id: region }                              # level 0, the root
      - { source_field_id: client_name, label_field_id: client_name }  # level 1, narrowed by region
    additional_fields: [industry]
The two dropdown fields on the Campaigns taxonomy wire the cascade: 
- name: client_region
  type: dropdown
  settings: { picklist_id: client_picklist }

- name: client
  type: dropdown
  settings:
    picklist_id: client_picklist
    depends_on: client_region
    source_field_id: client_name
The client_region dropdown offers the distinct region values across all approved Clients records. Once the submitter picks a region, the client dropdown offers only the client_name values from clients in that region. The chosen client’s industry rides along on the submission for reporting. For a plain, non-cascading dropdown, give the picklist a single level and drop depends_on and source_field_id from the field. When the Clients taxonomy gains a new approved record, it appears in these dropdowns the next time the form is opened. No governance-model change is needed.

​
Gotchas

  • Cascading uses settings.levels. One level is a plain dropdown; two or more cascade. A child field renders a specific level with its own source_field_id and points at the level above with depends_on. There is no parent_id on an automated picklist.
  • Deleted source records drop out; other statuses stay. The option list includes every source record except those whose status is deleted. To remove an option, the source record has to be deleted; other status changes leave it selectable.
  • Submitters cannot add options. allow_additions does not apply. A new value only appears once a record carrying it is approved in the source taxonomy. If submitters need to coin values inline, use a static picklist with allow_additions.
  • The source taxonomy cannot be the field’s own taxonomy. A taxonomy cannot use an automated picklist that sources from itself.
  • An automated picklist must not declare options. Its options come from records. A configuration with an options array is rejected.
  • A selected option keeps a snapshot of its source record. The chosen option carries the source record as it looked when the submission was made, so later edits to that record do not rewrite past submissions. New submissions read the current record.
  • Renaming a level’s source_field_id field changes its codes. Codes are the values of the level’s field. Repurposing or renaming that field on the source taxonomy changes what new codes look like and can leave older records with codes that no longer match any current source value. Validate on publish; a deleted level field is caught there, but subtler changes are not.