Introducing two new project permissions - View Projects and View Issues

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

  1. if a user can view projects
  2. 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.

  1. 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.
  2. 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
  • 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?

  1. Current behaviour:
  • If you want users to access projects or issues, BROWSE_PROJECTS permission is used
    • eg: if you want users to get project information like description, issuetypes, project properties, BROWSE_PROJECTS permission is used
  1. New behaviour after Stage 1
  • If you want users to access projects, use VIEW_PROJECTS or BROWSE_PROJECTS permission
    • eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either VIEW_PROJECTS or BROWSE_PROJECTS permission
  • If you want users to access issues, use both “VIEW_PROJECTS and VIEW_ISSUES" or BROWSE_PROJECTS permission
    • eg: if you want users to get issue and or its fields using the get_issue API, you need to have both “VIEW_PROJECTS and VIEW_ISSUES" or BROWSE_PROJECTS permission

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.

  1. Behaviour after Stage 2
  • If you want users to access projects, use VIEW_PROJECTS permission

    • eg: if you want users to get project information like description, issuetypes, project properties using the get project API , you can use either VIEW_PROJECTS permission
  • If you want users to access issues, use both “VIEW_PROJECTS and VIEW_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_PROJECTS and VIEW_ISSUES" permission

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-

  1. 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
    }
  }
}
  1. 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

6 Likes

Hi Varad,
I was wondering if you could share how this will affect project entity properties? Will they require VIEW_ISSUES permissions (since some of them could be “content based”) or will they be readable based on the VIEW_PROJECT permissions?

If it’s the later - will you be introducing another mechanics for project based issue entity properties that is attached to the VIEW_ISSUES permissions?

Thanks,

/Daniel

5 Likes

Love to hear that this coming, very much looking forward to our users being able to see available projects, so they can request access to them, rather than being in the dark about what projects are in Jira.

1 Like

I have a few questions coming from the perspective of a Jira Cloud admin.

  1. Does the Jira Cloud admins have to update the all the permission schemes manually or the updates will be done automatically with a tool? This is a challenge for sites with a lot of permission schemes. It is an administrative nightmare to get inputs from project owners to decide on the new permissions.

  2. Is the Permission Helper going to be updated for this?

  3. Is Jira Cloud Migration Assistant (JCMA) going to be updated for this? Will it affect the migration of Server instance to Cloud?

  4. Thinking aloud, will it be easier to retain BROWSE_PROJECTS permission as it is and introduce VIEW_PROJECTS as a new permission? This permission can be granted to allow users who does not have BROWSE permission but need to view the projects.

4 Likes

Hi Daniel,

I will check with my dev team and get back to you soon.

Meanwhile, we have rolled this out to the EAP cohort as mentioned in the post. In case you are part of that, I would request you to try out these scenarios.
Thanks

Hi, Thank you for the questions

  1. The updates will be done automatically. So admins for sites with lots of permissions don’t have to worry about it.
  2. Yes, Permission helper will be updated for this
  3. I will check it and get back to you soon. As of today, we believe it won’t impact the JCMA, but I’ll still make sure and reply back.
  4. We had considered that as an option, although we wanted to avoid confusion by not keeping 2 permissions that behave similarly. I will keep you posted if there are any updates on this.
1 Like

As a Jira admin and vendor i had the same thought as huasoon that leave browse projects as is and just add the new view projects privilege.

Much smaller change and non breaking. Also prevents need to check 2 separate privs because (to me) the browse project/view issue implies the user can see the project.

Is there a use case where a user would need view issue and NOT view project?

My 2 cents
Chris

2 Likes

Hello Varad,

Today, Sept’23 I’ve tried:

  • https://<mysite>.atlassian.net/rest/api/3/permissions - no VIEW_ISSUES permission.
  • https://<mysite>.atlassian.net/rest/api/3/mypermissions?permissions=VIEW_ISSUES - error “VIEW_ISSUES”: “Unrecognized permission”

Is the stage 1 postponed?
Ondrej

I guess Sept’22 meant somewhere in September 2022, not 22th of September. Just saying.

1 Like

@stefan_hc @VaradPingale Aha I am sorry, my misunderstanding, so I’ll wait till October’22.

1 Like

Hello @OndejMedek
Thanks for checking in, and apologies for the delay in replying.
As @stefan_hc mentioned, we were planning to release this to everyone by September 2022.
We are still evaluating these changes based on some of the feedback we have received in the comments, hence it might take one more week to get back on when we can release this to everyone.
In the meanwhile, I would request you to enroll a test instance in the EAP cohort here Jira Cloud Vendor First Release if you want to try out the change.
Thank you.

1 Like

Hello @Chris_at_DigitalRose
Thanks for the feedback. We are evaluating this approach before we rollout the change to everyone.
Will keep you posted on this.
Thanks

1 Like

Update on above announcement:

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.

2 Likes

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.

After the rollout on 31st March’23 both Browse project permission and the two new permissions will continue working together until 6 months later?

2 Likes

Any update on when the old Permission will be removed, or is this something that will be updated after 31st March '23, when both sets of Permissions are rolled out?

2 Likes

@VaradPingale @ibuchanan - where does this stand now? March 31st is approaching soon and it is completely unclear to me what, if anything, will happen. I suppose that the content that is “outdated as of Oct 22” can be disregarded? Please help us understand what’s going on, this is having massive impact on pretty much any Marketplace app.

1 Like

@VaradPingale are there any news regarding the rollout, and what exactly will happen on March 31st?

I’m assuming the initial plan (stage 1 and stage 2, with at least 6 months in between) is still relevant, but it would be good to have a confirmation.

1 Like

Hi!

Is it possible to know what is the current situation of this?
It is almost 31st March and we have no news.

1 Like