Skip to main content

Component Hierarchy for Jira — User Guide

Introduction​

Jira components are a flat list — fine for small projects, but a poor fit for layered systems where "Auth" needs to sit under "Platform", and "SSO" under "Auth". Component Hierarchy for Jira adds a parent-child tree to your project's components: platforms, modules, and submodules arranged the way your product actually works.

Every node in the tree is a real Jira component, so boards, releases, and reports keep working exactly as before. On top of the tree you get:

  • A project page where anyone on the team can build and edit the tree.
  • A cascading picker on each issue that stores a full path such as Platform/Auth/SSO.
  • A JQL function — inComponentHierarchy("Auth") — that returns every issue in a node and all of its descendants.
  • CSV import/export for bulk setup, plus automatic syncing between tree nodes and Jira components.

Requirements​

  • Jira Cloud. The app runs natively in Jira and Jira Service Management.
  • Installing requires Jira administrator rights. Using the project page, the issue field, and JQL requires no special permissions.
  • One project = one tree. Trees are stored per project and don't affect other projects.

Installation​

  1. Go to Apps → Manage your apps in Jira.
  2. Click Find new apps and search for Component Hierarchy for Jira.
  3. Click Install. The custom field Component Hierarchy is created automatically.
  4. Open any project and find Component Hierarchy under the project sidebar's Apps section to build your first tree.

How to find the app​

Entry pointWhere
Tree editorProject sidebar → Apps → Component Hierarchy
Issue fieldIssue view, create screen, transitions, and JSM portal requests — field Component Hierarchy
JQL searchIssue navigator → inComponentHierarchy("NodeName")

Building the tree (project page)​

Open the project page: project sidebar → Apps → Component Hierarchy.

Add nodes​

  1. Type the first node's name where it says New root node name and confirm — this creates a root.
  2. Hover any row and click ＋ to add a child under it, type the Child node name, and confirm.
  3. Repeat as deep as you need. Multiple roots are supported — e.g. Platform and Auth side by side.

Row actions​

IconActionWhat it does
＋Add childCreates a child node under this row
✎EditRenames the node, or maps it to a different Jira component
⇌MovePicks a new parent from the Move to list (available once the tree has 2+ nodes)
🗑RemoveDeletes the node and everything under it

Saving​

You don't need to press save — every change is stored automatically a moment after you make it. Node names must be unique within the project (children of different parents may share a name — see JQL).

Tree nodes are real Jira components​

  • Creating a node creates a Jira component with the same name.
  • Components that already exist are adopted when names match — nothing is duplicated.
  • If some nodes don't have a matching component yet (e.g. after a CSV import), a Sync components button appears at the bottom toolbar — click it to create the missing ones.
  • When someone sets the field on an issue, the components for every node on the selected chain are added to that issue's Components automatically (the app only ever adds, never removes). Reports and boards that filter by component keep working.

Picking a path on an issue​

The Component Hierarchy field is a cascading picker: level by level, from roots down to leaves.

  1. Open an issue (or the create dialog, a transition screen, or a JSM portal request).
  2. In the Component Hierarchy field, pick the first level — you'll only see nodes that can follow your previous choice.
  3. Stop at any level; the field stores the full path, e.g. Platform/Auth/SSO.
  4. Leave it empty if the issue isn't tied to a node.

After a node is renamed, issues show the new name automatically — values are linked to the tree, not frozen text.

Searching with JQL​

Open the issue navigator and use:

inComponentHierarchy("Auth")

This returns every issue whose path is Auth or starts with Auth/ — the whole branch, at any depth. Combine it with anything else JQL offers:

inComponentHierarchy("Auth") AND status != Done
inComponentHierarchy("Platform") AND assignee = currentUser()
not inComponentHierarchy("Deprecated")

Same name at two depths? Use the level argument​

If your tree has two nodes called Auth (say, one under Platform and one under Mobile), add the node's depth as the second argument — a root is level 1, its children level 2:

inComponentHierarchy("Auth", 2)   // the Auth directly under a root
inComponentHierarchy("Auth", 3)   // an Auth one level deeper

Searches stay correct after edits: results are recalculated automatically whenever the tree changes, so a renamed or moved node doesn't leave stale results behind.

CSV import and export​

The bottom toolbar on the project page has everything for bulk setup:

ControlWhat it does
Download templateDownloads a CSV with the format Name,Parent
File pickerImports a CSV — this replaces the whole tree
Export CSV / Export JSONDownload the current tree (disabled while the tree is empty)

To import: download the template, fill one row per node, and import. A blank Parent means the row is a root; a Parent value must match a node defined in another row. Quoted names with commas are supported. Every imported node gets its matching Jira component created (use Sync components if any are still missing).

Tips & common workflows​

  • Service catalogs — model each service as a node and let agents file portal requests against Catalog/Billing/Refunds style paths.
  • Layered architectures — Platform / Auth / SSO mirrors how ownership actually nests, then inComponentHierarchy replaces fragile component in (...) lists.
  • Bulk migration — export a mature tree as JSON, tweak it, and re-import into a template project.
  • Board filters — swap long component lists for one inComponentHierarchy("Platform") clause; the filter keeps working as the tree grows.

Troubleshooting​

The field doesn't appear on my issues → A Jira admin needs to add the Component Hierarchy field to the relevant screens (Settings → Issues → Screens), or check the field's context covers your project.

inComponentHierarchy returns nothing → Check the node name spelling (matching is case-insensitive but otherwise exact), and confirm at least one issue has the field set. Issues only appear once their field value sits on or under that node.

Two nodes share a name and my search matches both → Add the level argument: inComponentHierarchy("Auth", 2) targets the one at a specific depth (roots are level 1).

A node has no Jira component → Click Sync components on the project page. It creates components for any node that's missing one.

Someone deleted a component in Jira directly → The node stays in the tree; click Sync components to recreate the component.

My CSV import looks wrong → The file must be Name,Parent with one node per row, parents defined in their own rows, and blank parent for roots. Remember importing replaces the current tree — export first if you need a backup.

Was this helpful?