Jira Cloud next-gen projects and Connect apps

agility-projects
jira-cloud
announcement
next-gen
rest-api

#1

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.
    • Example: GET https://hostname.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.
  • There is no public REST API available to create project-scoped entities like issue types, statuses and custom fields:
  • 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 in Ecosystem Developer Service Desk 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 in our Ecosystem Developer Service Desk.

Thanks!

Mythili Gopalakrishnan

Product Manager for the Jira platform


Impact of next-gen projects on the Jira Cloud REST API/Marketplace Apps
Impact of next-gen projects on the Jira Cloud REST API/Marketplace Apps
Duplicated Issue Types with different IDs - how to work with context parameters now?
Jira Software next-gen projects are getting new modules
#2

Thanks for the heads up on this @mythili.

Epic endpoints only work for classic boards. The endpoints may appear to work for next-gen projects, however data returned will be invalid.

Our product Easy Agile User Story Maps requires the ability to retrieve Epics and their linked issues to work. Is fixing these APIs in the scope of ACJIRA-1568?

We currently retrieve issues with JQL rather than the Agile API as it’s much more convenient/performant. Will the linkedIssues JQL function also be fixed to retrieve issues linked to an Epic?

Thanks!

~Dave


#3

Hi Dave,

Yes fixing the APIs for epics is also covered under this body of work. We will soon create detailed stories for each piece of work and link it back to the epic ACJIRA-1568.

Best,
-Mythili


#4

Thanks for confirming that, @mythili. :grin:


#5

Can you shed some light on this line, @mythili? We use board properties extensively. How do you see the APIs changing?

Thanks.


#6

Hi @edave,

I might jump in on this one - all the endpoints for board properties, versions and sprint properties exist and are working on the new next-gen projects.

However, due to the architectural changes we’re introducing with next-gen projects, we wanted to give you a heads up that there is a good chance they will change going forward.

For instance, you’ll notice that Versions are not in the UI for next-gen projects and so using the Versions endpoint on the next-gen projects may not currently make sense or result in unexpected things once we do enable this feature.

I think for now you are fine to continue using board properties. Where you can’t see any features in the next-gen project UI you might want to think about whether calling that endpoint still has meaning.

We’ll communicate any upcoming changes if/when we do decide that changes to any of these endpoints and the data contained may cause any breaking changes.

Regards,
Jason Wong
Product Manager, Jira Software


#7

Hey Jason. Great to hear from you, mate. Thanks for the pointers.

We’ll roll out compatibility for Agility boards.

Cheers.

~Dave


#8

Hi @mythili, thanks for the update. Besides from the REST API and board configuration, there are also UI add-on points that are affected by next-get projects. Do have any closer plans of adding them too?

Below, I’m attaching original topic that my workmate created for this specific question. Just take a look at the screenshots there. We have 2 add-ons using board dropdowns and customers more and more often are asking us to support next-gen boards too :frowning:

Damian


#9

Are issue’s createmeta and editmeta valid for next gen projects? Would they return the fields available when creating an issue for a giving next-gen project and issue type?

I have found something odd in next gen. Createmeta does return fields that have been created for a given issue type (using the issue type’s ‘Create new field’ tab).

EXAMPLE:

https://somehost.atlassian.net/rest/api/2/issue/createmeta?projectKeys=SNG&issuetypeIds=ISSUE_TYPE_ID_1&expand=projects.issuetypes.fields

But, if you add the same fields (using drag and drop) into another issue type of the same project, these added fields are not returned in the corresponding createmeta of the second issue type.

EXAMPLE:

https://somehost.atlassian.net/rest/api/2/issue/createmeta?projectKeys=SNG&issuetypeIds=ISSUE_TYPE_ID_2&expand=projects.issuetypes.fields

I believe this is a bug. If createmeta is returning false negative, our addon would not know how to create issues in next gen.

Cheers
fernando


#10

We’re seeing errors using the /rest/api/2/issue endpoint but there is no mention of impact in the bullets above. For example we see errors like the following with nextgen projects.

“description: Field ‘description’ cannot be set. It is not on the appropriate screen, or unknown.”

but our API implementation works perfectly with classic projects. I can confirm the same user can create issues in the browser interface. Please advise.


#11

Hi Geoffrey,

could you be more specific about specific call?

Thanks


#12

This is the problematic exchange. I’ve redacted the details.

POST https://XXXX.atlassian.net/rest/api/2/issue

    Connection: keep-alive
    Accept-Encoding: gzip, deflate
    Accept: */*
    User-Agent: python-requests/2.19.1
    Content-Type: application/json
    Cookie: atlassian.xsrf.token=XXXXXXX
    Content-Length: 372
    Authorization: Basic XXXXXXXXXXX
    
    {"fields": {"project": {"key": "GFFW"}, "issuetype": {"id": "7"}, "labels": ["XXXX"], "description": "XXXXXXX", "summary": "CT627: test"}}

400 Bad Request
    
    Server
    Cache-Control
    Content-Type
    Strict-Transport-Security
    Date
    ATL-TraceId
    X-AREQUESTID
    X-XSS-Protection
    Transfer-Encoding
    ATL-TCS-Time
    X-AUSERNAME
    X-Content-Type-Options
    Connection
    X-Seraph-LoginReason
    
    {"errorMessages":[],"errors":{"summary":"Field 'summary' cannot be set. It is not on the appropriate screen, or unknown.","description":"Field 'description' cannot be set. It is not on the appropriate screen, or unknown.","labels":"Field 'labels' cannot be set. It is not on the appropriate screen, or unknown."}}

These fields exist on the Create Issue page. Our implementation makes sure of it as well - since we pull the createmeta response. Here is a screenshot:

Here is the API exchange for the problematic project,

GET https://XXXXX.atlassian.net/rest/api/2/issue/createmeta?projectKeys=GFFW&issuetypeNames=Story&expand=projects.issuetypes.fields
    
    Connection: keep-alive
    Accept-Encoding: gzip, deflate
    Accept: */*
    User-Agent: python-requests/2.19.1
    Cookie: atlassian.xsrf.token=XXXXXX
    Authorization: Basic XXXXXXXX

200 OK
    
    Server
    Vary
    Cache-Control
    Content-Type
    Content-Encoding
    Strict-Transport-Security
    Date
    ATL-TraceId
    X-AREQUESTID
    X-XSS-Protection
    Transfer-Encoding
    ATL-TCS-Time
    X-AUSERNAME
    X-Content-Type-Options
    Connection
    X-Seraph-LoginReason
    
    {"expand":"projects","projects":[{"expand":"issuetypes","self":"https://XXXX.atlassian.net/rest/api/2/project/27805","id":"27805","key":"GFFW","name":"geoffw","avatarUrls":{"48x48":"https://XXXX.atlassian.net/secure/projectavatar?avatarId=10403","24x24":"https://XXXX.atlassian.net/secure/projectavatar?size=small&avatarId=10403","16x16":"https://XXXX.atlassian.net/secure/projectavatar?size=xsmall&avatarId=10403","32x32":"https://XXXX.atlassian.net/secure/projectavatar?size=medium&avatarId=10403"},"issuetypes":[{"self":"https://XXXX.atlassian.net/rest/api/2/issuetype/10152","id":"10152","description":"Stories track functionality or features expressed as user goals.","iconUrl":"https://XXXX.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10315&avatarType=issuetype","name":"Story","subtask":false,"expand":"fields","fields":{"summary":{"required":true,"schema":{"type":"string","system":"summary"},"name":"Summary","key":"summary","hasDefaultValue":false,"operations":["set"]},"issuetype":{"required":true,"schema":{"type":"issuetype","system":"issuetype"},"name":"Issue Type","key":"issuetype","hasDefaultValue":false,"operations":[],"allowedValues":[{"self":"https://XXXX.atlassian.net/rest/api/2/issuetype/10152","id":"10152","description":"Stories track functionality or features expressed as user goals.","iconUrl":"https://XXXX.atlassian.net/secure/viewavatar?size=xsmall&avatarId=10315&avatarType=issuetype","name":"Story","subtask":false,"avatarId":10315}]},"attachment":{"required":false,"schema":{"type":"array","items":"attachment","system":"attachment"},"name":"Attachment","key":"attachment","hasDefaultValue":false,"operations":[]},"description":{"required":false,"schema":{"type":"string","system":"description"},"name":"Description","key":"description","hasDefaultValue":false,"operations":["set"]},"project":{"required":true,"schema":{"type":"project","system":"project"},"name":"Project","key":"project","hasDefaultValue":false,"operations":["set"],"allowedValues":[{"self":"https://XXXX.atlassian.net/rest/api/2/project/27805","id":"27805","key":"GFFW","name":"geoffw","projectTypeKey":"software","avatarUrls":{"48x48":"https://XXXX.atlassian.net/secure/projectavatar?avatarId=10403","24x24":"https://XXXX.atlassian.net/secure/projectavatar?size=small&avatarId=10403","16x16":"https://XXXX.atlassian.net/secure/projectavatar?size=xsmall&avatarId=10403","32x32":"https://XXXX.atlassian.net/secure/projectavatar?size=medium&avatarId=10403"}}]},"issuelinks":{"required":false,"schema":{"type":"array","items":"issuelinks","system":"issuelinks"},"name":"Linked Issues","key":"issuelinks","autoCompleteUrl":"https://XXXX.atlassian.net/rest/api/2/issue/picker?currentProjectId=&showSubTaskParent=true&showSubTasks=true&currentIssueKey=null&query=","hasDefaultValue":false,"operations":["add"]},"reporter":{"required":true,"schema":{"type":"user","system":"reporter"},"name":"Reporter","key":"reporter","autoCompleteUrl":"https://XXXX.atlassian.net/rest/api/latest/user/search?query=","hasDefaultValue":true,"operations":["set"]},"assignee":{"required":false,"schema":{"type":"user","system":"assignee"},"name":"Assignee","key":"assignee","autoCompleteUrl":"https://XXXX.atlassian.net/rest/api/latest/user/assignable/search?project=GFFW&query=","hasDefaultValue":false,"operations":["set"]},"labels":{"required":false,"schema":{"type":"array","items":"string","system":"labels"},"name":"Labels","key":"labels","autoCompleteUrl":"https://XXXX.atlassian.net/rest/api/1.0/labels/suggest?query=","hasDefaultValue":false,"operations":["add","set","remove"]},"customfield_13017":{"required":false,"schema":{"type":"number","custom":"com.atlassian.jira.plugin.system.customfieldtypes:float","customId":13017},"name":"Story point estimate","key":"customfield_13017","hasDefaultValue":false,"operations":["set"]}}}]}]}

#13

Hi Geoff,

Thanks for detailed information. I created https://jira.atlassian.com/browse/JRACLOUD-70993 to keep track of it.

Best regards,

Xavi


#14

Thank-you!

This is impacting testing and pre-sales activities so we would appreciate a resolution to this issue. Please let me know if I can be of further assistance. I’ve successfully tested our integration against Jira v8.0.0-m0021 (local download) and I don’t see any issues.