Impact of next-gen projects on the Jira Cloud REST API/Marketplace Apps

Hi there,

As a follow-up to this topic, I’ve created this one to discuss with other developers and Atlassian staff about the impact of some scoped entities of next-gen projects like the Agility project.

Since the last weeks we are investigating some strange situations on Xporter for Jira Cloud related with “duplicated” issue types and role names when asking for Jira Issue Types and Project Roles.
Till now, looking on how the REST API design, it looked like those entity names were unique. Although, that’s not the case since Agility projects wildly appeared :slight_smile:

After reading the topic I mentioned before, I noticed that no one mentioned problems with Roles or any plan about changes on this entity. When an Agility Project is created, 4 new roles will be created exclusively for each project.

  • Administrator
  • Member
  • Viewer
  • atlassian-addons-project-access

This means the same “problem” will occur like the IssueTypes, Custom Fields and Statuses. When asking for Jira Project Roles we will get Roles with duplicated names.

How can this impact our apps? I will briefly explain our case. On Xporter for Jira Cloud we implemented our own Permission Schemes with the ability to define which issue types, roles and groups could export data from Jira Cloud.

Right now, we display n duplicated issue types and roles too, what causes some confusion to our users, due we don’t have any information that the Story issue type is related with a specific project. But that’s not the worst problem because our logic we used the role name as unique.
We were using /rest/api/2/project/<projectIdOrKey>/role in order to get the roles that are being used for each project. It returned the role name and the self url, so we used the role name to get the role id by searching on the Jira Project roles /rest/api/2/role. We needed to get the role actors for each project and we started getting some “404 - Not Found” errors because we provided the wrong role id (Wrong match on role names :frowning:).

Of course we could parse the self url and we could get the role id easily, but it was something that we really didn’t expect.
After explaining this problem on the Atlassian Ecosystem Service Desk, Anne Calantog suggested to start using this (new?) endpoint /rest/api/2/project/<projectIdOrKey>/roledetails. We will get the same data format as we have on /rest/api/2/role.

Although, we are still searching for the best way to fit out permission schemes (in our case of course) on the next-gen projects. Also, it would be very important to receive some answers to this questions.

  1. Is there any date for rolling out the changes on the REST APIs related with retrieve project roles, issue types and other entities by project scope?
  2. There is an Atlassian Connect conditional called “entity_property_contains_any_user_role” that uses the role key or name stored on jira properties. Shouldn’t the role name be deprecated on this condition?

I’m sorry if I’ve missed something on this topic, but it’s something that can have impact so much things in a different way.
Please, be kind and complete this one with the problems you are facing or questions. Thank you :slight_smile:

Kind regards,
Paulo Alves.


Hi @paulo.alves,

Thanks for posting this in the community. I’ll tap Atlassian who would be better at answering this.

For completeness and for other developers to benefit with this information as well, let me share my response to you:

Hi Paulo Alves,

Here’s what I’ve gathered:

(DW/simplified/agility/next-gen) projects we have 4 projects roles created by default for each new project

  1. Administrator
  2. Member
  3. Viewer
  4. atlassian-addons-project-access

These project roles are scoped only to this new project (cannot be used outside of this project), we have rolled a fix for retrieving the correct project roles for a given project under

For retrieving all project roles /rest/api/2/role changes are in flight for all rest APIs that returns all things (as statuses, issuetypes, project roles) to include information about these project roles and where they can be use.

In the mean time there are some APIs broken, the team is aware of the issue and there’s planned changes to update the APIs and communicate the changes to developers using these APIs.

More information can be found in: Jira Cloud next-gen projects and Connect apps

Anne Calantog


Hi @paulo.alves,

Thanks for starting the thread.

We are going to release few blog posts to provide more clarity around the technical implications of the introduction of next-gen projects and provide some guidance about future roadmap and how APIs are going to evolve. I thought it would be worth sharing some of these details before that.

There are few entities that are project scoped: Notificationscheme, Permissionscheme, Roles, Screen, Workflows, Fields, Issue Types, Status and Projects.

As Paulo mentioned, there were certain assumptions that are not valid anymore in next-gen model:

  • We have the concept of project scoped entities. These entities are not sharable across projects (better to say "not yet"™) which is quite different to the classic model.
  • Because of project scoped entities, we cannot rely in the name uniqueness of these entities. In fact, it will be pretty common to have multiple projects with different issue types named “Bug”.

Ok, what’s the plan? How are you able to disambiguate between project and scoped entities?

We will start rolling out API changes to existing REST endpoints, from v2 onwards, which will include scope information for each entity. We will start targeting endpoints using Add-On usage as priority:

  • First one to include this extra information will be Issue Type endpoint. We are aiming the week of 15th October 2018.
  • Other endpoints like Project or PermissionScheme will come after in following weeks.
  • You should expect more blogposts to give you a clearer picture of next-gen Jira and roadmap

I hope to have given you useful information. Please stay tuned. Happy to answer any follow-up question.

Best regards,

Xavi Ferró

Hi @xavi.ferro,

Thank you for the prompt and useful response. Do you have any information about the Atlassian Connect condition “entity_property_contains_any_user_role” and the support of role names on it?

Looking forward to the updates and blogposts. :slightly_smiling_face:

Kind regards,
Paulo Alves.

Hi @paulo.alves,

We just published a continuation blogpost that contains current changes in REST APIs as we discussed. Please let me know if you have any further questions.

Kind regards,


1 Like