> ## 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: The UTM cascade

> Build the UTM Mediums and Sources hierarchy, learn how option lists change over time, and meet per-taxonomy option filtering.

<Info>
  **What you'll learn:** how a second hierarchical picklist powers the UTM medium and source pair, how option lists change (admins edit, then publish), 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, 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 values are where governance pays for itself. A free-text `utm_source` box produces `facebook`, `Facebook`, `fb`, and `FB Ads` within a month, and your analytics splinter four ways. A picklist-backed cascade produces exactly one spelling of each source, filed under the right medium. The trade-off is that the list is closed: a submitter can only pick what the published list offers, and a new source gets added by an admin, not typed into the form. This part builds the cascade and shows how that maintenance loop works. The other half of this part, `filter_options`, solves a different 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

### Option lists are closed

A dropdown offers the options its picklist holds, and nothing else. There is no way for a submitter to type a value that is not in the list; an out-of-list value simply fails validation. That closedness is the point: it is what keeps `utm_source` to one spelling per source.

### Admins change options by editing and publishing

When marketing launches on a new channel, an admin opens the picklist, adds the option, and publishes the governance model. Option edits behave like any other model change: they sit in the draft until you publish, and submitters see the new option once the publish goes through. The [publish a revision guide](/guides/publish-revision) covers that loop.

### When values move too fast for a list

Some values genuinely churn faster than any admin should be asked to keep up with. For those, a dropdown is the wrong shape. Use a **Text** field with **Suggest from past entries** turned on instead: submitters type freely, and the form suggests values the account has already approved for that field, which nudges everyone toward the same spellings without hard-blocking new ones. The [suggest past values recipe](/recipes/suggest-past-values) shows when and how. In this tutorial the UTM vocabulary is deliberately admin-owned, so we stay with picklists.

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

`filter_options` hides options, 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`. 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.
  </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.
* 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. The medium and source levels behave like Countries and Regions: pick `social`, and the source dropdown offers only Facebook, Instagram, LinkedIn, and X / Twitter. The vocabulary is admin-owned, so every submission spells every source the same way. `filter_options` is ready; Part 8 sets it.

```mermaid theme={null}
flowchart LR
  subgraph PL[UTM Mediums picklist]
    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

* **A new source is an admin edit plus a publish.** If marketing starts using a channel that is not in the list, an admin adds the option to `UTM Sources` and publishes. Submitters cannot add it from the form, and the option appears for them only once the publish goes through.
* **A static picklist always needs at least one option.** You cannot save an empty list and fill it in later; give every level at least one real option up front.
* **Keep codes lowercase and stable.** The code is what lands in the URL and in your analytics. Set the label to whatever reads well (`Paid search and ads`), but treat the code (`cpc`) as permanent.
* **`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 cascade, see the [cascading dropdowns recipe](/recipes/cascading-dropdowns).