G’day Atlassian Developer community!
As shared earlier in Adding support for group ID along with group name in REST APIs and Jira Cloud Platform changelog, Jira Cloud is moving towards using groupID s as unique identifier for groups instead of group name s.
We have provided support for groupID field in all Jira Public APIs that use group name as an identifier. We will be removing the support for group name field from such Jira Public APIs starting from February 28 2023, as described below.
Why is it changing?
As you may know, Jira does not offer the functionality to rename groups. To enable that, we want groups to be identified by an identifier with is immutable. Currently, group name is used as an identifier, which is inherently mutable. Thus, we need to remove the use of group name as the identifier.
What is changing?
We have been using group name as group identifiers across all Jira Cloud public APIs. We are moving towards using groupID as the unique identifier for a group instead. All APIs that use group names across Jira Cloud like get notification schemes paginated, get all application roles, create permission scheme etc., including Jira expressions types and Connect conditions will be affected by this change. The REST API documentation The Jira Cloud platform REST API has been updated with this change.
There are also a few exceptions to it. More details on sample changes and exceptions are given below:
Examples
- Request type
This is an example of comment Visibility API (https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-links/#api-rest-api-3-issuelink-post)
Old behaviour: The request payloads used group name for mutation operations (like adding visibility, in the below example).
"comment": {
"visibility": {
"type": "group",
"value": "jira-software-users"
}
New behaviour: Now, these support use of groupID as identifier for all such operations. Similar changes have been made across all the APIs.
"comment": {
"visibility": {
"identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
"type": "group",
"value": "jira-software-users"
}
- Response type
This is an example of Bulk Get Groups API (https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-groups/#api-rest-api-3-group-bulk-get)
Old behaviour: Previously, the API responses had only group names.
"values": [
{
"name": "developers"
},
{
"name": "juvenal-bot"
}
]
New behaviour: Now, these will include groupIDs in addition to group names.
"values": [
{
"name": "developers",
"groupId": "276f955c-63d7-42c8-9520-92d01dca0625"
},
{
"name": "juvenal-bot",
"groupId": "6e87dc72-4f1f-421f-9382-2fee8b652487"
}
]
Exceptions
There are a few exceptions to these, where the APIs won’t get impacted by this change.
- This change won’t be applicable to APIs where group
namesare used as query parameters for search/ create operations etc.
- Example: Search for filters, Find users and groups, Create group etc.
- This change won’t be applicable for Workflow APIs. Changes to them will be released later, and a separate deprecation period will be given after that.
- List of workflow APIs which are not affected: Workflows API group and Workflow transition properties
We have tried to be exhaustive in identifying these APIs, and providing support for groupIDs in them. In case you identify any APIs which do not support groupIDs in it, please reach out to us by replying on this thread.
When is the change happening?
The support for groupID has been already added. You might have already noticed these changes in the REST APIs and their documentation. Currently we support both group names and groupIDs to enable testing out these changes. We will be removing the support for group name field from such Jira Public APIs starting February 28, 2023.
What do I need to do?
We ask you to migrate away from using group name s and start using the groupID s in these APIs. We request you to start reviewing these changes and plan to incorporate them into your app to give yourself the maximum opportunity for a smooth transition.
The new behaviour is now available in all Jira Cloud APIs. If you encounter any issues or have questions, please respond to this post.
By when do I need to do it?
We are beginning the 6 month deprecation notice period with this announcement. We will switch off the old behaviour (supporting group names) starting February 28, 2023 . Meanwhile, we will keep you updated on any changes.
Please feel free to reply to this thread in case of any queries or suggestions once you try out the changes.
Thanks,
Varad,
Jira Cloud PM