Cascade Levels for Jira: Documentation

Getting started

  1. Install Cascade Levels from the Atlassian Marketplace.
  2. In Jira admin settings, open the custom fields page and create a new field. Choose the type Cascading select (multi-level).
  3. Add the field to the screens where people should see it.
  4. Open the field’s context settings to build the option list.

Building the option list

The context settings have three tabs.

Options. Add, rename, reorder, disable or remove options one level at a time. Choose an option to see and edit the options below it.

Add many. Paste many options at once, either as an indented list:

Europe
  Germany
    Berlin
    Munich

or as full paths, one per line, such as Europe > Germany > Berlin. Options that already exist are kept, so pasting the same list twice is safe. A size meter shows how much room the option list has left.

Levels and rules. Name each level (for example Region, Country, City) and choose whether people must pick a value on every level down to the last one.

Each field context has its own option list, so projects can share one field with different options. Only Jira admins can change options.

Choosing a value

On the issue view and create screen the field shows one picker per level. Each picker lists only the options below the value chosen above it. Disabled options are hidden from new choices, but issues that already use them keep their value.

Searching with JQL

Use the field name followed by a level alias:

Search Example
A level by name "Location.level1" = "Europe" up to level10
The last option chosen "Location.leaf" = "Berlin"
Text anywhere in the path "Location.path" ~ "Germany"
An option by id, including everything below it "Location.id" = "a1b2"

Searching by id keeps working after an option is renamed.

REST API, automation and CSV import

You can set the field with text such as Europe > Germany > Berlin. The app turns it into the matching options. Every value, however it arrives, is checked by a Jira expression: unknown options, broken paths and (when the rule is on) partial paths are rejected.

Renaming and removing options

A rename shows up right away wherever the field is displayed. Issues saved before the rename keep the old name for JQL searches on level, path and leaf until the field is chosen again; searches on id are not affected. Before you remove an option, the app counts the issues that use it, so you can disable it instead.

Limits