• Products
  • Documentation
  • Resources

Upcoming changes: 'epic-link' replaced with 'parent'

Currently, the epic-link connects issues from the base level (containing stories, bugs, tasks) to epics, and the parent-link connects epics to issues at higher levels for those who have Jira Software Cloud Premium.

From October 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 your Jira Software projects. epic-link and parent-link in company-managed projects will be replaced with the parent concept already used in team-managed projects.

Note: The following updates will apply automatically to your Jira Software instance, there will be no action required from you. The following changes apply to company-managed projects only.

A diagram displaying the current and future hierarchy in Premium and Free/Standard.

Updates to the issue view

The parent of an issue will move from appearing in the epic-link or parent-link field in the right panel, to the breadcrumb at the top, consistent with team-managed projects. Any existing epic-links will automatically move to the breadcrumb – no user action will be required.

For Jira Software Cloud Premium users, the parent-link will also move to the breadcrumb, and will no longer need issue configuration to appear.

Current experience

New experience

The old parenting experience using the Epic Link field

The old parenting experience using the Epic Link field

The old parenting experience using Parent Link field

The old parenting experience using Parent Link field

The new breadcrumb parenting experience

The new breadcrumb parenting experience

Change parent in the more (…) menu on the issue view

Change parent in the more (…) menu on the issue view

Change an issue’s parent via the more (…) menu, or by clicking View all in the breadcrumb

Change an issue’s parent via the more (…) menu, or by clicking View all in the breadcrumb

 

Updates to boards/backlogs

The board and backlog experience will not change – you will continue to see parent epics appear in the lozenge on each listed issue.

Parent epics displayed on each listed issue on the Backlog

Updates to issue create

The epic-link field and parent-link fields will be replaced by a single parent field in the issue create experience. Consistent with current functionality, you will be able to exclude 'done' issues when searching for a parent, and the issue search results will only show issues from 1 level above.

The parent field in the issue create experience

Updates to JQL, issue searches and saved searches

Now: All existing epic-link data has been copied to the new parent field – any new epic-links you create will also automatically copy across to the parent field. Users will not be able to create new JQL or issue searches using epic-link, they will be directed to use parent instead. All saved searches/JQL queries including JQL-backed boards will continue to show the same results*, adding new or editing existing epic links will result in updated results for saved searches and queries.

Essentially, anything you’ve saved will continue to work as expected, but we’ll guide you to using parent instead of epic-link for creating anything new.

A warning when selecting epic link on the board filter
A warning when adding epic link on the advanced board filter

Next:

  • In late 2022 the above changes will apply to the parent-link field as well.

  • In 2023 we will convert all existing saved JQL and issue searches containing epic-link and parent-link to parent. Search results will not be affected* and no user action will be required. More specific dates will be added here as we get closer to the update.

*There are some cases where a JQL query will return different results than previously because both epic-link and parent-link values will be copied to parent.

These updates only affect issues in company-managed projects. Issues in team-managed projects will not be affected.

The following use of the parent JQL function may return more issues, as results previously included only subtasks, but will now include all issues with an epic-link value:

  • parent is not empty

  • parent = xyz (where xyz is an epic issue)

  • parent != xyz

  • parent in (xyz, abc) (where xyz or abc is an epic issue)

  • parent not in (xyz, abc)

Recommendation: If you’re using these functions and want to continue to filter out subtasks only, use the issueType[1] field.

If you’re using parent is empty, you may notice that this query returns less issues, as results will no longer include issues that have an epic-link value. These queries will need to be manually updated based on their intended behaviour.

Updates to automation

Components

For existing automation rules, components that currently reference the Epic Link field (i.e. the Edit field, Create issue, and Clone issue actions) will continue to work.

For new automation rules, you’ll still be able to select the Epic Link field on these components, as well as the Parent field.

In all rules, if the Epic Link field is selected in these components, the rule will update the issue’s Parent field.

Smart values

The following smart values will change:

  • {{issue.epic link}} will return values if the issue’s parent is an epic.

  • {{issue.parent link}} will return values if the issue’s parent is not an epic.

  • {{issue.parent}}, previously used for subtasks only, will now return values regardless of whether the active issue is a subtask or not.

Updates to CSV import and export

The parent field will now be used when importing and exporting data into Jira via CSV.

This means that, when importing data using a CSV file, you should now map the IDs of parent issues to the new parent field in order to ensure this data is captured within Jira.

If you’re still importing epic link and parent link fields via CSV, we will prioritise the parent field when setting this value within Jira.

When exporting data to CSV, parent ID will no longer be captured for sub-tasks – only the parent field will be returned.

Impact to marketplace APIs

Marketplace vendors have been notified of these changes with 6+ months notice – see: Deprecation of the Epic Link, Parent Link and other related fields in REST APIs and webhooks

What do you have to do? Will existing epic-links be preserved?

These updates will apply automatically to your Jira Software instance, there will be no actions required from you. All your existing epic-links and parent-links will be copied to parent, any updates to epic-link and parent-link will automatically update the parent value.

FAQs

  • Are epic colors affected? You’ll still see epics with colored lozenges in boards and backlogs, there are minor changes upcoming to epic colors – learn more about these changes: Upcoming changes to epic fields in company-managed projects

  • Will I still be able to see the epic-link data after these changes are made? Yes, you'll still be able to access these fields JQL and issue search.

  • What happens to the parent value if I update the epic-link? The parent value will automatically be updated.

Need more help?

If you have any questions, add a comment here or please contact our support team.

Additional Help