Versions hierarchy

Overview

Depending on its size, Jira project can contain a lot of components. Components help split a project into smaller parts and group project issues to simplify search and project reporting.

Project components are a flat list of items which can represent a project at a different level of details. But the relations between components cannot be explicitly defined anywhere (except maybe in a component name).

When users select components in issues they don't typically have enough context about the component placement in the overall structure of the project.

Key features

Here is the list of key Subcomponents features:

• add new or existing components
• manage all component details without switching between project tabs
• view all component details in the hierarchy tree grid
• add components more than once in different places
• group components using folders (virtual components)
• search components in the hierarchy
• find issues for any part of a project represented by components hierarchy
• select components from hierarchy when creating (including Service Desk customer portal) or editing issues
• perform all operations with components hierarchy via REST API
• use custom JQL functions to search issues

Glossary

Throughout the documentation, we use some terms which we'd like to briefly explain before you continue.

Quick start guide

After installing the app a new project tab "Subcomponents" is added to all your Jira projects. It is the home of components hierarchy for a particular project.

If you are a project administrator you can create or change the hierarchy of the components. Users without project administrator permissions can explore the hierarchy of the components.

When you first land on the Subcomponents tab and no hierarchy has been defined yet, we recommend you take our Quick Tour to familiarize yourself with key features. All project users can always access Quick Tour using the link in the Help menu.

Overview

Subcomponents project page consists of two parts:

• hierarchy toolbar on top of the page
• hierarchy itself under the toolbar

Hierarchy toolbar

All users who can browse a project can also view its subcomponents hierarchy.

Project administrators can manage the hierarchy:

• Add existing component/folder - add one or more existing components/folders to the top of the hierarchy
• Add new component/folder - create and add new component/folder to the top of the hierarchy

Hierarchy item toolbar

Subcomponents hierarchy consists of hierarchy items - links to corresponding components or folders.

Each hierarchy item has its context menu with a set of available actions.

Users without project admin permissions can only expand and view item issues.

Manage hierarchy

Add new component

You can add a new component to the top of the hierarchy via Add new component action of the hierarchy toolbar or under a target hierarchy item using its context menu.

In Add component dialog you can specify all component details: name, description, component lead and default assignee.

By default new component is added as a last child of the target item. But you can change the position to add the component after the target item on the same level.

Add a new folder

When you start with Subcomponents app you don't have any folders.

Let's quickly recap what a folder is and what it can be used for:

• the folder is an additional hierarchy item type to group other components or folders
• the folder has a name (mandatory) and description attributes
• unlike components, two different folders can have the same name

You can add a new folder via Add new folder action in hierarchy toolbar or item context menu.

In Create folder dialog you can define folder name and description.

When a folder is created from the item context menu its relative position can be adjusted in the same way as in components.

Add existing components

When you start with Subcomponents app your project might already have some components you want to add to the hierarchy.

Similar to adding a new component you can add existing components to the top of the hierarchy from the hierarchy toolbar or under the target item via its context menu.

In the opened Add components dialog select the components you want to add and click 'Add to hierarchy' button.

All available project components are displayed in a table with the following columns:

• name - component name
• description - component description
• used in a hierarchy - how many times the component is added to a hierarchy 
• actions - component context menu with edit and delete actions

Use filters to find and select components from a reduced list. Components can be filtered by:

• name - free text input
• usage in a hierarchy - dropdown with the options: used, unused, all

Add existing folders

Adding existing folders to hierarchy is done via Add folders dialog. It is opened when you click Add existing (folders) from Subcomponents toolbar or hierarchy item context menu.

All available project folders are displayed in a table with the following columns:

• name - mandatory non-unique folder name
• description - optional folder description
• used in a hierarchy - the number of times folder is added to the hierarchy.
• actions - context menu with edit and delete actions

Select an individual folder or bulk select all folders you want to add to hierarchy.

Use filters to find and select folders from a reduced list. Folders can be filtered by:

• name - free text input
• usage in a hierarchy - dropdown with the options: used, unused, all

Manage components

In addition to adding components to hierarchy, you can fully manage components on Add components dialog without switching to Components project tab.

Manage folders

Add folders dialog is where you can manage project folders.

Edit and delete actions are located in each folder context menu.

Find issues

You can find issues for a particular part of the project represented by some root component and its children items.

There are two ways how to achieve that:

1. via hierarchy item View issues context action
2. via JQL search with the help of custom JQL functions: subcomponents() and subfolder()

View issues

Click on View issues action in the item context menu to open the View issues dialog with the list of issues.

Issues are displayed as a table and contain the following details:

• key - issue key linked to the issue page
• summary - summary
• components - all issue components

In the example below there are three components organized in a three-level hierarchy.

Each of the components has one issue directly associated with it.

Viewing issues for the top level component will result in all three issues being found.

In the background View issues screen utilizes JQL search capabilities to find the required issues and you can switch to Jira Issue Navigator to get more details about the issues.

JQL search

Subcomponents app adds two custom JQL functions to search issues in subcomponents hierarchy: subcomponents and subfolder.

The result of both functions is a list of components, that's why you should use them in a combination with "component in " prefix.

Select components in issue

Now let's explore how users can select components from the hierarchy using Subcomponents picker to add components to issue.

Subcomponents picker

Subcomponents picker is invoked via action button with the hierarchy icon located next to Components field on issue Create/Edit screen.

When you edit Components field inline Subcomponents picker action button is located in inline edit tools.

Subcomponents picker is a modal dialog with project components hierarchy.

Users can select components from the hierarchy and add them to issue in addition to selecting from the plain list.

Subcomponents picker settings

Users can configure hierarchy being displayed expanded or collapsed by default in Subcomponents picker via settings.

It is also possible to adjust automatic select/unselect behavior for a parent, sibling, and children items.