---
title: "Subcomponents"
canonical: "https://wiki.brokenbuild.net/space/SUBCLOUD/3754852537/Subcomponents"
format: markdown
---
## 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.
> ✅ 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 the hierarchy when creating (including the Service Desk customer portal) or editing issues
- export/import subcomponents hierarchy
### Glossary
Throughout the documentation, we use some terms that we'd like to briefly explain before you continue.
| 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 the 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 a 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 |
| --- | --- |
| 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:
> ℹ️
> ℹ️ - 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 the 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 the hierarchy toolbar or item context menu.
In Create folder dialog you can define the 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 the hierarchy, you can fully manage components on Add components dialog without switching to Components project tab.
| 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 |
| --- | --- |
| 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 the "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.
## Select components in issue
You can select components from the subcomponents hierarchy and assign component versions when creating or editing an issue. There are two ways to open the Subcomponents picker:
- **Custom fields on the issue layout** - available on both Create and Edit issue screens. This is the recommended way to work with subcomponents and component versions on issues.
- **Issue actions menu** - available when editing an existing issue.
### Subcomponents picker on issue layout
You can select components from the hierarchy and assign component versions directly on the issue layout when creating or editing an issue. This is done using two custom fields provided by the Subcomponents app:
- **Components (Subcomponents app)** - select components from the subcomponents hierarchy
- **Versions (Subcomponents app)** - select component versions for Fix versions, Affects versions, and other version fields
> ℹ️ The app creates these fields automatically during installation, but they won't appear on your issue screens until a Jira administrator adds them. Follow the steps below to get set up.
#### Add the fields to your issue screen
The fields are created automatically when the app is installed. To make them available on the Create and Edit issue screens, add them to the appropriate Jira screen:
1. Go to **Jira admin settings** > **Screens**.
2. Open the screen used by your project for the Create issue and Edit issue operations.
3. Use the **Select Field** dropdown at the bottom of the field list to add **Components (Subcomponents app)** and **Versions (Subcomponents app)**.
You can verify whether the fields are available from the Create issue dialog:
1. Open **Create issue** and click the **...** menu in the top-right corner. Then select **Find your field**.
2. Search for "subcomponents".
3. If a field is not yet on the screen, a diagnostic dialog will explain which settings need to be updated and link to the Screen configuration where you can add it.
#### Select components
The Components field displays a **Select components** dropdown and an **Add from hierarchy** button.
Click **Add from hierarchy** to open the Subcomponents picker. You can select components from the hierarchy and add them to the issue in addition to selecting from the plain list.
#### Select component versions
The Versions field displays a section for each version field available on the issue (e.g. **Fix versions**, **Affects versions**). Click **Add from component versions** to open the Component versions picker and select versions linked to the components on the issue.
#### Sync with native Jira fields
The custom fields sync their values to the corresponding native Jira fields (Components, Fix versions, Affects versions).
The sync behavior differs depending on whether you are creating or editing an issue:
| Operation | When sync happens | Details |
| --- | --- | --- |
| Create issue | After the issue is created | While filling in the form, a note is displayed below the fields: *Your selections will be added to Jira's native fields after you create the work item.* Native fields are populated once you click **Create**. |
| Edit issue | Immediately | Native fields are updated as soon as you select values in the picker modal. |
If a native field already contains values, the result is the combined set of both the existing and newly selected values. No existing values are removed during sync.
### Subcomponents picker in issue menu
You can also open the Subcomponents picker when editing an existing issue without using the custom fields. In the issue view, open the actions menu and select **Subcomponents**. This opens the same picker modal as described above.
This method is only available when editing an existing issue. To select components during issue creation, use the custom fields on the issue layout.
### Subcomponents picker settings
Users can configure the 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 |
| --- | --- |
| 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 |
## Export/import subcomponents hierarchy
You can export subcomponents hierarchy and then import it into another project. It works for different Jira instances and for different Jira deployment types. So you can export data from one project in Jira Server/DC and then import it into another project in Jira Cloud and vice versa.
Exported data are saved as JSON file. You need to copy the JSON text and paste it into Import data dialog during import process.
