Change notice: Removing hierarchy level IDs from next-gen APIs
The six-month deprecation period for these changes begins on 1 March 2021.
What is changing?
We are removing hierarchy level IDs and entityIDs from next-gen project APIs.
We are changing database structure of Jira issue type hierarchy levels and as result they will no longer exist as standalone entities and there will be no IDs to return.
There are four APIs at the moment that return these IDs:
(1) Get project hierarchy v2 + (2) Get project hierarchy v3:
- The
entityIdproperty will be removed
(3) Get project with “issueTypeHierarchy” expand v2 + (4) Get project with “issueTypeHierarchy” expand v3:
-
The following properties will be removed:
baseLevelIdidbelowLevelIdaboveLevelIdexternalUuidprojectConfigurationId
-
A new property will be added:
-
level: either 0 or -1 or 1
-
Example “Get project hierarchy” response before the change:
// {{baseUrl}}/rest/api/3/project/:projectId/hierarchy
// Before
{
"projectId": 10030,
"hierarchy": [
{
"entityId": "1342dc4e-65b3-4e90-8bc7-ed2f279bc67c",
"level": 0,
"name": "Base",
"issueTypes": [
{
"id": 10008,
"entityId": "85a70d81-23f3-4455-abe0-e54de6313f49",
"name": "Story",
"avatarId": 10324
},
{
"id": 10001,
"entityId": "2534f74e-4516-4f38-9fba-21a818ceadd7",
"name": "Bug",
"avatarId": 10324
}
]
},
{
"entityId": "90be892d-eda9-4fa2-bd7f-ccc0f599383a",
"level": 1,
"name": "Epic",
"issueTypes": [
{
"id": 10007,
"entityId": "e18f662c-d996-4852-8289-23fb7e19bed4",
"name": "Epic",
"avatarId": 10179
}
]
},
{
"entityId": "f4c8b61f-19e6-47c9-b7c4-a6ae38f1db55",
"level": -1,
"name": "Subtask",
"issueTypes": [
{
"id": 10009,
"entityId": "31768ce2-fd38-452d-82f6-27c07742ba2b",
"name": "Subtask",
"avatarId": 10573
}
]
}
]
}
Example “Get project hierarchy” response after the change:
// {{baseUrl}}/rest/api/3/project/:projectId/hierarchy
// After
{
"projectId": 10030,
"hierarchy": [
{
"level": 0,
"name": "Base",
"issueTypes": [
{
"id": 10008,
"entityId": "85a70d81-23f3-4455-abe0-e54de6313f49",
"name": "Story",
"avatarId": 10324
},
{
"id": 10001,
"entityId": "2534f74e-4516-4f38-9fba-21a818ceadd7",
"name": "Bug",
"avatarId": 10324
}
]
},
{
"level": 1,
"name": "Epic",
"issueTypes": [
{
"id": 10007,
"entityId": "e18f662c-d996-4852-8289-23fb7e19bed4",
"name": "Epic",
"avatarId": 10179
}
]
},
{
"level": -1,
"name": "Subtask",
"issueTypes": [
{
"id": 10009,
"entityId": "31768ce2-fd38-452d-82f6-27c07742ba2b",
"name": "Subtask",
"avatarId": 10573
}
]
}
]
}
Example “Get project” response before the change:
// {{baseUrl}}/rest/api/3/project/:projectIdOrKey?expand=issueTypeHierarchy
// Before
{
"expand": "description,lead,issueTypes,url,projectKeys,permissions,insight",
"self": "<self>",
"id": "10000",
// ...
"issueTypeHierarchy": {
"baseLevelId": 112,
"levels": [
{
"id": 113,
"name": "Epic",
"belowLevelId": 112,
"projectConfigurationId": 10065,
"issueTypeIds": [
11159
],
"externalUuid": "6346f176-4a80-440e-86a7-82c18d1a57e9"
},
{
"id": 112,
"name": "Base",
"aboveLevelId": 113,
"belowLevelId": 114,
"projectConfigurationId": 10065,
"issueTypeIds": [
11161,
11158
],
"externalUuid": "cfcd86f0-80d9-470e-96e4-60fe86d93844"
},
{
"id": 114,
"name": "Subtask",
"aboveLevelId": 112,
"projectConfigurationId": 10065,
"issueTypeIds": [
11160
],
"externalUuid": "daf25e8b-1a17-4745-946a-72f0f9357e23"
}
]
},
"properties": {},
"entityId": "044c6996-8305-4aae-a23f-19d825c7dc3d",
"uuid": "044c6996-8305-4aae-a23f-19d825c7dc3d"
}
Example “Get project” response after the change:
// {{baseUrl}}/rest/api/3/project/:projectIdOrKey?expand=issueTypeHierarchy
// After
{
"expand": "description,lead,issueTypes,url,projectKeys,permissions,insight",
"self": "<self>",
"id": "10000",
// ...
"issueTypeHierarchy": {
"levels": [
{
"name": "Epic",
"issueTypeIds": [
11159
],
"level": "1"
},
{
"name": "Base",
"issueTypeIds": [
11161,
11158
],
"level": "0"
},
{
"name": "Subtask",
"issueTypeIds": [
11160
],
"level": "-1"
}
]
},
"properties": {},
"entityId": "044c6996-8305-4aae-a23f-19d825c7dc3d",
"uuid": "044c6996-8305-4aae-a23f-19d825c7dc3d"
}
Level coding is:
-
1: means Epic level -
0: means Base level -
-1: means Subtask level
Why is it changing?
We are removing unused code to make Jira more maintainable.
The current database structure allows us to configure hierarchy levels individually and independently for each project, but Jira does not actually expose this feature anywhere in UI or API.
What do I need to do?
If your app is using baseLevelId : find the hierarchy with level = 0, that will be always the base.
If your app is reading aboveLevelId / belowLevelId: the relative ID mapping is replaced with absolute level.
level = 1 is “Epic” level (it has 0 or 1 Epic issue type),
level = -1 is “Subtask” level (it has 0 or 1 Subtask issue type),
level = 0 is “Base” level (it has all the other issue types, minimum of 1).
If your app is reading id or entityId or externalUuid:
these will no longer exist and will be replaced by global, static, and hardcoded objects of 3 standard hierarchy levels.
Either update your app to consider the hierarchy levels global scope, or generate IDs to keep storing them in project scope.
It is safe to drop the IDs without replacement because the hierarchies won’t change between projects.
It is safe to assume that the -1/0/1 <> Subtask/Base/Epic mapping will be stable.
In the future there may be new levels below or above.
If your application only works with classic projects, there is nothing to do because there will be no changes.
The above only applies to next-gen projects.
By when do I need to do it?
First, we will add the new level property to APIs (3) and (4):
Get project with issueTypeHierarchy expand, and return it together with the old id, entityId, entityUuid, baseLevelId, aboveLevelId and belowLevelId.
This will happen on or before 1 March, 2021.
Then, 6 months after that change, Jira APIs will stop returning: id, entityId, entityUuid, baseLevelId, aboveLevelId, belowLevelId, and projectConfigurationId.
This will happen on or after 1 September, 2021.
