Get Groups API enhanced to support group lookups based on access type

[ShirazKhan]

UPDATE:

• Changed date from August 2nd to August 9th for changing the default group names for new customers
• Added date August 5th 2021 for when we will enhance this API by adding a new optional query parameter named accessType
• Added new section titled Testing Notes

What is a group?

A group is a collection of users. Administrators create groups so that the administrator can assign permissions to a number of people at once. For example, it is quicker to give group ‘X’ access to Jira Software, rather than giving every team member access individually. In cloud, each group needs to be uniquely named. A user can be a member of multiple groups. Groups are particularly important as they are used to:

• Control users access to a product instance.
• Restrict which users have access to content within a product instance, like restricting access to a Confluence space or page, or access to a Jira Software project.
• Enable features for groups of users within a Jira product or Confluence, like editing, commenting or workflows.

Why are group names significant?

Today, our APIs are keyed off group name and some apps may be expecting certain group names to always exist, such as the default groups that Atlassian creates when a new product is provisioned. But these default groups don’t always exist.

What are we changing?

Groups have always been able to be altered by customers. They can create new groups, delete existing groups, and alter which products those groups get access to. So a customer may start off with two groups called jira-software-users and confluence-users , that grant access to Jira Software and Confluence. But they could end up with a single group called all-staff that grants access to both Jira Software AND Confluence.

We’ll be changing the default group names for new customers on August 9th 2021, so we can better disambiguate groups for customers who want to see all groups in a single list, across all their products. To do this, we’ll attach the site name to the current default group names, e.g. for the site Acme Test, the default confluence group name will be confluence-users-acmetest . Existing customers will not have their groups altered before February 1st 2022.

Why are we changing it?

We’re altering our architecture to allow a single userbase at the Organisation level to serve a number of different products, on multiple sites. This requires us to update our group names to ensure they’re still unique in the future.

As a side note; We’re also working towards a long term goal of allowing customers to change their group names, rather than having to create a new one and delete the old one. This is something that our customers have wanted for about ~18 years . Once this work is complete, customers will be able to change any group name they like. But, we have many months of work ahead of us before this is in customers hands.

Give me some technical details!

For Confluence apps

We currently have an API to get groups: GET /wiki/rest/api/group (see The Confluence Cloud REST API for more details). On August 5th 2021, we will enhance this API by adding a new optional query parameter named accessType that will return only groups with that type of permission:

• GET /wiki/rest/api/group?accessType=<ACCESS_TYPE> (ACCESS_TYPE must be admin , user or site-admin )
  • GET /wiki/rest/api/group?accessType=admin
    • return list of groups that have product admin access to Confluence
    • e.g. confluence-admin or confluence-admin-acmetest
  • GET /wiki/rest/api/group?accessType=user
    • return list of groups that have use access to Confluence
    • e.g. confluence-users or confluence-users-acmetest
  • GET /wiki/rest/api/group?accessType=site-admin
    • return list of groups that have admin access to the site or organisation
    • e.g. site-admin

We strongly encourage using this API going forward since it’s unreliable to lookup static group names today, and may result in more unexpected results in the future.

For Jira apps

Our team will have more information on when this API will be available around October 2021.

What do I need to do?

If your apps search for groups based on group name, you should instead consume the above API to get groups, in order to ensure your app works for all customers.

I can’t / I don’t want to / I hate your API / work around

If do you have customers experiencing issues with your app due to unexpected group names, they are always able to manually create any group name you need them to and apply the correct product access permissions to it.

Testing Notes

You can test this API by:

1. Create a new group with any name you like.
2. Apply the Confluence product access permission to it (or any other product or admin permission you want to test)
3. Call the GET /wiki/rest/api/group API with the access type you’ve applied to the new group