Subcomponents for Jira Cloud

 

Why subcomponents

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 that can represent a project at a different level of detail. 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.



With Subcomponents you can:

  • organize project components in a structural and hierarchical way

  • visualize parent-child relations between components

  • add more context when selecting components from the hierarchy

  • search issues related to a particular part of a project represented by a subcomponents hierarchy at any level

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

Glossary

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

Term

Comment

Term

Comment

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

Component

The component is a native project component

Folder

Custom hierarchy item type implemented in Subcomponents App

Subcomponents picker

The 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 action

Description

Item action

Description

Expand

Expand all children items of the target item

View issues

View issues for the target item and all its children items

Edit

Edit linked component or folder details

Remove

Remove target item from the hierarchy

Add new component

Create and automatically add new component under of after target item

Add a new folder

Create and automatically add a new folder under of after target item

Add existing components

Add one or more existing components under of after target item

Add existing folders

Add one or more existing folders under of after target item

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

A confirmation dialog is displayed before the item is removed and contains the following information that:

  • item is removed with all its children items, number of items is included

  • neither components nor folders are deleted, only their references in the hierarchy are removed

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 component is added to the 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 action

Description

Component action

Description

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.

Edit

When 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 action

Description

Component action

Description

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.

Edit

When 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.

Click on View issues action in 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.

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

Once project administrator has established subcomponents hierarchy users can select components from that hierarchy via "Subcomponents" picker available on issue operations toolbar.

It is not possible to use Subcomponents picker on Create/Edit issue screen due to Jira Cloud API limitations

 

Click on "Subcomponents" issue action to open "Subcomponents" dialog where you can:

  • select one or more components to be assigned to the current issue

  • expand/collapse subcomponents hierarchy

  • search components by name

Click on "Apply" will update issue with the selected components.

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.

Option

Description

Option

Description

Bulk check parents

When a component is selected also select all its parent components

Bulk check siblings

When a component is selected also select all its sibling components

Bulk check children

When a component is selected also select all its children components

Bulk uncheck parents

When a component is unselected also unselect all its parent components

Bulk uncheck siblings

When a component is unselected also unselect all its sibling components

Bulk uncheck children

When a component is unselected also unselect all its children components

Support and questions

Please, contact us using the following support channels if you need help with Subcomponents for Jira Cloud app.