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"
  },
  ...
]

Note: The rollout plan for this deprecation to the webhook changelogs (Change 6) is different from all other deprecations on this page.

  • Until 31 May 2022, only the old changelog entry will be returned.
  • Consumers should write their code, such that it can work with both old and new changelog entries.
  • On 31 May 2022 we will stop returning the old changelog entry, and start returning the new one.

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 6-month deprecation period (30 Nov 2021 - 31 May 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 has been rolled out to the Jira Ecosystem beta group on 30 Nov 2021. It will be progressively rolled out to all Jira instances by January 2022.

If you don’t observe the new behavior on your Jira Cloud instance, please reach out to the author of this post to have the new behavior enabled for your instance.

Update: the new functionality is planned to be fully rolled out to all Jira Cloud instances during the week of 10 January 2022.

The hard deadline is 31 May 2022 at which time the old behavior will be switched off.​

9 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

3 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 @ben2, 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.

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

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