Pathpick documentation (public knowledge base source)
Getting started
- Build an option tree. Jira settings > Apps > Pathpick > New tree. Name it ("Locations") and name the levels top first ("Region, Country, City, Site"). Add options level by level (one per line), or Import CSV or list.
- Create the field. Jira settings > Work items > Fields > Create field > choose Pathpick cascading select, name it ("Location"), and pick the projects and work types in its context.
- Pick the tree and rules. On the field, open Contexts and default value > Edit configuration: choose the tree, optional level names for this context, and the rules (require the last level, minimum depth, number of picks, search over every level).
- Put it on screens. Add the field to the create, edit and view screens (and transition screens if needed). For Jira Service Management, add it to the request type's fields to show it on the portal.
Picking a value
- One select per level. Type inside any select to filter that level. When an option has a next level, it shows a small arrow and the next select appears.
- Search every level (if enabled for the context): type a few letters and pick a full path in one step, for example "EMEA > Germany > Berlin".
- Changing a level clears the levels below it.
- Several picks (if the context allows more than one): build a path and press Add this pick; at a last level, pick several options at once. Remove a pick with Remove.
- On the issue view, confirm with the check mark. In the create dialog, transition dialog and on the portal, the value is saved with the form.
Rules
| Rule | What it does |
|---|---|
| Require a pick at the last level | A pick must end at an option with no children |
| Pick at least down to | A pick must reach at least this many levels |
| Picks allowed | 1 for a single path, up to 50 |
| Show a search box over every level | Turns the cross-level search on or off |
Jira checks these rules whenever someone saves the field from Jira's screens or sends a value built from option ids. Text values written by imports or automation are matched after the save instead (see below).
Searching with JQL
| Query | Finds |
|---|---|
"Location.Path" = "EMEA > Germany > Berlin" | exactly that path |
"Location.Branch" = "EMEA > Germany" | that option and everything below it |
"Location.Level1" = "EMEA" | anything with EMEA at the top level |
"Location.Level3" = "Berlin" | Berlin at the third level, under any parents |
"Location.Depth" >= 3 | values that reach at least three levels |
"Location.Complete" = 1 | values that end at a last-level option |
"Location.Unmatched" > 0 | text that matched no option (fix after an import) |
"Location" ~ "berlin" | the word anywhere in the value |
"Location" is EMPTY | no value |
Level1 to Level10 are available. List view, filters, notifications and CSV export show the value as text, several picks separated by "; ".
Setting values as text (CSV import, bulk edit, automation, REST)
Write the path as text: EMEA > Germany > Berlin. Several picks: separate them with ;.
Pathpick matches the text to the field's tree right after the save, ignoring case and extra
spaces. Text that matches no option stays on the work item, shows a "No matching option" label
and is found by "Location.Unmatched" > 0. Matching also works for retired options, so old data
stays valid.
Managing trees
- Rename an option: work items that use it are updated in the background, so JQL and list view show the new name. The option id doesn't change.
- Move an option (with everything below it) under another option or to the top level; work items are updated the same way.
- Retire an option to remove it from pickers. Values that already use it keep it. Restore brings it back.
- Delete removes an option and everything below it, only when no work item uses any of them.
- Up / Down and Sort A to Z order a level ("Floor 2" sorts before "Floor 10").
- Edit tree renames the tree or its levels; a tree used by a field context can't be deleted.
Import and export
- One row per path, one column per level, top first. A blank cell repeats the value from the row above. A short row adds an option that has no children yet.
- Optional header row (recognised when it matches the tree's level names or ends in "Status").
- Optional Status column:
retiredretires the row's last option; empty restores it. - An indented list (two spaces or a tab per level) works too.
- Modes: Add new options (merge; nothing is removed) or Make the tree match this file (options not in the file are retired, never deleted).
- Up to 50,000 options per tree, 10 levels; large files are sent in chunks of 2,000 rows.
- Export CSV gives the same format, ready to import into another tree or site.
Moving from Data Center
Rebuild the tree from a CSV export of your options (one column per level), then bring values in
as text paths with > between levels. Anything that doesn't match is flagged, so you can fix the
tree and save again.
Limits
10 levels, 50,000 options per tree, 200 trees per site, 120 characters per option name (no >
or ;), 50 picks per value. Not available inside the Jira Service Management Forms feature.