Versions Hierarchy

This documentation is for Versions Hierarchy app version 1.x

Version 2.x documentation is available at Versions hierarchy v2

About "Versions Hierarchy" app

Versions in JIRA projects are represented as a flat list of items while in real life large and modular projects releases are usually a combination of its modules versions.

Versions Hierarchy add-on allows you to organize modular project releases with versions hierarchy and get a list of issues for modules sub-tree at any level.

Check out Versions Hierarchy on Atlassian Marketplace

How to install

  1. Log into your JIRA instance as an admin.

  2. Click the admin dropdown and choose Atlassian Marketplace.

    The Manage add-ons screen loads.

  3. Click Find new add-ons from the left-hand side of the page.

  4. Locate Versions Hierarchy via search.

    The appropriate add-on version appears in the search results.

  5. Click Try free to begin a new trial or Buy now to purchase a license for Versions Hierarchy.

    You're prompted to log into MyAtlassian. Versions Hierarchy begins to download.

  6. Enter your information and click Generate license when redirected to MyAtlassian.

  7. Click Apply license.

  8. If you're using an older version of UPM, you can copy and paste the license into your JIRA instance.

Admin's guide

Users with project administration access can create versions hierarchy for the selected project in the "Versions Hierarchy" project admin tab.

There are two panels in the versions hierarchy page: "Available versions" and "Versions hierarchy".

Available versions panel

Project versions which are present in the project, but are not currently added to the hierarchy, are displayed on the "Available versions" panel.

On the "Available versions" panel you can:

  • create new versions here without switching to "Versions" tab and then add them to a hierarchy

  • add versions to hierarchy with drag&drop

  • filter versions by "released/unreleased" and "archived/non-archived" version properties

Versions hierarchy panel

Versions hierarchy panel is where you define the structure of the project versions.

Drag&drop versions to change the existing hierarchy and add new versions from "Available versions" panel.

You can also search and filter versions by name using the "Filter" form.

Issues preview panel

By selecting version in the hierarchy you can preview issues for the selected versions sub-tree.

There are key, summary and fixVersion fields data is shown in the preview.

You can click the total number of issues link to view issues in JIRA Issue Navigator

User's guide

Users can take advantage of the project versions hierarchy in two ways:

  • select versions from hierarchy when creating/editing issues

  • search issues in the versions hierarchy

Selecting versions using Version Picker

Use "Version Picker" to select versions from hierarchy when creating/editing issues which is available via link next to "Fix Versions" field:

In the opened dialog select versions from the configured versions hierarchy for the current issue's project:

Search issues using subversions() JQL function

You can find all issues for particular version sub-tree using subversions() JQL function:

JQL search query syntax with subversions() JQL is the following:

<version field> in subversions(<project key>, <root version>, <include/exclude root version issues>)


  • version field -  standard JIRA fixVersion or affectVersion fields, or any custom field of Version type

  • project key - project key to search versions hierarchy in

  • main version - root version name of a hierarchy sub-tree to get issues for

  • include/exclude root version issues - true/false

Issues preview page

Project users can preview issues for the selected versions sub-tree same way as project administrators on a generally available project tab "Versions Hierarchy":

REST API v1.0-alpha reference 

since 1.4.0

Versions Hierarchy add-on uses REST API for all CRUD operations. It is still an alpha version of the API that can be used at the moment.

Get project versions hierarchy as a tree

Request: <jira_url>/rest/net.brokenbuild.versions-hierarchy/1.0-alpha/<project_key>

Request type: GET

Example response:

[ { "key": 10000, "title": "Version 1.0", "name": "Version 1.0", "sequence": 1, "isReleased": true, "isArchived": false, "projectId": 10000, "linkId": 1, "folder": true, "expanded": true, "children": [ { "key": 10001, "title": "Version 2.0", "name": "Version 2.0", "sequence": 2, "isReleased": false, "isArchived": false, "projectId": 10000, "linkId": 3, "folder": false, "expanded": true } ] } ]

Get project versions hierarchy as a list

Request: <jira_url>/rest/net.brokenbuild.versions-hierarchy/1.0-alpha/<project_key>/list

Request type: GET

Example response:

[ { "id": 1, "versionId": 10000, "projectId": 10000 }, { "id": 2, "versionId": 10002, "parentId": 10000, "projectId": 10000 }, { "id": 3, "versionId": 10001, "parentId": 10000, "projectId": 10000 } ]

Add version to project versions hierarchy

Request: <jira_url>/rest/net.brokenbuild.versions-hierarchy/1.0-alpha/<project_key>

Request type: POST

Request body: 

{ childId: <child JIRA version id>, parentId: <parent JIRA version id> }

Return: link id of the added version in the hierarchy

Remove version from project versions hierarchy

Remove version with all sub-tree identified by link id of the version in the hierarchy

Request: <jira_url>/rest/net.brokenbuild.versions-hierarchy/1.0-alpha/<project_key>/<version_link_id>

Request type: DELETE

Move version inside project versions hierarchy

Request: <jira_url>/rest/net.brokenbuild.versions-hierarchy/1.0-alpha/<project_key>/<version_link_id>

Request type: PUT

Request body:

{ newParentVersionId: <new parent JIRA version id> }

Support & questions

Please, contact us via the following support channels if you have any questions or need help with the Versions Hierarchy app.