In the spirit of openness, we want to take this opportunity to communicate some of the side-effects that Jira’s new next-gen projects (formerly known as agility projects or independent projects) have introduced to Connect apps.
The next-gen projects simplify the project configuration experience and allow non-jira-admins to create projects and configure them. All project configuration entities in these next-gen projects like issue types, statuses, and custom fields – are scoped to the project. Schemes don’t exist in these projects. Project configuration entities that are created within a next-gen project are only available to that project.
The launch of these next-gen projects has resulted in some change in behavior to the existing Cloud REST API v2.0 as listed below:
-
Read operations return both global and project scoped entities, which results in a semantic change.
- Ex:
GET https://x.atlassian.net/rest/api/2/issuetype
On instances with classic and next-gen projects the above GET call will return all issue types for both global and project-specific contexts. Because next-gen projects don’t share schemes, this list could include duplicate entries. And, the list does not distinguish between global and project-scoped issue types.
- Ex:
-
There is no public REST API available to create project-scoped entities like issue types, statuses and custom fields:
-
POST and PUT calls work as per contract when applied to classic project configuration objects. All write operations (create and update) will NOT work when operating on next-gen project entities.
-
Ex:
PUT https://x.atlassian.net/rest/api/2/issuetype/10235/properties/color
If issue type 10235 is project-scoped this call will fail with a 400 or 500.
-
-
Create and Delete board is not supported for next-gen projects
- You cannot create the new next-gen board as a standalone board object. It can only be created with a next-gen project. This may change in the future when we introduce multiple boards for next-gen projects.
-
Epic endpoints only work for classic boards. The endpoints may appear to work for next-gen projects, however data returned will be invalid.
-
Board properties, Versions and Sprint properties should not be set for any next-gen projects as these may change in future releases.
Additionally, if an app adds a web item into a project’s settings and provides a project settings configuration screen, this web item and project settings page will not appear in next-gen project’s settings.
We have logged two tickets to track these issues:
- ACJIRA-1567 – Plugin point for adding per-project configuration settings in next-gen projects
- ACJIRA-1568 – REST API for new Jira Projects
As a first step, we plan to fix the API for those apps that add a web item and project configuration settings, their settings appear under the next-gen project settings. Subsequently we plan to fix the GET calls to provide additional information for project scoped entities so apps can differentiate the global entities from those independent to a next-gen project. Finally we will prioritize project-scoped POST and PUT calls.
Once we have addressed all the issues, we’ll follow up with another post on what changes Connect apps need to make to ensure the apps work in both classic and next-gen projects. In the meantime, if you have any questions or concerns, please comment on any of the two tickets listed above, or to engage in a deeper discussion, head over to this thread on the developer community forums.