> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terminus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Automated picklist

> A picklist whose options come live from the approved records of another taxonomy, with one or more levels that can cascade.

<Info>
  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.
</Info>

## 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.

<Warning>
  Do not use an automated picklist when the options are a fixed vocabulary the admin owns. Use a [static picklist](/reference/picklists/static) instead. Submitters cannot propose new values on an automated picklist; new options only appear when records are approved in the source taxonomy.
</Warning>

## 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](/reference/picklists/hierarchical) does: the child [dropdown field](/reference/fields/dropdown) 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

| Setting                             | Required           | Default     | Description                                                                                                                         |
| ----------------------------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                | Yes                | None        | Stable picklist identifier.                                                                                                         |
| `name`                              | Yes                | None        | Human-readable name.                                                                                                                |
| `type`                              | Yes                | `automated` | Always the literal string `automated`.                                                                                              |
| `source_taxonomy_id`                | Yes                | None        | The taxonomy whose approved records supply the options. It cannot be the same taxonomy that contains the field using this picklist. |
| `settings.levels`                   | Yes (at least one) | None        | Ordered, root-first array of cascade levels. One level is a plain dropdown. Two or more create cascading dropdowns.                 |
| `settings.levels[].source_field_id` | Yes on each level  | None        | The source-taxonomy field this level renders. The distinct values of this field become the level's option codes.                    |
| `settings.levels[].label_field_id`  | No                 | None        | A source-taxonomy field whose value is shown as this level's label. When omitted, the code is used as the label.                    |
| `settings.additional_fields`        | No                 | `[]`        | 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`.

<Note>
  Cascading is configured with `settings.levels`, not with `additional_fields`. `additional_fields` only carries extra display values; it never narrows the list.
</Note>

## 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:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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](/reference/picklists/static) 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.

## Related

* [Static picklist](/reference/picklists/static): the alternative when options are admin-curated.
* [Hierarchical picklist](/reference/picklists/hierarchical): cascading for hand-authored static lists.
* [Records](/reference/records): the approved source data that populates automated picklists.
* [Dropdown field](/reference/fields/dropdown): `depends_on` and `source_field_id`, how a cascade level is set up from the field side.
* [Cascading dropdowns recipe](/recipes/cascading-dropdowns): a hands-on walkthrough.
* [Automated picklist recipe](/recipes/automated-picklist): an end-to-end setup.