Last updated Dec 13, 2024

Deprecation notice - field 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. During the deprecation period, the Epic Link and Parent values will be returned alongside IssueParentAssociation in order to facilitate migration.

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.

Which operations are effected?

Jira Software Cloud REST API

OperationMethodEndpointScopeImpact
Get issues without epic for boardGET/rest/agile/1.0/board/{boardId}/epic/none/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get board issues for epicGET/rest/agile/1.0/board/{boardId}/epic/{epicId}/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get issues for boardGET/rest/agile/1.0/board/{boardId}/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get board issues for sprintGET/rest/agile/1.0/board/{boardId}/sprint/{sprintId}/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get issues without epicGET/rest/agile/1.0/epic/none/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get issues without epic for boardGET/rest/agile/1.0/epic/none/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get issues for epicGET/rest/agile/1.0/epic/{epicIdOrKey}/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get issueGET/rest/agile/1.0/issue/{issueIdOrKey}ResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Get issues for sprintGET/rest/agile/1.0/sprint/{sprintId}/issueResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.

Jira Cloud Platform REST API v3

OperationMethodEndpointScopeImpact
Get change logsGET/rest/api/3/issue/{issueIdOrKey}/changelogResponseThe changelog items returned in the values body.
Get issueGET/rest/api/3/issue/{issueIdOrKey}ResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Search for issues using JQLGET/rest/api/3/searchResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Search for issues using JQLPOST/rest/api/3/searchResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.

Jira Cloud Platform REST API v2

OperationMethodEndpointScopeImpact
Get change logsGET/rest/api/3/issue/{issueIdOrKey}/changelogResponseThe changelog items returned in the values body.
Get issueGET/rest/api/2/issue/{issueIdOrKey}ResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Search for issues using JQLGET/rest/api/2/searchResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.
Search for issues using JQLPOST/rest/api/2/searchResponseThe changelog items returned in the changelog/histories body when including the expand=changelog query parameter.

Does this deprecation affect webhooks?

No, webhooks are not included in this deprecation. This is because changelogs items in Jira webhooks provide access to field values Epic Link and Parent, and the deprecation of changelogs items in Jira webhooks has been announced as part of Deprecation of the Epic Link, Parent Link and other related fields in REST APIs and webhooks.

Rate this page: