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:
| Tip |
|---|
|
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.
Term | Comment |
|---|---|
Versions hierarchy | The hierarchy of project versions |
Item | Item or hierarchy item is an element which is added to the hierarchy. It is the link to a project version or folder |
Version | Native Jira project version (release) |
Folder | Custom hierarchy item type implemented in Versions hierarchy app |
Versions hierarchy picker | The extension of version fieldstype to select versions from the hierarchy |
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.
...
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.
...
Action | Description |
|---|---|
Expand | Expand all nested items of the target item |
View issues | View issues for the target item and all its children items |
Edit | Edit version or folder details |
Remove | Remove target item from the hierarchy. A confirmation dialog is displayed before the item is removed and contains the following information:
|
Add new version | Create and automatically add new version under of after target item |
Add a new folder | Create and automatically add a new folder under of after target item |
Add existing versions | Add one or more existing versions under of after target item |
Add existing folders | Add one or more existing folders under of after target item |
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.
...
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.
...
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.
Version action | Description |
|---|---|
Create | When new version is created in the Add versions dialog it is not added to hierarchy automatically. You would need to select and add it explicitly. |
Edit | When version is updated the hierarchy is updated with new details automatically. |
Delete | When version is deleted all its references from hierarchy are removed. All nested items of the deleted version are removed from hierarchy as well. If the deleted version is associated with some issues a popup dialog is displayed with options to swap issues to another version. |
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.
...
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.
...
Folder action | Description |
|---|---|
Create | When a new folder is created in “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 nested items of a deleted folder are removed from hierarchy as well. |
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:
using hierarchy item View issues context action
via JQL search with the help of custom JQL functions: subversions() and vrSubfolder()
View issues
Click on “View issues” action in the item context menu to open the View issues dialog with the list of 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 vrSubfolder.
...
Function | Parameters | Examples |
|---|---|---|
subversions() |
You can optionally provide the third parameter as "false" to exclude issues of current version from the result |
|
vrSubfolder() |
|
|
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.
...
| Info |
|---|
Versions hierarchy and Issue picker are fully supported in Jira Service Management projects. Customer portal users can take advantage of selecting versions from versions hierarchy when creating issues in the customer portal. |
Versions hierarchy picker settings
When Versions hierarchy picker is opened the hierarchy is displayed expanded or collapsed based on user settings.
...