Deprecation of fields values Epic Link and Parent in issue history changelogs

What is changing?

We’re deprecating the Epic Link and Parent values returned in field in issue history changelogs for company-managed projects (previously known as classic projects). These values will be replaced with IssueParentAssociation , a value used in team-managed projects (previously known as next gen projects). IssueParentAssociation will be the new source of truth in the issue history changelogs for information about issue reparenting, that is, changing epic links and subtask parents.

This change impacts all issue operations and webhooks that return changelogs. For an exhaustive list of the deprecations and what it impacts, see the official deprecation notice Deprecation notice: Issue changelogs for issue parenting.

During the deprecation period, the Epic Link and Parent values will be returned alongside IssueParentAssociation in order to facilitate migration.

Examples

For changelog items for updates to the Epic Link field of issues, instead of returning:

"items": [
  ...,
  {
    "field": "Epic Link",
    "fieldtype": "custom",
    "fieldId": "customfield_id",
    "from": "1234",
    "fromString": "ABC-1",
    "to": "4567",
    "toString": "ABC-2"
  },
  ...
]

we will return:

"items": [
  ...,
  {
    "field": "IssueParentAssociation",
    "fieldtype": "jira",
    "from": "1234",
    "fromString": "ABC-1",
    "to": "4567",
    "toString": "ABC-2"
  },
  ...
]

For changelog items for subtask re-parenting, instead of returning:

"items": [
  ...,
  {
    "field": "Parent",
    "fieldtype": "jira",
    "from": null,
    "fromString": null,
    "to": "1234",
    "toString": "ABC-1"
  },
  ...
]

we will return:

"items": [
  ...,
  {
    "field": "IssueParentAssociation",
    "fieldtype": "jira",
    "from": null,
    "fromString": null,
    "to": "1234",
    "toString": "ABC-1"
  },
  ...
]

Why is Atlassian making this change?

Atlassian is standardizing reparenting of issues across the Jira products. This means we are changing our underlying data model so that all issue parenting goes through one common code path. As a result we are also consolidating the values Epic Link and Parent that appear in issue history changelogs. This is just one of the many changes we have been making around issue type hierarchy, with more to come. For prior deprecations relating to this, see:

What do I need to do?

If your app is dependent on the Parent and Epic Link values in the changelogs of issues, please migrate and consume IssueParentAssociation instead.

We will facilitate this migration by returning changelog items for both the old and new values for each reparenting update during the deprecation period.

By when do I need to do it?

First, we will return IssueParentAssociation in addition to existing changelog items for each reparenting update starting on or before 10 June 2021 . We will ceased to return issue history changelog items containing the Epic Link and Parent values on 10 December 2021 .

Hi @Hayden ,
Could you please share a link to the announcement of deprecation for the hierarchy level changes (on CDAC)? I couldn’t find an announcement for that deprecation (which is a bigger change than the changelog change)
Thanks
David

2 Likes

Hi @david2,
Apologies for the delayed response and your patience while we have been investigating this. It does indeed look like we have missed an announcement post for that related deprecation.

After reviewing that deprecation in more depth, I believe that we also have some missing information for one of the APIs we have listed on there. As a result, we will provide more detail on the existing deprecation and also provide a proper announcement to the community once this has been finalised.

Stay tuned for this in the coming weeks!

Thanks,
Hayden

1 Like

@Hayden Can you confirm that the IssueParentAssociation item is being returned in the changelog at this moment?

I only get the ‘Epic Link’ item when I change the ‘Epic Link’ of an issue:

items: [
    {
      field: 'Epic Link',
      fieldtype: 'custom',
      fieldId: 'customfield_10014',
      from: '11165',
      fromString: 'ADC-1',
      to: null,
      toString: ''
    }
  ]

It’s also worth mentioning that webhooks have never been fired when the ‘Parent’ field is changed. This has been a bug for a long time and still appears to be the case. See ACJIRA-2088.

Cheers

Hi @RhysDiab,
You should be seeing both changelog items now. Could you provide some additional details i.e. what API are you using to fetch the changelogs?

Thanks for highlighting the bug on the webhooks for the ‘Parent’ field. We already have this on our roadmap to be fixed as part of this stream of work.

Cheers

You should be seeing both changelog items now. Could you provide some additional details i.e. what API are you using to fetch the changelogs?

The changelog items are sent in the body of the request when the jira:issue_updated webhook is called. At the moment only the ‘Epic Link’ item is present.

Thanks for highlighting the bug on the webhooks for the ‘Parent’ field. We already have this on our roadmap to be fixed as part of this stream of work.

All good. I like the way this change simplifies parent-child relationships across company and team managed projects.

The work to fire the webhook when the Parent field is changed is currently in development. Once this is completed you will see the IssueParentAssociation item being returned in the webhook changelog (you will continue to get an event containing the change of the Epic Link as well).

I will let you know when this has been rolled out, and we will update our deprecation notice to reflect this information too.

1 Like

@Hayden - will the issue.fields values for epicLink and parent change as well in the foreseeable future? (not changelog, just the regular returned fields)

Hi @ernst.stefan,
Yes, in the foreseeable future this will likely be changing as well. We will make a seperate announcement for this change given that it’s going to be more impactful.

For this change - if somebody is consuming Epic Child in the actual Epic - will that change?

1 Like

Hi @danielwester, thanks for your question. We will be removing the Epic Child changelog behaviour in future, so we recommend apps to move away from consuming this.

We are working on a large deprecation announcement covering this topic and many others relating to re-parenting issues. This will be available in the near future, so stay tuned for this announcement.

@Hayden There is no fieldId in provided example of Epic Link’s new changelog item version. Does that mean we can treat the “field”: “IssueParentAssociation” property as id?

Hi @mklempka, thanks for your question, and welcome to the Community!

Yes, you can treat “field”: “IssueParentAssociation” as an identifier.

Technically, the IssueParentAssociation changelog items do not have fieldId.
Consumers should not use fieldId for the IssueParentAssociation changelog items.

Hi @KonstantinK ,
using the field name as an identifier is not clean at all. What if Atlassian decides to change that name later?
Why not use the fielded field to contain a meaningful ID? That would be more robust.

Hi @david2,
I understand your concern regarding fieldId here.

Technically, IssueParentAssociation is not a custom field, so unlike Epic Link it doesn’t have an ID of the format like “customfield_10014”. For IssueParentAssociation, fieldId is empty.

Note that having an empty fieldId is already the case for some existing fields in Jira (for example, the Link field changelog API representation in Jira Issue View).

IssueParentAssociation is a system entity name, and it cannot be changed by the admin or user. At the moment, we do not plan to change this name in the code and API as well. Consumers are encouraged to rely on IssueParentAssociation to identify this particular changelog item.

Thanks for your question!

@Hayden any update on the wider deprecation announcement for hierarchy levels? https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-hierarchy-levels/ states that the changes will go in effect on November 1st, but we have no place to ask questions about the changes. You said 2 months ago that a proper announcement on the community would be made, I think it’s time, unless the deadline is going to be pushed back.

Thanks,
David

Hi @david2,

We have an announcement in the works which includes the changes from deprecation-notice-hierarchy-levels, webhooks and further changes surrounding our theme of hierarchy unification in Jira Cloud. These are effectively going to be combined into one announcement given they are all related.

Given that the changes mentioned in deprecation-notice-hierarchy-levels will be included in another announcement, we will be providing the typical deprecation period of 6 months, which will extend to everything inside it. This means consumers will get plenty of time to ask questions and make the required changes from those within the mentioned deprecation notice along with the new deprecations.

The only changes mentioned in deprecation-notice-hierarchy-levels that will not be included in the subsequent announcement are the changes to project GET and PUT APIs. The reason for this is that they have already been deprecated and announced on CDAC prior to the deprecation-notice-hierarchy-levels announcement (they were actually duplicated into the most recent one), so the deprecation date on those project APIs still stand.

Let me know you have any concerns with this.

Thanks,
Hayden

2 Likes

Thanks @Hayden for the clarification, sounds great!
David

1 Like

Hi @Hayden

I have a couple of questions.

  1. Will we be able to use the new IssueParentAssociation field to query Epic children using IssueParentAssociation = key instead of 'Epic Link' = key OR parent = key? This would be a great addition as many users have created an extra field named ‘Epic Link’ in their instances which causes queries using this field to fail.

  2. Any update on when the jira:issue_updated event will return the IssueParentAssociation field? December 10th is fast approaching and I’m still only seeing the item with the ‘Epic Link’ field when this event is called.

Thanks again.

1 Like

Hi @RhysDiab,

To answer your first question, we are building a new JQL clause in the future to consolidate the various methods of querying for children or parents - it will make use of the data model that supports the IssueParentAssociation field. I can’t provide too much detail on exactly how this may function, but we will provide more details in our future announcements when the time comes.

To answer your second question, the deadline for changelog migration in webhooks will be shifted to the new announcement I mentioned in my previous response - this means the deprecation period for changelogs in webhooks will be extended in order to provide sufficient time for consumers to migrate. Keep in mind that this is only for webhooks, and does not include anything else to do with changelogs in this announcement.

Information on whats expected of consumers when migrating will be detailed in the upcoming announcement, which you can expect to see in the near future.

Let me know if this answers your questions.

Thanks,
Hayden

1 Like