Subcomponents

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.

TermComment
Subcomponents

Subcomponents are the hierarchy of components. Below are other ways we call subcomponents:

  • hierarchy
  • components hierarchy
  • subcomponents hierarchy
Item

Item or hierarchy item is an element which is added to the hierarchy. It is the link to a project component or folder

ComponentThe component is a native project component
FolderCustom hierarchy item type implemented in Subcomponents App
Subcomponents pickerThe extension of Components field to select components from the hierarchy

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.

Item actionDescription
ExpandExpand all children items of the target item
View issuesView issues for the target item and all its children items
EditEdit linked component or folder details
RemoveRemove target item from the hierarchy
Add new componentCreate and automatically add new component under of after target item
Add a new folderCreate and automatically add a new folder under of after target item
Add existing componentsAdd one or more existing components under of after target item
Add existing foldersAdd one or more existing folders under of after target item


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.

Component actionDescription
Create

When a new component is created from Add components dialog it is not added to hierarchy automatically.

You will then need to select and add it explicitly.

EditWhen a component is updated the hierarchy is updated with new details automatically.
Delete

When a component is deleted all its references from hierarchy are removed.

All children items of a deleted component are removed from hierarchy as well.

If a removed component is associated with some issues a popup dialog is displayed with options to swap issues to another component.

Manage folders

Add folders dialog is where you can manage project folders.

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


Component actionDescription
Create

When a new folder is created from Add folders dialog it is not added to hierarchy automatically.

You need to select and add it explicitly.

EditWhen a folder is updated the hierarchy is updated with new details automatically.
Delete

When a folder is deleted all its references from hierarchy are removed.

All children items of a deleted component are removed from hierarchy as well.

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.

FunctionParametersExamples
subcomponents()
  1. project key - key of the project to search in
  2. component name - find issues for all hierarchy items under this component including the component itself

You can optionally provide the third parameter as "false" to exclude issues of parent component and only keep those for its children components

  • component in subcomponents("DEMO", "Component A")
  • component in subcomponents("DEMO", "Component A", "false")
subfolder()
  1. project key - key of the project to search in
  2. folder name - find issues for all hierarchy items under this folder
  • component in subfolder("DEMO", "folder 1")

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.

OptionDescription
Bulk check parentsWhen a component is selected also select all its parent components
Bulk check siblingsWhen a component is selected also select all its sibling components
Bulk check childrenWhen a component is selected also select all its children components
Bulk uncheck parentsWhen a component is unselected also unselect all its parent components
Bulk uncheck siblingsWhen a component is unselected also unselect all its sibling components
Bulk uncheck childrenWhen a component is unselected also unselect all its children components