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 Linkfield:
"fields": {
...
"customfield_10014": "ABC-1",
...
}
- Example of the
Parent Linkfield:
"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
epicfield (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
parentfield:
"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:
- Create issue
- Bulk create issue
- Update issue
Deprecated behavior: For issues in company-managed projects, stop providing the Epic Link and Parent Link fields.
- Example of usage of the
Epic LinkorParent Linkfields:
"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
parentfield:
"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
typeparameter:
{
...
"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
hierarchyLevelparameter:
{
...
"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 Linkfield:
"fields": {
...
"customfield_10014": "ABC-1",
...
}
- Example of the
Parent Linkfield:
"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
epicfield (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
parentfield:
"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_storywebhook 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_subtaskwebhook 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_updatedwebhook 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 Linkchangelog item (the changelog item forParent Linkis similar):
"items": [
...,
{
"field": "Epic Link",
"fieldtype": "custom",
"fieldId": "customfield_id",
"from": "1234",
"fromString": "ABC-1",
"to": "4567",
"toString": "ABC-2"
},
...
]
- Example of the
Parentchangelog 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
IssueParentAssociationchangelog 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:
- GET /rest/api/3/issue/createmeta
- GET /rest/api/2/issue/createmeta
- GET /rest/api/3/issue/{issueIdOrKey}/editmeta
- GET /rest/api/2/issue/{issueIdOrKey}/editmeta
Deprecated behavior: For issues in company-managed projects, stop consuming the Epic Link and Parent Link fields.
- Example of usage of the
Epic LinkorParent Linkfields:
"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
parentfield:
"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:
- Deprecation of fields values Epic Link and Parent in issue history changelogs
- Removing hierarchy level IDs from Jira cloud platform APIs
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.
