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 work items 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:
Users won’t be able to make invalid epic-link relationships. [RELEASED]
Invalid epic-link relationships will be deleted. [NOVEMBER 2022]
epic-linkandparent-linkwill be replaced withparent. [2022-2023]
Users won’t be able to make invalid epic-link relationships [Released]
A valid epic-link relationship is when the child work item 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 work item. Invalid epic-link relationships include when the:
child work item is at the same level as the epic
child work item is from a higher level than the epic
To adjust your work item hierarchy, in the navigation bar, admins can go to Settings > Work items, and select Work type hierarchy from the sidebar.
If you attempt to add an invalid epic-link relationship, an error message will appear.
You will also receive an error if you attempt to add an invalid epic-link relationship by dragging and dropping a work item (at the same or higher hierarchy level) into the Epic panel on the backlog.
Invalid epic-link relationships will be deleted [November 2022]
When this change is released, the epic-link value for affected work items 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 work item will not be changed in any way.
View affected work items
To view if your data will be impacted this change, using the following JQL in the advanced search. In the sample below, <LIST OF WORK TYPES> is a comma-separated list of the work types at or above the epic hierarchy level that you want to check:
worktype in (<LIST OF WORK TYPES>) and "Epic Link" is not EMPTY
For example, worktype in (Feature, Initiative) and "Epic Link" is not EMPTY will return a list of Feature and Initiative work types that have epic link data.
This JQL search only returns impacted work items 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 work types that sit above the epic level in your work item hierarchy: in the navigation bar, go to Settings > Work items, and then select Work type hierarchy from the sidebar.
Maintain epic relationships
There are two approaches you can take to maintain the epic relationships on affected work items:
If your work item hierarchy is important in its current form, you can add the epic as a linked work item (e.g. relates to).
OR
If your epic link data is important to maintain, you can move any affected work types to the base level in your work item hierarchy.
Add the epic as a linked work item
You can maintain your epic relationships by changing them to different relationships using linked work items. Learn more about linking a work item.
Open the work item that you want to update the epic link for.
Select Link work item.
Choose the type of work item link, e.g. relates to.
Specify the epic that you want to link to, by either:
typing the full work item key (ABC-123, for example)
searching for a work item with a text search or an advanced search.
Select Link.
Select the Epic link field and remove the epic.
Move affected work types to the base level
Alternatively, if you wish to maintain your epic link data, you can move the affected work types to the base level in your work item hierarchy. Learn more about configuring your hierarchy levels in Advanced Roadmaps.
Changing your work item hierarchy within Jira may invalidate existing parent and child relationships between your work items.
In the navigation bar, select Settings > Work items, and then select Work type hierarchy from the sidebar.
Locate and deselect the affected work type(s) under the Jira work types column. This will remove the work type from its current level.
Select Save changes.
Recovering deleted epic-link relationships
If you need to recover an epic-link relationship, please contact our support team.
Epic-link and parent-link replaced with parent [2022-2023]
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.
Was this helpful?