Confluence cloud is moving away from groupName towards groupId as the identifier for Groups. Two main changes may affect you.
REST API - We will be exposing REST endpoints that will use groupId instead of groupName in the next two months. Once the new groupId APIs are available, we will start a 6 month deprecation for the APIs that use groupName. After this 6 month period, groupName will still be available but will no longer be immutable, so you will not be able to store it and rely on it being a stable identifier.
Webhook Events - We will also be adding a new field groupId to the webhook events group_removed and group_created.
Why is it changing?
Currently since groupName is the identifier for groups it is immutable which means once a group is created there is no way to rename said group. A big reason we are making this change is so that going forward we can introduce the functionality to rename groups.
If not storing groupName, making this change is optional (there is still a small chance of getting a groupName and trying to make a new REST API call after the old groupName has been updated but this is a very unlikely case). Your team can make the decision, groupName will continue to be unique per organization but will no longer be immutable.
If storing groupName, your team must update to use groupId instead because going forward groupName will no longer be immutable.
Determine if your team needs to make the switch to use the new field groupId instead of groupName.
By when do I need to do it?
Deprecation Date: March 27, 2022
REST APIs with groupName will still be available for use but groupName will no longer be immutable after this date. Please let us know if you have any concerns about this. We may adjust our timeline based on your feedback.
Will this also affect the REST APIs dealing with content restrictions and space permissions? Right now, giving a group permission is done by group name.
Update: Sorry, not all the APIs will be ready by Nov 16 . I will make a new post once all the new APIs are ready and the 6 month deprecation notice will only start from that date.
Hello!
I’m wondering if this change will also come to Jira APIs. Our app make use of both Confluence and Jira and when fetching the current user’s user groups through Jira we’re not getting the group id, just the name. We’re letting customers decide what user groups that can see certain content and we won’t be able to adjust for this Confluence update unless the ids are also returned from the Jira API.
Hi @jjohn , /rest/api/space/SPACEKEY?expand=permissions still doesn’t support groupId in the response. Will this be supported before the deprecation? Thanks!
Jira and Confluence are doing this work separately and this change has not been planned for Jira yet so I unfortunately cannot give you a timeline for when to expect it.
Yes, it will be supported before the deprecation but we are currently blocked on some work that we need to do before we can include groupId in the response, we are hoping to get unblocked sometime in January.
Hey John,
moving to groupIds is a great step in the development. Is it also in your scope to use the id’s in the experimental apis, namely adding new permissions to groups via id?
Could you tell us if the experimental change are also included in the January patch? In the trello board someone has talked about updates being made in September and we haven’t gotten an update since then)
Hey Kilian,
Is there a specific API you are asking about? We are almost done with adding the groupId endpoints and I’m trying to confirm we have everything (we are still working on a few / rolling them out).
When group names become mutable does this also apply to the Confluence built-in special groups like ‘administrators’ and ‘confluence-users’? If so, will there be an API to get the ID of these groups?
. I will make a new post once all the new APIs are ready and the 6 month deprecation notice will only start from that date.
to get unblocked sometime in January.