Last updated Jan 18, 2023

Rate this page:

Changelog

This page includes release notes and updates for Jira Cloud app developers. Use this page to keep track of upcoming changes, deprecation notices, new features, and feature updates from Jira Software Cloud.

Go to our developer community to ask questions. You may also be interested in the What's New blog for Atlassian Cloud where details of major changes that affect all users of the Jira Cloud products are announced.

18 January 2023

Announcement We’re updating our API token, API key, and Repository Access Token length

On January 18, 2023, we'll be extending the length of API tokens for Atlassian accounts, API keys, and Repository Access Tokens. This ensures new tokens and keys generated after this date are more secure and reliable. Tokens and keys created before January 18, 2023 won’t be affected.

16 December 2022

Added App alerts now support custom target value

In the developer console, you can now edit the target value of your Forge app alert. Previously, the alert was set at a target value of 99%. Now you can choose from a number of values between 99% and 60%.
For more information, see Manage app alerts.

15 December 2022

Deprecation Notice Plan-only teams will no longer be accessible in the Team field via Jira REST APIs and JQL queries

Plan-only teams (also known as private teams) will no longer be usable outside of an Advanced Roadmaps plan, specifically in the Team field via Jira REST APIs and JQL queries.

These changes do not affect the use of shared teams.

More details

What is changing?

Plan-only teams (also known as private teams) will no longer be usable outside of an Advanced Roadmaps plan, specifically in the Team field via Jira REST APIs and JQL queries. This does not affect the use of shared teams.

Plan-only teams are not provided as JQL Suggestions for the Team field, however it is possible to query a plan-only team directly by it’s id. After this change, querying plan-only teams directly by id will no longer return any results.

Plan-only teams will also no longer be exposed in the Team field of an issue on the Jira Get Issue REST API, nor be settable via the Create or Edit Issue REST API. Previously only the id and a place-holder title “Plan-specific team" were returned. After this change, the field will appear empty.

This change also affects the REST API and Jira Smart values; after this change takes effect, the following attributes of the exposed custom field data will be deprecated:

  • The “title” attribute will be deprecated in favour of the “name” attribute

  • The “isShared” attribute will be deprecated and can assumed to be true as only shareable teams will be returned by the API.

All functionality for shared teams will continue to be supported.

What do I need to do?

  • If you have plan-only teams you wish to use outside of the plan, you may convert these to share teams to continue to be able to use them

  • If you use the "title" attribute, of the team custom field, replace this use with the "name" attribute

  • If you use the "isShared" attribute, of the team custom field, it will no longer be required - replace this with the assumption the value is always true

For example, in the Jira Rest API:

GET /rest/api/{version}/issue/{issueIdOrKey}

1 2 3 4 5 6 "customfield_10001":{ "id":"6", "name":"My team", "title":"My team", -- deprecated, use "name" "isShared":true -- deprecated, assume true }

For example, in Jira Smart values

replace

1 {{issue.Team.title}}

with

1 {{issue.Team.name}}

When will this change happen?

The change will be progressively rolled out 3 months from this notice.

2 December 2022

Deprecation Notice Retiring full-page issue create in Jira Cloud

The full-page issue create experience will be retired for all Jira Cloud customers over the next 6 months. Although there is no formal API for the full-page issue create experience, it’s possible that some apps may be relying on it and will need to be updated.  For more information, read this community post.

1 December 2022

Announcement Developer Canary Program for Jira and Confluence cloud sites

The Jira/Confluence Cloud First Releases for Ecosystem initiative has been renamed to Developer Canary Program and now includes an app to provide self-service capabilities for developers.

For more information on how to get started with the program, see the Developer Canary Program documentation.

More details

To access the Developer Canary Program app for:

23 November 2022

Added Germany region added for Connect data residency

Added Germany as supported realm for Connect data residency.

Read the documentation

22 November 2022

Announcement Data residency realm migration for Connect apps: Early Access Program

Today, we are happy to announce the launch of the Early Access Program (EAP) of data residency realm migration for Connect apps. This EAP release includes a new realm migration service and associated APIs, which will enable you to start integration and testing to support migration of app data to match the parent product realm.

Read the full blog announcement here.

11 November 2022

Announcement Single value metrics in developer console

To quickly identify the current state of your Forge apps, the developer console now displays values, as well as charts, for each metric. For more information, see View app metrics.

7 November 2022

Announcement Get comments and worklogs operations limited to 5000 items per call

Three months ago, we announced that a limit of 5000 items per call would be applied to get comments and worklogs operations. This limit is to mitigate potential issues if a call returns large numbers of comments or worklogs. As the deprecation period has elapsed, we will publish this limit on Nov 8, 2022.

More details

Note that “items" here refers to comments or worklogs.

What is changing?

Instead of returning all items from GET rest/api/{v:2|3|latest}/issue/{issueIdOrKey}/item, we are limiting the number of items returned to 5000 per call. Clients can get all the items using pagination.

The default value for the maximum number of items returned (maxResults) is now 5000. The order and shape in which the items are returned are unaltered.

Example

This request does not specify the maxResults request parameter:

1 2 3 4 5 // Request without specifying maxResults curl --request GET \ --url 'https://<jiraBaseUrl>/rest/api/2/issue/{issueIdOrKey}/item' \ --user 'username@atlassian.com:<token>' \ --header 'Accept: application/json'

Before the change, maxResults was set to the default value of 1048576 and generated a response like this:

1 2 3 4 5 6 7 // Before the change { "startAt":?, "maxResults":1048576, // default value if not specified "total":?, // the total number of items on the issue "items":[?] }

After this change, maxResults is set to 5000 and generates a response like this:

1 2 3 4 5 6 7 // After the change { "startAt":?, "maxResults":5000, // default value if not specified "total":?, // the total number of items on the issue "items":[?] }

This request specifies the maxResults request parameter as less than 5000:

1 2 3 4 5 //request specifying maxResults to a number less than 5000 curl --request GET \ --url 'https://<jiraBaseUrl>/rest/api/2/issue/{issueIdOrKey}/item?maxResults=100' \ --user 'username@atlassian.com:<token>' \ --header 'Accept: application/json'

The response (before and after this change) is as follows:

1 2 3 4 5 6 { "startAt":?, "maxResults":100, "total":?, // the total number of items on the issue "items":[?] }

 This request specifies the maxResults request parameter as more than 5000:

1 2 3 4 5 //request specifying maxResults to a number greater than 5000 curl --request GET \ --url 'https://<jiraBaseUrl>/rest/api/2/issue/{issueIdOrKey}/item?maxResults=7500' \ --user 'username@atlassian.com:<token>' \ --header 'Accept: application/json'

The response after this change truncates the response to 5000 items like this:

1 2 3 4 5 6 { "startAt":?, "maxResults":5000, // maxResults truncated from the requested 7500 down to 5000 "total":?, // the total number of items on the issue "items":[?] // the list of items returned will be truncated to 5000 items. }

 Why are we making this change?

Most issues contain less than 5000 comment or worklog items. However, there are some issues with large numbers of items. The backing system can overload when a client queries all those issue items through rest/api/{v:2|3|latest}/issue/{issueIdOrKey}/item.

What do you need to do?

If you are not working with items returned using GET rest/api/{v:2|3|latest}/issue/{issueIdOrKey}/items, no changes to your client code are needed.

If your client only needs to know about the total of the items on an issue, you can use total from the response, and no changes to your client code are necessary.

If you are confident that your client code does not set maxResults to greater than 5000 and you do not have issues with more than 5000 items, no changes are necessary.

If your client code sets maxResults to greater than 5000 and you have issues containing more than 5000 items, you may need to modify your code to make additional calls to get more items. However. as this is a paginated operation, clients that follow pagination best practices should need no changes. 

2 November 2022

Announcement Grouping metrics by app version in developer console

To help you debug your Forge apps, the developer console now lets you group your metrics by app version. Each chart now has a Group by dropdown menu, with the option to select Version. For more information, see Monitor your apps.

1 November 2022

Deprecation Notice Instead of relying on special default names, use Bulk Get groups API to fetch groups having certain permissions/ access

From April 30th, 2023, if your apps use hardcoded references to group names, they may stop working for customers with a new userbase configuration.

This includes references such as:

  • site-admins

  • jira-admins-<tenantName>

You can avoid this by switching to the newly added query parameter accessType in the bulk get groups GET /rest/api/3/group/bulk) API.

The API will get groups with a specific type of permission based on the accessType provided.

More details

After April 30th, 2023, we’ll start moving customers' site-level userbases to the organisation level.

If you’re developing an app, this will require you to stop using hardcoded references of special group names. Instead, utilise the API recommended above to dynamically fetch the same information.

This API will ensure the app continues to work for all customers, even after the userbase configuration changes.

Endpoint: GET /rest/api/3/group/bulk

Query parameter: accessType

Values: site-admin, admin, user.

Returns: name (name of the group) and groupId (group identifier)

20 October 2022

Announcement Link to app settings page is now displayed after the app installation via link

When a user installs your Forge app via installation link, we now display a link to your app settings page on the installation success popup:

The link will only show to users if you have an app settings page for your app. If you don’t have an app settings page, you can add one by including either the Jira admin page or Confluence global settings module in your app’s manifest.yml file.

More details

Please note:

  • The installation success notification can currently only display one link to a single app configuration page. If the confluence:globalSettings or the jira:adminPage have both useAsConfig or useAsGetStarted pages specified, then only the link to the useAsConfig page will be displayed.

  • The link to an app’s configuration page will only be displayed if the direct distribution link is generated for a single product. For example, the link to the configuration page will not be displayed if an app is installed on both Jira and Confluence, but it will be displayed if the app is installed on only Confluence.

  • This feature isn't available for Compass apps.

26 September 2022

Announcement Forge app alert editing and alert history now available in developer console

In the developer console, you can now edit the title and description of your app alert, as well as view alert history. You can also see the metrics highlighted when value is below the threshold. For more information, see Manage app alerts.

12 September 2022

Announcement Bulk get groups API enhanced to support group lookups based on access type

We have added a new optional query parameter, accessType to the bulk get groups API to return only groups with a specific type of permission based on the accessType provided. This is an enhancement to the existing bulk get groups (GET /rest/api/3/group/bulk) API in Jira to support fetching groups.

Endpoint: GET /rest/api/3/group/bulk

Query parameter: accessType

Values: site-admin, admin, user.

Returns: name (name of the group) and groupId (group identifier)

If your apps have hardcoded references to group names, particularly for default groups (for example, site-admins, jira-admins-<tenantName>) in their configurations, it is recommended to start using this API to get groups to ensure your app continues to work for all customers.

More details

Endpoint and descriptions

Endpoint

Description

Notes

GET /rest/api/3/group/bulk?accessType=site-admin

Returns list of groups that have site administration access with return values of name and groupId

Jira is now moving away from using groupName to using groupId as the identifier for groups. To achieve this the groupName is no longer going to be immutable and Jira will use external groupId as the immutable reference to groups. We are making this change to support the functionality to rename groups. The ability to rename groups is essential if you have multiple sites to migrate the site-level userbases to the organisation level.

GET /rest/api/3/group/bulk?accessType=admin

Returns list of groups that have Jira administration access with return values of name and groupId

GET /rest/api/3/group/bulk?accessType=user&applicationKey=jira-software

Returns list of groups that have Jira Software access with return values of name and groupId

7 September 2022

Deprecation Notice Deprecation of group name fields in the Jira REST API

The name field in the Jira REST API operations that include group details is deprecated and replaced with groupID.

We’re changing this to enable support for functionality to rename groups. To achieve this, groups need an immutable identifier rather than the inherently mutable group name identifier. Thus, we’re removing the use of group name as the identifier and replacing it with groupID.

The name field will be removed on 28 February 2023.

See the Adding support for groupID field in Jira REST APIs, expressions types developer community post for more details on the change.