We are removing hierarchy level IDs and entityIDs from team-managed 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:
entityId property will be removed(3) Get project with “issueTypeHierarchy” expand v2
The following properties will be removed:
baseLevelIdidbelowLevelIdaboveLevelIdexternalUuidprojectConfigurationIdA new property will be added:
level: either 0 or -1 or 1Example “Get project hierarchy” response before the change:
1 2// {{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:
1 2// {{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:
1 2// {{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:
1 2// {{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 level0: means Base level-1: means Subtask levelWe 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.
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 company-managed projects, there is nothing to do because there will be no changes. The above only applies to team-managed projects.
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.
Rate this page: