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

# Part 6: User-addable picklists

> Build the UTM Mediums and Sources hierarchy, turn on Allow new values so submitters can propose options, and meet per-taxonomy option filtering.

<Info>
  **What you'll learn:** how the "Allow new values" setting (`allow_additions`) lets submitters propose new options, how those options are created only on approval, and how per-taxonomy option filtering (`filter_options`) shows a different subset of the same picklist to each taxonomy.

  **What you'll build:** one two-level `UTM Mediums / UTM Sources` hierarchical picklist with "Allow new values" turned on, plus two dropdown fields (`utm_medium`, `utm_source`) that form the second cascade.

  **Prerequisites:** [Part 5: Hierarchical picklists](/tutorial/05-hierarchical-picklists).
</Info>

## Why this matters

UTM sources mutate faster than any governance model keeps up with. Marketing spins up a new newsletter, launches on a new paid channel, tries a partner network, and none of it should require a ticket to get `partnerstack` added to a list. "Allow new values" is the escape valve: submitters propose new options as they fill a submission, reviewers catch typos before the option is created, and the picklist grows without admin babysitting. The other half of this part, `filter_options`, solves the opposite problem. Three taxonomies share the same `utm_medium` field, but each should only see its own medium: Email should never offer `social` or `cpc`. You wire `filter_options` for real in Part 8; here you just meet it.

## Concepts first

### "Allow new values" (`allow_additions`)

A setting on a **Static** picklist, labeled **Allow new values** in the editor. When it is on, any dropdown backed by that picklist lets a submitter type a value that is not in the list yet. The typed value attaches to that submission row as a proposed option with a "new" badge. It is local to the submission: other submissions do not see it, and the picklist itself is unchanged while the submission is a draft.

### Proposed options are created on approval

A proposed value becomes a real picklist option only when the submission is **approved**. At that point Terminus walks the approved rows, finds the proposed options, and adds the missing ones to the picklist so every future submission can pick them. Reject or cancel the submission and the proposed values disappear with it; the picklist never changed.

### Gated by the published revision

Whether a picklist accepts new values is read from the governance model's **published revision** at approval time, not from the live setting. If you toggle "Allow new values" off but submissions are already in flight against an older published revision, those submissions still follow the contract they were built against. This keeps an admin's mid-flight change from silently rewriting what an in-progress submission is allowed to do. Publishing is covered in the [publish a revision guide](/guides/publish-revision).

### Per-taxonomy option filtering (`filter_options`)

Where "Allow new values" adds options, `filter_options` hides them, per taxonomy. On a taxonomy's copy of a dropdown field you can either **include** a chosen subset of codes (an allowlist: only those show) or **exclude** some codes (a blocklist: everything except those shows), never both. The picklist itself is untouched. This is how one `utm_medium` field can appear on three taxonomies and show a different single medium on each.

## Step-by-step

<Steps>
  <Step title="Create the UTM Mediums / UTM Sources picklist">
    Open the `Marketing` GM, click **Picklists**, then **Create new** and choose **Static Picklist**. Name it `UTM Mediums`. In the first level, add `email` / `Email`, `social` / `Social`, `cpc` / `Paid search and ads`. These are your mediums.
  </Step>

  <Step title="Add a second level for sources">
    Click **Add level** to add a child level for sources. Under `email`, add `newsletter` / `Newsletter`, `drip` / `Drip campaign`, `transactional` / `Transactional`. Under `social`, add `facebook` / `Facebook`, `instagram` / `Instagram`, `linkedin` / `LinkedIn`, `twitter` / `X / Twitter`. Under `cpc`, add `google` / `Google Ads`, `bing` / `Bing Ads`, `meta_ads` / `Meta Ads`.
  </Step>

  <Step title="Turn on Allow new values">
    In the picklist editor, turn on **Allow new values**. This is the user-facing name for `allow_additions`: submitters can now propose sources that are not in the list yet. Save the picklist.
  </Step>

  <Step title="Create the utm_medium Dropdown field">
    Go to **Fields** and click **Create new field**. Name: `utm_medium`. Type: **Dropdown**. **Picklist**: pick the top (medium) level of `UTM Mediums`. Leave option filtering alone; you set it per taxonomy in Part 8, once the taxonomies exist. Save.
  </Step>

  <Step title="Create the utm_source Dropdown field">
    Click **Create new field** again. Name: `utm_source`. Type: **Dropdown**. **Picklist**: pick the source (child) level. Save. The editor wires the cascade to `utm_medium` automatically, and the field inherits the "Allow new values" behavior from its picklist.
  </Step>
</Steps>

<Note>📸 Screenshot coming soon: part 06 utm hierarchy</Note>

## Check your work

* A single `UTM Mediums` picklist exists with two levels: three mediums (`email`, `social`, `cpc`) and the source options nested under each.
* The picklist has **Allow new values** turned on.
* Two new fields exist: `utm_medium` (Dropdown on the medium level, no filtering yet) and `utm_source` (Dropdown on the source level, cascading from `utm_medium`).
* The GM has eight fields total: the six from Parts 3 to 5 plus `utm_medium` and `utm_source`.

## What you just built

A second cascade, with a twist. The medium and source levels behave like Countries and Regions (pick `social`, see only Facebook, Instagram, LinkedIn, X / Twitter), but submitters can also propose, say, `threads` at submission time and it flows through review like any other change. `filter_options` is ready; Part 8 sets it.

```mermaid theme={null}
flowchart LR
  subgraph PL[UTM Mediums picklist · Allow new values]
    M[Level 1: mediums<br/>email, social, cpc]
    S[Level 2: sources<br/>newsletter, drip, … → email<br/>facebook, instagram, … → social<br/>google, bing, … → cpc]
    M -.ancestor path.-> S
  end
  MF[utm_medium field<br/>Dropdown → medium level] -->|cascade| SF[utm_source field<br/>Dropdown → source level]
```

## Gotchas

* **"Allow new values" is a Static-picklist setting only.** Automated picklists source their options from another taxonomy's records, so a "new option" there would have no meaning; the toggle does not appear on them. See [automated picklists](/recipes/automated-picklist).
* **Rejected and cancelled submissions create nothing.** A proposed value only becomes a real option on approval. If a reviewer rejects a submission that proposed `newsleter`, that typo is discarded with the submission and never lands in the picklist.
* **The published revision decides, not the live toggle.** Turning "Allow new values" off does not retroactively block submissions already in flight against an older published revision. Republish to change the contract for new submissions.
* **Reviewers should spot-check proposed values before approving.** Nothing stops a submitter from typing `Newsletter` with a capital N and creating a near-duplicate. Glance at any proposed (newly badged) options before you approve; the [submissions reference](/reference/submissions) covers the review step.
* **`filter_options` is a per-taxonomy override, not a picklist setting.** You configure it on each taxonomy's copy of the field. Part 8 sets three different filters for the same `utm_medium` field on three taxonomies. See [filter options per taxonomy](/recipes/filter-options-per-taxonomy).

## Next up

[Part 7: Computed fields](/tutorial/07-computed-fields). The payoff. Wire `utm_campaign`, `tagged_url`, `short_url`, and `qr_code` into a four-level chain. For the standalone version of this part, see [letting submitters add options](/recipes/user-addable-options).