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.