Apply a custom hierarchy | Colined Help Center

You may have reached this article after creating a report by following the steps in a related article and now want to change the work item hierarchy within that report.

This article explains why you might need to update a report’s work item hierarchy and how to access it from the report sidebar.

If you want to modify the report’s appearance instead of its hierarchy, see the related article. To update the report source, refer to the corresponding article. To define a common hierarchy for all reports, see the separate article.

Why you should you create a custom hierarchy?

A custom hierarchy lets you extend beyond Jira’s default structure (Epic → Story → Sub-task) without changing Jira settings.

By using work item links, such as Blocked by, you can build a hierarchy directly within a report and use it in the Work item Structure tab, or define a custom hierarchy and apply it across all reports. This approach lets you create relationships across multiple levels—from Sub-task up to Initiative, Theme, or any structure you define—even across multiple spaces included in the report.

What is the difference between a Jira and a custom hierarchy?

Jira hierarchy: Jira provides a default hierarchy based on standard work types, such as Sub-task, Task, Bug, Story, and Epic. This built-in structure follows a fixed order and does not include higher levels like Themes or Initiatives.

Custom hierarchy: A custom hierarchy lets you define your own work item structure using existing work item links created in the Work item View. This allows you to extend the hierarchy beyond Epics to include levels such as Themes and Initiatives.

You can also create a custom hierarchy even if you don’t use standard work types like Stories or Epics, without modifying your Jira settings.

Features and use cases

Use 'Blocked by' or another link to show a parent relationship

You can add links, such as as Blocked by, in the Work item View to represent a relationship with a parent item in your organization and display it using a custom hierarchy in a report. Other organizations may use different links, such as Belongs to, for the same purpose.

Make sure to extend the report source to include parent work item when they belong to another space. For example, an Initiative may act as a parent work item—through a relationship link—but exist in a different space than its Epic.

If the report source only includes the Epic and is not extended to include parent work items, the Initiative will not appear after enabling the custom hierarchy.

Follow these steps to verify relationship links, extend the report source, and configure a custom hierarchy:

In this example, the report source references three spaces using JQL. Click Columns.
Select or search for Linked Issues.
Identify the highest-level parent and determine the relationship type. In this example, Epic SKP-17 blocks Initiative SSP-32, which belongs to a space not included in the report source.

Enable Parent Work items to extend the report source.
Click Apply.

Click + Add Link Type.
Select a Parent Work item Type, Link Type, and Child Item Types.

In this example, Initiative SSP-32 is blocked by Epic SKP-17. As a result, Initiative is the parent work item type and Epic is the child item type.

Click Apply.

After completing these steps, the parent relationship appears in the hierarchy, as shown in the screenshot below.

Note that Epic SKP-17 is grouped under the space associated with its parent Initiative as part of the custom hierarchy.

Use a common hierarchy across all reports

You can apply a shared hierarchy across all reports by selecting Use default settings in the report sidebar, as shown in the screenshot above.

A Jira admin can configure a custom hierarchy that is automatically applied to newly created reports or to any report where this option is selected. The steps to create this hierarchy are described in a related article.

How can you create custom hierarchy within a report?

The Source tab can be accessed from the report sidebar by following these steps:

Click Configure in the header section.
Select Source in the dropdown.
Select a Parent Work type, Link Type, and Child item types.
Click Apply.

FAQ

How can you create and display additional levels in Jira?

With a Jira Cloud Premium or Enterprise subscription, you can use more than three hierarchy levels in company-managed spaces. As a Jira admin, you can create additional levels by following the steps mentioned in a related article.

Once created, you can display these levels in a Plan (formerly Advanced Roadmaps), which is included in your subscription. Within a Plan, use filters to view the full hierarchy or select a range of levels using dropdown menus—for example, from Initiative to Sub-task or from Epic to Story.

In comparison, with the Pivot Report app, you can create a custom hierarchy on a Free plan. However, it is limited to three levels.

On higher tiers, you can create a full hierarchy and display all levels directly in a report, without using a Plan (formerly Advanced Roadmaps).

How can you interpret the relationship links?

In the Work item View, an Epic is linked to an Initiative using a Blocks relationship. This means the Initiative is blocked by the Epic.

In the Work item Structure tab of a report, the Blocks column displays the Initiative. The arrow points toward the Epic, indicating that it is blocking the Initiative.

Can you create a custom hierarchy that varies per project in a report?

No. You cannot create a custom hierarchy that varies per space in a report.

All spaces included in the report source follow the same hierarchy, whether it is the default hierarchy or a custom hierarchy defined for the report.

If you need different hierarchies, create separate reports for each space and configure each one individually.

For example, one report can use the Blocked by link, while another uses the Belongs to link. Afterwards, use dashboard gadgets to show each report and both space hierarchies.

What if you want to use 'Relates to' or 'Belongs to' for showing a parent relationship?

You can use Relates to, Belongs to, or another link type to show a parent relationship in a custom hierarchy. For example, an Epic may Belong to an Initiative.

For any link type:

Enable the link columns for both incoming and outgoing links.
Review these columns to identify which work item is the parent.
Check if the parent is in the same space; if not, extend the source to include parent work items.
Configure the custom hierarchy based on the identified parent.

Can you override a common hierarchy in a report?

Yes. You can override the common hierarchy by disabling Use default settings in the report sidebar. In the screenshot above, this option is enabled.

Once disabled, the common hierarchy is copied into your custom hierarchy. You can remove these entries by clicking the bin icon or by editing each field individually (Parent Work item Type, Link Type, and Child Item Types), as shown in the screenshot below.

Can you use a custom hierarchy to any deliverable type?

Yes. You can define a custom hierarchy for a specific work type or apply it to all work types, as shown in the screenshot above.

Leave the Parent work types and Child item types boxes empty to apply the hierarchy to any work type. However, this may cause a work item to appear multiple times in the hierarchy.

Troubleshooting

Why is one your deliverables linked to multiples parents?

A work item can appear under multiple parents in the hierarchy when using a custom hierarchy.

For example, a task can be linked to both a Theme and an Initiative. In this case, the work item may appear under both parents.

The task and its sub-tasks can appear under the Theme.

Only the task appears under the Initiative. The Initiative itself may also be linked under the same Theme.

Without using a custom hierarchy, the task and its sub-tasks would not appear under both a Theme and an Initiative.

To prevent a work item from appearing multiple times in the hierarchy, either unlink it from the Initiative or specify values in the Parent work types and Child item types fields.

Leaving these fields empty allows any work type to be included in the relationship, as shown in the screenshot below.

What can you do if the app is missing from the sidebar?

If Pivot Report is missing from the Apps list from Jira’s sidebar, check if it is disabled by following the steps listed in a related article.

If you have questions or need assistance, contact our support team via email or service desk. Our team is available Monday through Friday (9:00 AM to 7:00 PM GMT+7) to help with technical challenges or discuss improvements.