Versions hierarchy

Overview

Jira project can contain a lot of versions that represent points-in-time for your project. You can assign issues to versions to find what was done a in particular project version. While project versions live as a flat list of items in Jira, using Versions hierarchy app you can:

Key features

The Versions hierarchy app introduces the following features:

• add new or existing versions to the hierarchy

• manage all version details without switching to Releases project tabs

• view all version details in the hierarchy tree grid

• add the same version to multiple places in the hierarchy

• group versions using folders

• search versions in the hierarchy

• find issues for any part of a project represented by versions hierarchy

• select versions from hierarchy when editing issues

• perform all operations with versions hierarchy using 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 "Versions hierarchy" is added to Project navigation tab where you can manage project versions hierarchy aka Versions hierarchy organizer.

By default, only project administrator can manage the versions hierarchy. Project administrator can enable non-project admin users to manage versions hierarchy by granting them “Manage versions hierarchy“ project permission.

When you first land on the Versions hierarchy project tab with the empty hierarchy, take a Quick tour to get familiar with the key features. Quick tour link is also available in Help menu.

Overview

Versions hierarchy project page consists of two parts:

• toolbar on top of the page

• hierarchy under the toolbar

Hierarchy toolbar

Using Versions hierarchy toolbar you can:

• search/filter versions in the hierarchy by its name

• add existing version/folder - add one or more existing versions/folders to the top of the hierarchy

• add new version/folder - add new version/folder to the top of the hierarchy

• expand/collapse all items in the hierarchy

• find more details about the app and raise support request using Help menu.

• import/export versions hierarchy from/to another project in the same or different Jira instance

Hierarchy item toolbar

Versions hierarchy consists of hierarchy items - versions and folders. Each hierarchy item has its context menu with a set of available actions.

Manage hierarchy

Add new version

You can add a new version to the top of the hierarchy using “Add new version” action in the hierarchy or item context menu. In the opened dialog you can specify all version details: name, description, start date, release date.

By default new version is added after the current item at the same level. But you can change the position to add a version under the current item as a last nested item.

Add new folder

When you start with Versions hierarchy app you there are no folders.

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

• folder is an additional hierarchy item type to group other versions or folders

• folder has name (mandatory) and description attributes

• unlike version, two different folders can have the same name

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

Add existing versions

Any existing version can be added to the hierarchy using “Add existing versions“ action.

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

In the “Versions“ dialog all available project versions are displayed with the dialog you can select versions that you want to add to the hierarchy.

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

• name - version name

• description - version description

• used in a hierarchy - how many times the version is added to a hierarchy 

• actions - version context menu with edit and delete actions

Manage versions

In the “Versions” dialog you can also edit existing or create new versions without switching to the Releases project tab.

Filter versions

Use filters to find and select versions from the shorter list. Versions 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 the hierarchy is done via Add folders dialog. It is opened when you click Add existing (folders) from Versions hierarchy toolbar or hierarchy item context menu.

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

• name - mandatory non-unique folder name

• description - optional folder description

• used in a hierarchy - how many times the folder has been added to the hierarchy.

• actions - context menu with edit and delete actions

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

Manage folders

Add folders dialog is where you can manage project folders.

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

Filter folders

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

• name - free text input

• usage in a hierarchy - dropdown with the options: used, unused, all

Find issues

You can find issues for a particular part of the project represented by some version and its nested items:

1. using hierarchy item View issues context action

2. via JQL search with the help of custom JQL functions: subversions() and vhSubfolder()

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

• versions - all issue versions from fixVersion field

In the example below there are three versions are organized in a three-level hierarchy where each version has one issue directly associated with it.

The result for Version 1.0 includes all three issues.

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

Versions hierarchy app adds two custom JQL functions to search issues in versions hierarchy: subversions and vhSubfolder.

The result of both functions is a list of versions, that's why you should use them in a combination with version field, e.g. "fixVersion in subversions(…)".

Select versions in issue

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

Versions hierarchy picker

Versions hierarchy picker is displayed when you click the action button with the hierarchy icon located next to any version field on the issue Create/Edit screen.

When you edit the version field inline Versions hierarchy picker action button is located in inline edit tools.

Versions hierarchy picker is a modal dialog with project versions hierarchy.

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

Versions hierarchy picker settings

When Versions hierarchy picker is opened the hierarchy is displayed expanded or collapsed based on user settings.

Except expand/collapse default state the settings also contain configuration options to manage automatic select/unselect behavior of parent, sibling, and children items of the target item.