# Component Hierarchy for Jira — User Guide

## Introduction[​](#introduction "Direct link to 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[​](#requirements "Direct link to 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[​](#installation "Direct link to 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[​](#how-to-find-the-app "Direct link to How to find the app")

| Entry point | Where                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Tree editor | Project sidebar → **Apps** → **Component Hierarchy**                                            |
| Issue field | Issue view, create screen, transitions, and JSM portal requests — field **Component Hierarchy** |
| JQL search  | Issue navigator → `inComponentHierarchy("NodeName")`                                            |

***

## Building the tree (project page)[​](#building-the-tree-project-page "Direct link to Building the tree (project page)")

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

### Add nodes[​](#add-nodes "Direct link to 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[​](#row-actions "Direct link to Row actions")

| Icon | Action    | What it does                                                                        |
| ---- | --------- | ----------------------------------------------------------------------------------- |
| ＋   | Add child | Creates a child node under this row                                                 |
| ✎    | Edit      | Renames the node, or maps it to a different Jira component                          |
| ⇌    | Move      | Picks a new parent from the **Move to** list (available once the tree has 2+ nodes) |
| 🗑    | Remove    | Deletes the node **and everything under it**                                        |

### Saving[​](#saving "Direct link to 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](#searching-with-jql)).

***

## Tree nodes are real Jira components[​](#tree-nodes-are-real-jira-components "Direct link to 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[​](#picking-a-path-on-an-issue "Direct link to 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[​](#searching-with-jql "Direct link to 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[​](#same-name-at-two-depths-use-the-level-argument "Direct link to 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[​](#csv-import-and-export "Direct link to CSV import and export")

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

| Control                          | What it does                                                 |
| -------------------------------- | ------------------------------------------------------------ |
| **Download template**            | Downloads a CSV with the format `Name,Parent`                |
| File picker                      | Imports a CSV — **this replaces the whole tree**             |
| **Export CSV** / **Export JSON** | Download 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[​](#tips--common-workflows "Direct link to 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[​](#troubleshooting "Direct link to 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?👍 Yes👎 No