• Products
  • Documentation
  • Resources

Upcoming changes: Epic link data above the epic level

The information on this page is for Jira Cloud customers only. Data Center customers are not affected by these updates.

The processes described in this section are only possible with Jira administrator permissions.

We’re making changes to the parent/child relationships of issues in Jira – in 2022 and 2023 we’ll be moving towards a single way of representing parent/child relationships to give you a simple, consistent experience for all levels in Jira.

epic-link and parent-link in company-managed projects will be replaced with the parent concept already used in team-managed projects. This will happen in a 3-step process:

  1. Users won’t be able to make invalid epic-link relationships. [RELEASED]

  2. Invalid epic-link relationships will be deleted. [NOVEMBER 2022]

  3. epic-link and parent-link will be replaced with parent. [2022-2023]

A valid epic-link relationship is when the child issue is 1 level below the epic. An invalid epic-link relationship is when the epic in an epic-link is not 1 level above the child issue. Invalid epic-link relationships include when the:

  • child issue is at the same level as the epic

  • child issue is from a higher level than the epic

The issue hierarchy screen in a company-managed project

To adjust your issue hierarchy, in the navigation bar, admins can go to Settings > Issues, and select Issue type hierarchy from the sidebar.

If you attempt to add an invalid epic-link relationship, an error message will appear.

The error message displayed when trying to add an invalid epic link on an issue.

You will also receive an error if you attempt to add an invalid epic-link relationship by dragging and dropping an issue (at the same or higher hierarchy level) into the Epic panel on the backlog.

When this change is released, the epic-link value for affected issues will be deleted. To see if your site will be affected by this change, follow the directions below.

When this change is released, the other field values in the issue will not be changed in any way.

View affected issues

To view if your data will be impacted this change, using the following JQL in the advanced search. In the sample below, <LIST OF ISSUE TYPES> is a comma-separated list of the issue types at or above the epic hierarchy level that you want to check:

issuetype in (<LIST OF ISSUE TYPES>) and "Epic Link" is not EMPTY

For example, issuetype in (Feature, Initiative) and "Epic Link" is not EMPTY will return a list of Feature and Initiative issue types that have epic link data.

This JQL search only returns impacted issues in active projects. If an archived or trashed project contains invalid epic-link relationships, these links will not be recovered when the project is restored.

Learn more about advanced searching in Jira.

To view the issue types that sit above the epic level in your issue hierarchy: in the navigation bar, go to Settings > Issues, and then select Issue type hierarchy from the sidebar.

Maintain epic relationships

There are two approaches you can take to maintain the epic relationships on affected issues:


Add the epic as a linked issue

You can maintain your epic relationships by changing them to different relationships using linked issues. Learn more about linking an issue.

Adding an epic as a linked issue
  1. Open the issue that you want to update the epic link for.

  2. Select Link issue.

  3. Choose the type of issue link, e.g. relates to.

  4. Specify the epic that you want to link to, by either:

  5. Select Link.

  6. Select the Epic link field and remove the epic.

Move affected issue types to the base level

Alternatively, if you wish to maintain your epic link data, you can move the affected issue types to the base level in your issue hierarchy. Learn more about configuring your hierarchy levels in Advanced Roadmaps.

Changing your issue hierarchy within Jira may invalidate existing parent and child relationships between your issues.

Updating the issue hierarchy on the Advanced Roadmaps hierarchy levels screen
  1. In the navigation bar, select Settings > Issues, and then select Issue type hierarchy from the sidebar.

  2. Locate and deselect the affected issue type(s) under the Jira issue types column. This will remove the issue type from its current level.

  3. Select Save changes.

If you need to recover an epic-link relationship, please contact our support team.

Company-managed epic-links and parent-links will be migrated to a parent field consistent with team-managed projects. We’ll share additional details about these updates on the Atlassian Community soon.

Need more help?

If you have any questions, please visit our FAQ page or contact our support team.

Additional Help