Deprecation of the Epic Link, Parent Link and other related fields in REST APIs and webhooks

What is changing?

Atlassian is standardizing how we associate parent and child issues across Jira for company-managed and team-managed projects. This results in deprecation of the Epic Link and Parent Link custom fields in REST APIs and webhooks, as well as in some other related changes.

Please refer to the detailed change list below:

Change 1 (Jira public API):

Endpoints: All API endpoints that return issues with their fields.

Deprecated behavior: For issues in company-managed projects, stop consuming the Epic Link, Parent Link, or epic fields.

  • Example of the Epic Link field:
"fields": {
  ...
  "customfield_10014": "ABC-1",
  ...
} 
  • Example of the Parent Link field:
"fields": {
  ...
  "customfield_10018": {
            "hasEpicLinkFieldDependency": false,
            "showField": true,
            "data": {
                "id": 10001,
                "key": "ABC-1",
                "keyNum": 1,
                "summary": "issue 1",
                "projectId": 10001,
                "issueType": {
                    "id": "10001",
                    "iconUrl": "/secure/viewavatar?size=medium&avatarId=10001&avatarType=issuetype"
                }
            },
  ...
}
  • Example of the epic field (please note that this field may not be present in all API responses):
"fields": {
  ...
  "epic": {
      "id": 10001,
      "key": "ABC-1",
      "self": "https://{your_jira_site}/rest/agile/1.0/epic/10001",
      "name": "epic",
      "summary": "epic",
      "color": {
          "key": "color_1"
      },
      "done": false
  },
  ...
}

New behavior: For issues in company-managed projects, consume the parent field.

  • Example of the parent field:
"fields": {
  ...
  "parent": {
            "id": "10097",
            "key": "ABC-1",
            "self": "https://{your_jira_site}.com/rest/api/3/issue/10097",
            "fields": {
                ...
            }
        },
  ...
}

Change 2 (Jira public API):

Endpoints: Public API endpoints that create or update issues:

Deprecated behavior: For issues in company-managed projects, stop providing the Epic Link and Parent Link fields.

  • Example of usage of the Epic Link or Parent Link fields:
"fields": {
  ...
  "customfield_10014": "ABC-1",
  ...
}

New behavior: For issues in both company-managed and team-managed projects, provide the parent field (where applicable) for issues of all types.

  • Example of usage of the parent field:
"fields": {
  ...
  "parent": {
      "id": "10055"
  }
  ...
}

Change 3 (Jira public API):

Endpoints: Public API endpoints that create issue types:

Deprecated behavior: stop providing the type parameter.

  • Example of usage of the type parameter:
{
  ...
  "type": "standard"
  ...
}

New behavior: provide the hierarchyLevel parameter. Documentation for this parameter can be found at The Jira Cloud platform REST API.

  • Example of usage of the hierarchyLevel parameter:
{
  ...
  "hierarchyLevel": 0
}

Change 4 (Webhooks in Jira):

Webhook events: All webhook events where the payload includes issues with their fields.

Deprecated behavior: For issues in company-managed projects, stop consuming the Epic Link, Parent Link, or epic fields in the webhook payload.

  • Example of the Epic Link field:
"fields": {
  ...
  "customfield_10014": "ABC-1",
  ...
} 
  • Example of the Parent Link field:
"fields": {
  ...
  "customfield_10018": {
            "hasEpicLinkFieldDependency": false,
            "showField": true,
            "data": {
                "id": 10001,
                "key": "ABC-1",
                "keyNum": 1,
                "summary": "issue 1",
                "projectId": 10001,
                "issueType": {
                    "id": "10001",
                    "iconUrl": "/secure/viewavatar?size=medium&avatarId=10001&avatarType=issuetype"
                }
            },
  ...
}
  • Example of the epic field (please note that this field may not be present in the webhook payload):
"fields": {
  ...
  "epic": {
      "id": 10001,
      "key": "ABC-1",
      "self": "https://{your_jira_site}/rest/agile/1.0/epic/10001",
      "name": "epic",
      "summary": "epic",
      "color": {
          "key": "color_1"
      },
      "done": false
  },
  ...
}

New behavior: For issues in company-managed projects, consume the parent field.

  • Example of the parent field:
"fields": {
  ...
  "parent": {
            "id": "10097",
            "key": "ABC-1",
            "self": "https://{your_jira_site}.com/rest/api/3/issue/10097",
            "fields": {
                ...
            }
        },
  ...
}

Change 5 (Webhooks in Jira):

Webhook events: The issuelink_created and issuelink_deleted webhook events where style is jira_gh_epic_story or jira_subtask.

Deprecated behavior: stop consuming the issuelink_created and issuelink_deleted webhook events where style is jira_gh_epic_story or jira_subtask .

  • Example of the jira_gh_epic_story webhook payload:
{
  "timestamp": 1634019576855,
  "webhookEvent": "issuelink_created",
  "issueLink": {
    "id": 10117,
    "sourceIssueId": 10096,
    "destinationIssueId": 10088,
    "issueLinkType": {
      "id": 10005,
      "name": "Epic-Story Link",
      "outwardName": "is Epic of",
      "inwardName": "has Epic",
      "style": "jira_gh_epic_story",
      "isSubTaskLinkType": false,
      "isSystemLinkType": true
    },
    "systemLink": true
  }
}
  • Example of the jira_subtask webhook payload:
{
  "timestamp": 1634020907890,
  "webhookEvent": "issuelink_created",
  "issueLink": {
    "id": 10118,
    "sourceIssueId": 10060,
    "destinationIssueId": 10118,
    "issueLinkType": {
      "id": 10004,
      "name": "jira_subtask_link",
      "outwardName": "jira_subtask_outward",
      "inwardName": "jira_subtask_inward",
      "style": "jira_subtask",
      "isSubTaskLinkType": true,
      "isSystemLinkType": true
    },
    "sequence": 10,
    "systemLink": true
  }
}

New behavior: ignore the issuelink_created and issuelink_deleted webhook events where style is jira_gh_epic_story or jira_subtask .

Instead, consume the parent field from the jira:issue_created or jira:issue_updated events.
Consume the parent/child relationships changes from the jira:issue_updated events’ changelog.

  • Example (partial) of the changelog in the jira:issue_updated webhook payload:
{
  "webhookEvent": "jira:issue_updated",
  "issue_event_type_name": "issue_updated",
  ...
  "changelog": {
    "id": "10549",
    "items": [
      {
        ...
      }
    ]
  }
}

Note: We’re not deprecating the events issuelink_created and issuelink_deleted . We’re only deprecating the style jira_gh_epic_story or jira_subtask .
All other styles of this event can still be consumed.


Change 6 (Webhooks in Jira):

Webhook events: All webhook events where the payload includes the issue changelog.

Deprecated behavior: stop consuming the Epic Link, Parent Link, and Parent changelog items in the issue webhook payload.

  • Example of the Epic Link changelog item (the changelog item for Parent Link is similar):
"items": [
  ...,
  {
    "field": "Epic Link",
    "fieldtype": "custom",
    "fieldId": "customfield_id",
    "from": "1234",
    "fromString": "ABC-1",
    "to": "4567",
    "toString": "ABC-2"
  },
  ...
]
  • Example of the Parent changelog item:
"items": [
  ...,
  {
    "field": "Parent",
    "fieldtype": "jira",
    "from": null,
    "fromString": null,
    "to": "1234",
    "toString": "ABC-1"
  },
  ...
]

New behavior: consume the IssueParentAssociation changelog entry for all issue parent updates in webhooks. This changelog entry represents the same thing as Epic Link, Parent Link, or Parent.

Note that only the base level issues will get this changelog. The epic will no longer get the Epic Child changelog

  • Example of the IssueParentAssociation changelog item:
"items": [
  ...,
  {
    "field": "IssueParentAssociation",
    "fieldtype": "jira",
    "from": null,
    "fromString": null,
    "to": "1234",
    "toString": "ABC-1"
  },
  ...
]

Update (7 October 2022):

In order to give our Marketplace partners a better experience in testing Change 6, we decided to change the rollout plan for it to return both OLD and NEW changelog items in the SAME webhook event. Originally we announced that we would only return either OLD or NEW changelog.


Change 7 (Jira public API):

Endpoints: create and update issue metadata endpoints:

Deprecated behavior: For issues in company-managed projects, stop consuming the Epic Link and Parent Link fields.

  • Example of usage of the Epic Link or Parent Link fields:
"customfield_10014": {
    "required": false,
    "schema": {
        "type": "any",
        "custom": "com.pyxis.greenhopper.jira:gh-epic-link",
        "customId": 10014
    },
    "name": "Epic Link",
    "key": "customfield_10014",
    "operations": [
        "set"
    ]
},
"customfield_10018": {
    "required": false,
    "schema": {
        "type": "any",
        "custom": "com.atlassian.jpo:jpo-custom-field-parent",
        "customId": 10018
    },
    "name": "Parent Link",
    "key": "customfield_10018",
    "operations": [
        "set"
    ]
},

New behavior: For issues in both company-managed and team-managed projects, consume the parent field (where applicable) for issues of all types.

  • Example of usage of the parent field:
"parent": {
    "required": false,
    "schema": {
        "type": "issuelink",
        "system": "parent"
    },
    "name": "Parent",
    "key": "parent",
    "hasDefaultValue": false,
    "operations": [
        "set"
    ]
},

Note. This is an additional change we’ve added in response to the Developer Community feedback. It will be rolled out to all instances between March and May 2022.


Scope

These changes apply to and are limited to Jira’s REST APIs and webhooks.
There will be no changes to the Jira UI. There will be no changes to JQL.

Why is it changing?

There are several ways of representing parent and child issue associations that have to be reconciled when developing tools for the Jira product range. Standardizing on one makes it easier to develop tools and integrate products. This simplification will help us create and roll out new features to customers faster.

For prior deprecations relating to this, see:

What do I need to do?

Plan to migrate away from the deprecated behavior and start using the new behavior.

During the 12-month deprecation period (30 Nov 2021 - 30 Nov 2022), both old and new behavior will be present, so you can begin testing your new code immediately. If you encounter any issues or have questions, please respond to this post.

By when do I need to do it?

Please start immediately reviewing the changes and planning to incorporate them into your app to give yourself the maximum opportunity for a smooth transition.

The new behavior is now available in all Jira Cloud instances.

The deadline is 30 November 2022. At any point after it, the old behavior may be switched off.

Note. We’ve extended the grace period for the old behavior, so both old and new behavior will be supported until 30 Nov 2022 (previously was 31 May 2022). We will update this notice if further extensions of the grace period are required.


FAQ

Are all of these new fields and events already available in production?

Yes, all production Jira instances now support all of these new fields and events. They are ready to be used.

What will happen on 30 November 2022?

This is the deadline for the users of the public API to start using the new fields and events. We will not remove the old fields on that day, but we may do it at any point after it. We will use our monitoring to track the adoption of the new fields, and once it indicates that the old fields are not being actively used, we will remove them.

Before disabling these deprecated fields for production customers, we will disable these fields for the Early Adopters / Ecosystem Beta Group, and we will allow them enough time to test their apps with the deprecated fields disabled. We will post a comment in this post when we are ready to disable these fields for the Early Adopters / Ecosystem Beta Group.

Will my Jira Automation rules that depend on the deprecated fields continue working after 30 November 2022?

Atlassian plans to migrate the affected smart values by 30 November 2022 so that Automation rules won’t break. If there are any edge cases we’re unable to migrate, we’ll communicate this closer to the time.

Will Epic Link or Parent Link be removed from JQL?

No. Also, we will add full company-managed project support to the parent JQL, and it will become the recommended way of searching for issue’s children in JQL. Read our Community announcement about it.

Note that all changes to JQL (including the full support for parent JQL) are out of the scope of this notice and will be released separately.

Will Epic Link or Parent Link be removed from the Jira issue view?

This is out of the scope of this deprecation. Though, we’re planning to replace it with a new “Add parent” feature. The dates from this deprecation notice are not applicable to any UI change. For details, please see our Community announcement about it.

Will Epic Link or Parent Link be removed from the “/rest/api/3/field” endpoint?

No. The “Get fields” endpoint ( GET /rest/api/3/field ) will continue returning these fields.

Does this deprecation apply to our Server or Data Center products?

No. This change is only for Jira Cloud.

What will happen to the “Epic Name“ and “Epic Color“ fields?

We will not remove these fields. You can still consume them, but only as custom fields. Note that the epic property which now contains them is being deprecated and will be removed on 30 November 2022 (see Change 1 in this notice).

As we’ve announced in Community, in company-managed project epics in Jira we’ll use Issue Color instead of Epic Color , and Summary instead of Epic Name . This is the current TMP behavior. Once we release this for company-managed projects in Jira, we encourage our partners to make a similar change. There is no deadline for it.

Have there been any changes to Jira Expressions?

Jira Expressions is out of the scope of this notice. We’re not deprecating or removing anything from Jira Expressions at this stage.

In late 2022, we’re adding the parent field for company-managed project issues above subtasks to Jira Expressions, to unify the experience with TMP issues. See the changelog for details.

What if I use the Advanced Roadmaps hierarchy, or want to rename Epic to Feature, or want to add a hierarchy level above Epic?

Currently, in the public API response, the issuetype 's hierarchyLevel property only supports the following values: -1 , 0 , or 1 . It ignores the Advanced Roadmaps hierarchy.

We’re currently working on moving the Advanced Roadmaps hierarchy configuration to Jira. This will allow for renaming Epic and (for Premium instances) creating hierarchy levels above it. Also, the hierarchyLevel property will support all levels, including those greater than 1. Read our Community announcement about it.

What if my question is not answered here?

Search through the comments in this thread. If you need additional help, please reach out to our Support team. If you think your question will also benefit other Community members, create a new topic in the Developer Community.

13 Likes

So, Epic Name becomes useless, too (at least for our use case).

Thank you @KonstantinK for the detailed explanation of the changes. I agree that harmonizing the various “parent” relations makes sense. Now I only wished that Jira Server/DC is changing in the same way :upside_down_face:

I have one question though about Change 6. Can you elaborate why you are not also adding the new changelog entry there now as well? I’d like to test that our app works fine and not just hope that the implementations hopefully match on 31 May 2022.
Having said that, am I right that the GET /rest/api/3/issue{issueIdOrKey}?expand=changelog endpoint will return the new format? If yes, we could use that one for verifying that the behaviour works.

Cheers,
Matthias.

4 Likes

Hello @KonstantinK,
Thanks a lot for sharing those details. It will make Epics/Initiatives etc. much easier to work with across team- and company-managed projects.

Could you please share the following exact dates once they are known?

  • When do the first customers outside the Jira Ecosystem beta group see these changes? (Note that this can already break apps, e.g. if both “Epic Link” and “Parent” fields are visible)
  • When is the rollout of the new behavior to all customers complete?

Thanks!

1 Like

Hi @KonstantinK ,
while all this makes perfect sense, it creates a fairly major risk: what about customers of Automation apps (such as JMWE, JSU, ScriptRunner, etc.) that wrote automations that depend on the Parent Link or Epic Link fields, or on the issuelink_created and issuelink_deleted webhook events?

While app vendors are (or should be) watching this space, and thus can adapt their apps to these changes by the deadline, regular Jira customers won’t hear about these changes before they break their automations. And as you know, app vendors have very limited means of communicating with their customers (only a single “technical contact” email which is often obsolete) so we can’t communicate these changes to our customers.

Any thoughts?

Thanks,
David

4 Likes

Hi @OndejMedek,
while at this stage we’re not planning to remove Epic Name, we will be moving away from using the Epic Name in views to using the Issue Summary so that Company Managed projects are consistent with Team Managed projects.

Thanks,
Konstantin

Hi @BenRomberg, thanks for your feedback!

Changes 2 and 3 have already been fully rolled out, as these create/update operations cannot affect the Marketplace apps.

Currently, we’re planning to start rolling out all other changes to everyone around 15 December 2021, just to give enough time for our partners here at Developer Community to react to this announcement. This date is flexible and may be pushed back if there’s an internal need for it. The rollout might take from one to several weeks as we’ll be closely monitoring it to avoid any regressions.

Of course, if there’s evidence that rolling out the parent field (with Epic Link, Parent Link and epic still present) as per the announcement will break some Marketplace apps, we may re-consider these dates.

Please let us know if this will break your (or any other) Marketplace app.

Thanks,
Konstantin

Hi @david2, that’s a good point, and we’ve also thought of how we can make this announcement more visible.

For Jira admins (and other users who’re not app vendors) we’ve posted this article on Atlassian Community.

We also plan to post this deprecation notice at Jira Cloud platform.

If you have any suggestions on how to make this more visible, feel free to share with us and we’ll consider them.

Thanks,
Konstantin

Hi @matthias, this is a great question.

First of all, I confirm that the GET /rest/api/3/issue{issueIdOrKey}?expand=changelog endpoint will return the new format (same as what we’ll return in webhooks), so you can use it for testing your changes. The only difference is that the REST API returns both old and new changelog entries, but in the webhooks, we are just going to show the new entry in the final state.

This rollout plan for Change 6 was a trade-off between the complexity of the changes consumers potentially need to make to read basically the same changelog entry with a different name versus managing both old and new changelog items in one webhook.

From these examples we see that both IssueParentAssociation and Epic Link changelog entries have the same format, except for the IssueParentAssociation entry not having the fieldId attribute, and having a different value in fieldtype. Also, the IssueParentAssociation is issue type agnostic, which means that this changelog entry cannot be used to determine if the parent is Epic, Base level, or any other type.

When it comes to Parent vs IssueParentAssociation, the format is identical.

So the only change we expect most consumers to make is just to change the field value from Epic Link/Parent to IssueParentAssociation, and it should just work (unless the consumer relies on fieldId or fieldtype).

We encourage consumers to write their code, such that it can work with both old and new changelog entries.

Please let me know if you have any concerns about this (or if you rely on fieldId and fieldtype in your Epic Link consumer). We’ve made this decision based on feedback from the internal consumers, but we’re keen to hear what our partners think about it.

Thanks,
Konstantin

Hi, @KonstantinK!
Thanks for the update.

Now we have faced the case when “parent” field is absent for sub-task in the REST API for searching issues /rest/api/3/search? So we can not build the issues hierarchy in this case at all.

Currently, we have only one client with this behavior and that breaks our app… Can you please help with weird behavior?

Thanks!

Hi @anton2, thanks for letting us know about this problem!

I’ve checked that, and I couldn’t reproduce this on my instance - I’m still seeing the parent field for subtasks in this endpoint’s response. Also, the customer you mentioned wouldn’t have the new behavior from this deprecation notice unless they are in the Jira Ecosystem beta group.

I think it’s possible that this might be a bug, but it’s not related to the changes from this deprecation notice. I’ll post here if otherwise.

At this stage, I suggest you raise a Support ticket for this, so we have all the details on the affected instance (e.g. cloudID ). Please mention me (Konstantin Kulishenkov) on that ticket (or send me a link to it once created via direct messages), so I can assist with the investigation.

Thanks,
Konstantin

2 Likes

I confirm that this problem is not related to the deprecation notice, or to the new functionality for it, which we’ve enabled for the Jira Ecosystem beta group.

Instances that are part of the Jira Ecosystem beta group can still safely use the new functionality (the parent field for CMP, and all other features mentioned in the notice).

2 Likes

Hi @KonstantinK,

I understand that these changes affect the Jira Cloud REST API, do you plan to apply them to the Jira Server/DC REST API as well?

If so, from what version of Jira Server/DC would they apply?
Do you have approximate dates of when versions will be available to test?

Our apps are available for the Cloud and Server/DC platform, so we will need Jira Server/DC versions to test the changes.

Thanks.
Regards,
David.

Hi @dortiz,

The change described in this notice is for Cloud only. We’re not planning to add this to Server/DC.

Thanks,
Konstantin

@KonstantinK

  • Epic Name is still mandatory, is it possible to make it optional? (E.g. make default value same as Summary.)
  • Jira API does not return parent field for GET /rest/api/3/issue/{issueIdOrKey}
  • Jira UI does not show Epic summary and icon in the breadcrumbs of a user story issue under an epic.

Hi @OndejMedek,

  1. We plan on making the Epic Name field optional, and the issue summary will remain mandatory consistent with all other issues types. This has not yet been implemented, but we plan to do it.
  2. It might be possible that the “parent” field change hasn’t yet been rolled out to your instance. I’ve sent you a direct message to confirm the details and look into it further. So far, the Jira Ecosystem Beta instances and the Early Adopters instances have the “parent” field change.
  3. I confirm that this is not related to the changes from this deprecation notice. This is a known bug, and it’s expected to be fixed at some point in 2022.

Thanks,
Konstantin

1 Like

Hi @KonstantinK,

I don’t know if anything has already been said about it, but I haven’t seen anything about it. I have a couple of doubts:

  1. Will the services that return the hierarchyLevel field take into account the roadmap hierarchy?
    For example,
    I have the following hierarchy roadmap

The services /rest/api/x/issue or /rest/api/x/issuetype return hierarchyLevel = 0

  1. Can the children of epics or the roadmap hierarchy be obtained through the parent field? Right now the parent field does not return them.

Thanks a lot.
Regards,
David.

3 Likes

Hi @dortiz, thanks for your detailed message.

We’ve been working on unifying hierarchy in Jira, and this API deprecation is just a part of it. Once this entire unification project is done, both of the examples you’ve given will show the behavior you’ve described. Historically it wasn’t working this way, and now we’re introducing this behavior.

  1. We’ve started working on getting the hierarchyLevel field to take into account the configurable hierarchy from Advanced Roadmaps. At the moment this hierarchy is applicable to Advanced Roadmaps only, so that’s why from Jira’s perspective, hierarchyLevel is 0. We’re working on brining this to Jira, so changes in the hierarchy configuration will take effect throughout Jira, including the hierarchyLevel field. I believe we’ll announce it separately.
  2. Currently the JQL parent doesn’t support that, but again we’re working on unifying this experience, so eventually JQL parent will return the same issues as Epic Link from your example.

This new behavior can be expected at some point in 2022.

Thanks,
Konstantin

2 Likes

Hi @KonstantinK,

thanks for your answer.

Will these changes be available as of 31 May 2022?
Our applications would need that functionality, especially jql’s queries with “Epic Link” and “Parent Link”. Since these fields will not be available from the mentioned date, our apps could stop working if there is no way to collect the issues of an epic or a roadmap level.

Thanks,
David.

Hi @dortiz, as it’s stated in this deprecation announcement regarding its scope:

These changes apply to and are limited to Jira’s REST APIs and webhooks.
There will be no changes to the Jira UI. There will be no changes to JQL.

So the fields Epic Link and Parent Link will remain in JQL after May, 31 and onwards, and you’ll be able to keep using them. These fields will only be removed from the API.

I know this can be a bit confusing, so we made it clear in the announcement. The reason for this is that the JQL implementation of all these fields is different from API, and they are being tackled separately. As I said before, I believe that the JQL changes will be announced separately once they’re made.

And thanks for your patience while waiting for all these changes - we think that unifying hierarchy will eventually make it easier to develop and maintain apps using Jira API :slightly_smiling_face:

Thanks,
Konstantin