G’day Atlassian developer community!
Update on above announcement (28th March’23):
We had earlier announced that “Introduction of two new permissions to replace Browse Project permission” was planned for release on 31st March ’23. Since then, we have received questions regarding the rollout from our partners and customers, which we are still in the process of addressing. As a result, we have decided to NOT rollout this change on 31st March ’23 for Jira Cloud.
This means, Browse projects permission will continue to work as it is, and the two new permissions won’t be introduced until further notice.
Meanwhile, this work is still a priority for us, and our team is evaluating all the questions and concerns mentioned in the comments. This process of evaluation will take a few more weeks. Following the evaluation, we will inform you about the revised timeline for rollout, well in advance.
In case you are interested in trying out the change, please enrol yourself in Developer Canary Program
If you have any questions, please drop them in the comments section. Please expect more communications on this in upcoming few weeks.
+++The content below is outdated as of 28th Mar 22, please read above for the latest update on replacement of Browse Project permissions with two new permissions +++
Update on below announcement (4th Oct’22):
On Aug 19, 2022, we announced the “Introduction of two new permissions to replace Browse Project permission”. It was planned to be released by end of September 2022.
We’ve since received feedback from many of you on this being a fundamental change in how permissions work, and the requirement of more notice period to adjust with the change. As a result, we have decided to NOT rollout this change to any of our customers till 31st March’23.
This means, Browse projects permission will continue to work as it is, and the two new permissions won’t be introduced till then.
Meanwhile, our team will evaluate the different cases mentioned in the comments to ensure all of them are addressed.
In case you are interested in trying out the change, please enroll yourself in the EAP cohort Jira Cloud Vendor First Release. After getting adequate feedback from this cohort, we will inform you well in advance about the revised timeline of the rollout of this change.
Thank you for your feedback and apologies for any confusion caused by the earlier announcement or this revision of the timeline.
Thank you for being an Atlassian partner. If you have any questions, please drop them in the comments section. We will keep you posted.
We’re adding 2 new permissions, View Projects and View Issues, to eventually replace the “Browse Projects” permission. This will give users and admins more fine-grained control over who can view the projects and issues.
Note: We have endeavoured to make this change backwards compatible, and based on our understanding of how apps are using our REST APIs today we believe this change should not impact apps. However, this is a significant and fundamental change to Jira Cloud: the BROWSE_PROJECTS permission is close to two decades old, and the semantics of our existing permissions APIs are quite complicated. There may be impacts to apps that are difficult for us to anticipate.
To mitigate the risk of us overlooking a use-case that is important to apps, we have decided to hold off on rolling this change out for four weeks (28 days) from time of publishing. Further, we have decided to give a window till Mar’23 to make changes within your application, post which we plan to remove support for Browse Project permissions. If you have concerns after reviewing the details below, and you believe the change is not backwards compatible (that is, the functionality of your app as it is built today will break) then please let us know in the reply and we will revise our proposed timeline as necessary.
Context
As you may know, the “Browse Projects” permission has dual functionality. It is used to check
- if a user can view projects
- if a user can view the issues within the project.
In other words, it can be used to act at the Project Level e.g. permission to view the projects directory, and at the Issue Level e.g. the ability to view an issue.
Since all the other permissions either work at the Issue Level (e.g. “Edit Issues”) or at the Project Level (e.g. “Administer Projects”), the current way of working of the “Browse Projects” permission is unique and problematic.
Why it is changing?
By splitting the “Browse Projects” permission into two, we can give users more fine-grained control over Jira’s permissions. Both the new permissions will have its own distinct role.
- “View Projects” is a project-level permission for viewing projects in Jira. It is the permission to view the projects directory page and the ability to select that project in various dropdowns such as in JQL.
- “View Issues” is an issue-level permission for viewing the issues within a project.
Therefore, “View Issues” can be used to control who can view issues within a project and “View Projects” can be used to control who can view projects in the projects directory.
How are we rolling this out?
We will rollout the change in 2 stages:
- Stage 1: Introduce two new permissions - View issues and View Projects - In Sept’22
- EAP: For instances enrolled in Jira Cloud Vendor First Release - Immediately after this announcement
- Stage 2: Remove support for Browse projects permissions - After Mar’23
This announcement is about Stage 1. As mentioned above, we believe everything is backward compatible in this stage, i.e. both Browse Projects permission and View Issues + View Projects permission will coexist and work together. The rollout for this stage will be done in phases over next few weeks, starting with the EAP cohort.
EAP: All instances enrolled in the Jira Cloud Vendor First Release will get these changes right after this announcement. After getting sufficient feedback on this, we will give an update about when this change will be rolled out to all customers.
For Stage 2, a separate announcement will be made after 6 months , in Mar’23. During this period, we welcome feedback from you.
We strongly recommend vendors to plan for and adopt the above changes. We plan to remove support for Browse projects permission after Mar’23. We will keep the community posted if there are any updates in this plan, as mentioned in the note above.
What is changing in Jira?
- Current behaviour:
- If you want users to access projects or issues,
BROWSE_PROJECTSpermission is used- eg: if you want users to get project information like description, issuetypes, project properties,
BROWSE_PROJECTSpermission is used
- eg: if you want users to get project information like description, issuetypes, project properties,
- New behaviour after Stage 1
- If you want users to access projects, use
VIEW_PROJECTSorBROWSE_PROJECTSpermission- eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either
VIEW_PROJECTSorBROWSE_PROJECTSpermission
- eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either
- If you want users to access issues, use both “
VIEW_PROJECTSandVIEW_ISSUES" orBROWSE_PROJECTSpermission- eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “
VIEW_PROJECTSandVIEW_ISSUES" orBROWSE_PROJECTSpermission
- eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “
After Stage 1, as a Jira ecosystem developer, you are expected to start updating your apps to use these two new permissions over the period of next 6 months. The BROWSE_PROJECTS permission will still be supported. This is because BROWSE_PROJECTS grant automatically gets copied to VIEW_ISSUES and VIEW_PROJECTS grants. Although, it is recommended to start using the new permissions.
- Behaviour after Stage 2
-
If you want users to access projects, use
VIEW_PROJECTSpermission- eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either
VIEW_PROJECTSpermission
- eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either
-
If you want users to access issues, use both “
VIEW_PROJECTSandVIEW_ISSUES" permission- eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “
VIEW_PROJECTSandVIEW_ISSUES" permission
- eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “
After Stage 2, as a Jira ecosystem developer, you will need to update your apps to use these two new permissions. This is because support for BROWSE_PROJECTS will be removed.
These changes will be reflected in The Jira Cloud platform REST API documentation to once we start rolling them out to everyone.
How do the changes look?
API Changes:
There won’t be any structural changes, but some semantic changes as follows:
Example 1: Let’s say a user has BROWSE_PROJECTS permission assigned in the scheme. Jira will automatically copy this grant to the new permissions VIEW_PROJECTS and VIEW_ISSUES after Stage 1.
This is how get my permissions API will behave 1.) Currently, 2.) After stage 1 rollout and 3.) After Stage 2 rollout-
- Current behaviour:
GET /rest/api/2/mypermissions?permissions=BROWSE_PROJECTS&projectKey=AB
The permission check depends on the grants against BROWSE_PROJECTS permission.
{
"permissions": {
"BROWSE_PROJECTS": {
"id": "10",
"key": "BROWSE_PROJECTS",
"name": "Browse Projects",
"type": "PROJECT",
"description": "Ability to browse projects and the issues within them.",
"havePermission": true
}
}
}
- After Stage 1 rollout:
The permission check depends on the grants against VIEW_PROJECTS instead of BROWSE_PROJECTS permission. Although you can still use BROWSE_PROJECTS.
We recommend you to change the API call to pass VIEW_PROJECTS instead of BROWSE_PROJECTS when check is done using project key or project id.
GET /rest/api/2/mypermissions?permissions=VIEW_PROJECTS&projectKey=AB
{
"permissions": {
"VIEW_PROJECTS": {
"id": "-1",
"key": "VIEW_PROJECTS",
"name": "View Projects",
"type": "PROJECT",
"description": "Ability to view projects.",
"havePermission": true
}
}
}
Similarly, we recommend you to change the API call to pass VIEW_PROJECTS and VIEW_ISSUES instead of BROWSE_PROJECTS when check is done using issue key or issue id.
GET /rest/api/2/mypermissions?permissions=VIEW_PROJECTS,VIEW_ISSUES&issueKey=AB
{
"permissions": {
"VIEW_PROJECTS": {
"id": "-1",
"key": "VIEW_PROJECTS",
"name": "View Projects",
"type": "PROJECT",
"description": "Ability to view projects.",
"havePermission": true
},
"VIEW_ISSUES": {
"id": "-1",
"key": "VIEW_ISSUES",
"name": "View Issues",
"type": "PROJECT",
"description": "Ability to browse issues within a project.",
"havePermission": true
}
}
}
After Stage 2 rollout:
BROWSE_PROJECTS permission no longer supported. As a result, the permission check will return an error saying Unrecognized permission.
GET /rest/api/2/mypermissions?permissions=BROWSE_PROJECTS&projectKey=AB
{
"errorMessages": [],
"errors": {
"BROWSE_PROJECTS": "Unrecognized permission"
}
}
The recommendation is to make sure all the code references to call the API are using VIEW_PROJECTS and VIEW_ISSUES permission.
UI changes:
Here are some screenshots from the Permission Schemes page that indicates the changes mentioned above.
Browse Projects has a “Deprecated” tag with it, and View Projects has “New” tag with it.
Note: Although Browse Projects permission is marked as “Deprecated”, it can still be used, until it the support is completely removed after Mar’23
View Issues lie under the Issue Permissions category, with a “New” tag with it
Thank you in advance for working through these changes and for your continued support.
If you have any concerns or questions about these changes please don’t hesitate to reply below.
Best,
Varad Pingale
Jira PM