Preparing for Jira Software 10.0 and Jira Service Management 10.0

This documentation is intended for Jira developers who want to ensure that their existing apps are compatible with Jira Software 10.0 and Jira Service Management 10.0.

Version history

Downloads

All development releases are available for download on the Jira Early Access Program downloads page.

Known issues

The following subsystems are known to be not functional in this release:

• DVCS doesn’t work
• There are log warns when entering any page, method needs allowlisting: com.atlassian.jira.projects.issuenavigator.DefaultIssueRenderService$FakeAction#getText(java.lang.String)
• Missing translations on the Admin panel
• After enabling a dark feature for an async webhook and restarting Jira, webhook payloads fail to send Parent Link data

Coming up next

The next EAP release of Jira Software 10.0 and Jira Service Management 10.0 won’t bring any further functional or technical changes as Platform 7 integration closed the planned scope. We’ll focus on quality aspects and ensuring further system stability instead.

Changes introduced in EAP 06 (11 July 2024)

For more details about what's in scope of this EAP release, check out the following updates:

• App usage page issue is fixed resolved. Read more on Atlassian Developer Community
• The error when accessing dashboard on Jira Activity Stream Gadget is fixed
• Disabled debug mode for velocity method allowlist to check the completeness of the list.If you think that your method is blocked, then look for the following log: Invocation blocked as method is not allowlisted: <method>). Learn how to configure the Velocity method allowlist

Changes introduced in EAP 05 (4 July 2024)

For more details about what's in scope of this EAP release, check out the following updates:

• added Upgrade to Platform 7
• added Avoid surprises with the change calendar
• added OpenAPI Standard for REST API documentation
• added Jira Core dialogs migrated to AUI Dialog 2
• added Velocity template and allowlist security improvements
• added New default endpoint security annotations for filters
• added Custom JSPs are blocked unless loaded by an action
• added Frontend API changes
• removed Removal of previously deprecated feature flags in EAP 05
• removed Removal of previously deprecated methods and classes in EAP 05
• removed Removal of previously deprecated REST API endpoints in EAP 05

Upgrade to Platform 7

added Jira Software Jira Service Management

Jira Software 10.0 and Jira Service Management 10.0 will include an upgrade to Atlassian Platform 7. This upgrade puts us in a better position to respond to security changes with reduced disruption and breaking changes for your apps. Prepare for the Platform 7 upgrade

Avoid surprises with the change calendar

added Jira Software Jira Service Management

Minimize service disruptions and plan changes to critical systems efficiently by creating freeze and maintenance windows in the change calendar. With all events scheduled in the calendar, change approvers can easily assess requests from change requestors and adjust schedules to avoid conflicts.

To start using the change calendar in your project:

1. Navigate to Project settings and select Change management.
2. Enable the change calendar. It is enabled by default in projects that use the ITSM template.
3. In the Default calendar view section, select the start and end date fields. Change requests are plotted on the calendar based on the data in the custom fields you select here.
4. Select Save.

The change calendar is now available to all agents of this project from the sidebar.

OpenAPI Standard for REST API documentation

added Jira Software

REST API documentation for Jira Core and Jira Software that are in OpenAPI standard and in a refreshed graphical form are already available. This is the first time REST API documentation for Jira Core and Jira Software are no longer split. What’s more, the content has been reviewed and updated. Check out the documentation

Jira Core dialogs migrated to AUI Dialog 2

added Jira Software Jira Service Management

Most instances of AUI Dialog 1 in Jira Core have been migrated to AUI Dialog 2. AUI Dialog 1 will be removed from Jira completely, so if your app uses that component, make sure to migrate to AUI Dialog 2.

Velocity template and allowlist security improvements

added Jira Software Jira Service Management

We're making steps towards verifiably secure installation directories for all Data Center products. These changes not only increase the difficulty for an attacker to exploit filesystem access, but also allow customers to verify the state of the product installation.

From Jira 10.0, all Velocity files stored on the filesystem (for example, shared, local home, or any other) will need to be explicitly allowlisted and must be of a specific file type. Files stored inside .jar files and bundled within plugins will not be affected.

In addition, all method invocations within a Velocity template must be explicitly allowlisted. For more information, visit Configuring the Velocity method allowlist and Configuring the Velocity file and file type allowlist.

New default endpoint security annotations for filters

added Jira Software Jira Service Management

In the EAP04, we introduced security annotations for Webwork actions, servlets, and REST endpoints. This EAP extends the mechanism to filters.

Each filter must be annotated following the same rules as the other endpoint types. If a filter isn't annotated, it's treated as @LicensedOnly by default. If a user executes a request with permissions that are lower than required, the filter will be skipped.

Filters located after-encoding and before-login are executed before a user is authenticated (so we don’t know who the user is). Such filters can only be marked as @UnrestrictedAccess or AnonymousSiteAccess. Any stronger annotation will result in the filter never being run.

Learn more about new default endpoint security annotations

Custom JSPs are blocked unless loaded by an action

added Jira Software Jira Service Management

We blocked direct requests to JSP files. JSP files can now be only loaded when requested by an action.

Frontend API changes

added Jira Software

We’re improving and updating the Code sharing section of the Jira Data Center front-end API.

This EAP brings the following additions:

• the inclusion of Jira-specific API modules, such as requested Jira Events
• extensions and updates to common libraries
• the introduction to particular versioning of common libraries and alias module type
• annotations to modules on the UPM level and better descriptions in the code

Regular modules for the common libraries are versioned up to the minor version (x.y), for example under the jira-frontend-api:react-18.3 web-resource Jira provides React 18.3.1, as of now. The patch version (aka bugfix) can be changed at any time, for example the same web-resource can provide React 18.3.2 in the future.

The alias modules are versioned up to the major version (x), for example under the jira-frontend-api:react-18 web-resource Jira provides React 18.3.1, as of now. The minor version can be changed at any time, for example the same web-resource can provide React 18.4.0 in the future.

This EAP brings the following changes to the existing modules:

The full list of available modules:

Removal of previously deprecated feature flags in EAP 05

removed jira software jira service management

In this EAP release, we’ve removed the following feature flags:

• com.atlassian.jira.agile.darkfeature.burnupchart
• optimistic.transitions
• com.atlassian.jira.advanced.audit.log
• velocity.chart.ui

Removal of previously deprecated methods and classes in EAP 05

removed jira software jira service management

In this EAP release, we’ve removed yet another set of methods and classes that have been deprecated since Jira Software 9.x and Jira Service Management 5.x.

Here’s what’s been removed:

Removal of previously deprecated REST API endpoints in EAP 05

removed jira software jira service management

In this EAP release, we’ve removed yet another set of REST API endpoints that have been deprecated since Jira Software 9.x and Jira Service Management 5.x.

Here’s what’s been removed:

Changes introduced in EAP 04 (28 May 2024)

For more details about what's in scope of this EAP release, check out the following updates:

• added Java 17 becomes the default
• added Jira Software dialogs migrated to AUI Dialog 2
• added New default endpoint security annotations
• removed Removal of binary installers
• removed Removal of previously deprecated feature flags
• removed Removal of previously deprecated methods and classes
• removed Removal of previously deprecated REST API endpoints

Java 17 becomes the default

added jira software jira service management

Jira Software 10.0 and Jira Service Management 10.0 have been recompiled in Java 17, which becomes the default language level. This means that from now on, earlier versions of Java will no longer be supported.

Jira Software dialogs migrated to AUI Dialog 2

The following dialogs in Jira Software are now using the AUI Dialog 2 component:

• Release version
• Create status
• Select kanban transition
• Reopen sprint
• Remove status
• Complete sprint
• Complete parent
• Update filter query
• Convert workflow
• Version quick create
• Add column
• Delete board

AUI Dialog 1 will be removed from Jira completely, so if your app uses that component, make sure to migrate to AUI Dialog 2.

New default endpoint security annotations

added Jira Software Jira Service Management

We’re introducing a new set of annotations to improve endpoint security by giving you better control over access to endpoints. These annotations have been revised to ensure that only the intended users access your application endpoints.

Starting from Jira Software 10.0 and Jira Service Management 10.0, when no annotation is specified, only licensed users will be able to access resources. To change this, annotate all endpoints that require lower security clearance level. You can also annotate all admin and system admin endpoints to provide tighter security measures.

To prepare your application for this change, refer to Prepare your Data Center app to comply with secure endpoint defaults. Here’s a general summary of the process:

1. Mark your endpoints with appropriate security annotations:
   If you don’t use any annotations, all endpoints are treated as marked with @LicensedOnly by default.
   • SystemAdminOnly restricts access to an endpoint to system admins only.
   • AdminOnly restricts access to admins and system admins. Note that this excludes project admins. In fact, there’s no separate annotation for project admins.
   • LicensedOnly enables access for licensed Jira users.
   • UnlicensedSiteAccess is for Jira Service Management portal customers, who aren’t licensed Jira users.
   • AnonymousSiteAccess is for endpoints that should allow anonymous access only if anonymous access has been turned on with the Allow sharing filters/dashboards with anyone on the web option.
   • UnrestrictedAccess is for endpoints that should always allow access by unauthenticated users, even if anonymous access is turned off.
2. Run all your tests and act accordingly:
   • If all tests pass, you’re done (provided you have proper coverage).
   • If a test fails, re-run it with TRACE logging enabled for the following classes:

     1
     2
     <!-- TRACE logging for Stronger Defaults -->
     <!-- Jira servlets -->
     <Logger name="com.atlassian.jira.web.filters.annotations.SecurityAnnotationsFilter" level="TRACE" additivity="false">
         <AppenderRef ref="filelog"/>
     </Logger>
     
     <!-- Webwork actions -->
     <Logger name="com.atlassian.jira.web.dispatcher.JiraWebworkActionDispatcher" level="TRACE" additivity="false">
         <AppenderRef ref="filelog"/>
     </Logger>
     
     <!-- REST -->
     <Logger name="com.atlassian.plugins.rest.v2.security.authentication.AuthenticatedResourceFilter" level="TRACE" additivity="false">
         <AppenderRef ref="filelog"/>
     </Logger>
     
     <!-- Plugin servlets -->
     <Logger name="com.atlassian.jira.plugin.servlet.ServletModuleContainerServlet" level="TRACE" additivity="false">
         <AppenderRef ref="filelog"/>
     </Logger>
     

3. Check the logs to find the endpoints that blocked access and:
   • If the test was incorrectly setup (for example, missing authentication), update it.
   • If the annotation was too strict, use a weaker one.
   • If the endpoint comes from Jira and you believe it is misconfigured (too strict), contact us describing your use case so that we can review it and potentially adjust the annotation level.

Removal of binary installers

removed jira software jira service management

Starting from Jira Software 10.0 and Jira Service Management 10.0, the .bin and .exe installers will no longer be available. You can still install Jira using the .zip and .tar.gz distributions.

Removal of previously deprecated feature flags

removed jira software jira service management

In this release, we’ve removed the following feature flags:

• jira.quick.search
• com.atlassian.jira.custom.csv.escaper
• atlassian.cdn.static.assets

Removal of previously deprecated methods and classes (EAP 04)

removed jira software jira service management

In this EAP release, we’ve removed yet another set of methods and classes that have been deprecated since Jira Software 9.x and Jira Service Management 5.x.

Here’s what’s been removed:

Removal of previously deprecated REST API endpoints (EAP 04)

removed jira software jira service management

In this EAP release, we’ve removed yet another set of REST API endpoints that have been deprecated since Jira Software 9.x and Jira Service Management 5.x.

Here’s what’s been removed:

Changes introduced in EAP 03 (6 May 2024)

For more details about what’s in scope of this EAP release, check out the following updates:

• added Allowlist your Velocity files on the filesystem
• added Allowlist your Velocity template class and method invocations
• added Turn off the lights with dark theme
• added Upgrade to Groovy 4
• removed Breaking changes to the Java and REST APIs in EAP03
• removed Disabling runtime JavaServer Pages compilation
• removed End of support for the H2 database engine
• removed Removal of dependencies
• removed Removal of previously deprecated methods and classes
• removed Removal of previously deprecated REST API endpoints
• removed Unbundling of atlassian-frontend-runtime-plugin
• deprecated All instances of AUI Dialog 1 migrated to AUI Dialog 2
• deprecated Deprecated and removed feature flags
• deprecated Deprecation of http-builder from the JSM package
• deprecated Deprecation of jquery-migrate 1.x

Allowlist your Velocity files on the filesystem

added Jira Software Jira Service Management

We’re making steps towards verifiably secure installation directories for all Data Center products. This change not only increases the difficulty for an attacker to exploit filesystem access, but also allows customers to verify the state of the product installation.

Starting from Bamboo 10.0, Bitbucket 9.0, Confluence 9.0, Crowd 6.0, Jira Software 10.0, and Jira Service Management 10.0, all Velocity files stored on the filesystem (that is, shared, local home, or other) will need to be explicitly allowlisted. Files stored inside of .jar archives and bundled within plugins won’t be affected.

In Confluence, Jira Software, and Jira Service Management, you can update the Velocity engine configuration to add files to the allowlist. This must be repeated for each new engine instance.

The following property is cached when the Velocity engine starts, enhancing performance and making it more difficult for attackers to disable.

1
2
velocity.addProperty(Velocity.RESOURCE_FILE_ALLOWLIST, "relative/file/path.vm")

However, we recommend migrating them to the database in every product.

Allowlist your Velocity template class and method invocations

added Jira Software Jira Service Management

Similarly to Confluence 9.0, we’re planning to migrate the method invocations in Velocity templates to an allowlist approach. All method invocations within a Velocity template will be explicitly allowed using a newly introduced annotation or app module descriptor.

The following classes and methods are allowed:

• introspector.allowlist.classes = java.io.Serializable
• java.io.ObjectInputValidation
• java.lang.reflect.Proxy
• net.sf.hibernate.proxy.HibernateProxy
• org.springframework.cglib.proxy.Facto
• introspector.allowlist.methods = getEditVM
• removeHtmlTags
• htmlEncode
• escapeHtml
• getLabelSearchPath
• encodeHtml
• encodeForHtml

Turn off the lights with dark theme

added Jira Software Jira Service Management

In Jira Software 10.0 and Jira Service Management 10.0 EAP 03, dark theme becomes partially available for the first time so that you can start preparing your Data Center app to support it and allow us to gather more feedback.

For more information about adjusting your app to dark theme, visit Prepare your Data Center app for the dark theme.

Known issues

The following components don’t support dark theme yet:

• Dashboards
• Plans
• Help us improve Jira dialog
• Automation for Jira
• Parts of the administration area
• Some reports

The following areas have known visual issues:

• Profile summary page
• Some parts of the administration area:
  • Troubleshooting and support page
  • Administering personal access tokens page
  • Terminology page
  • Content delivery network page
  • Rate limiting page
• Backlog view
• Create project dialog

Upgrade to Groovy 4

added Jira Service Management

To improve security, functionality, and syntax support, we’re planning to upgrade from Groovy 2 to Groovy 4 in Jira Service Management 10.0. If you’ve been using Groovy scripts in Assets, test your existing scripts against this EAP release of Jira Service Management 10.0 or the Groovy 4 console.

Here’s a rundown of the most important breaking changes:

• The syntax of the switch statement and the intersect() array method has changed.
• The resolutions of isser/getter properties has changed.
• picocli package is no longer bundled, use an extra @Grab instead.
• ImportCustomizer is applied once per module (previously it was applied once per class).
• groovy-jaxb, groovy-bsf, and StaticTypeCheckingVisitor#collectAllInterfacesByName modules are no longer available.
• Antlr2 based parse is no longer available (use the new Parrot parser).
• The formatting of some CLI help messages has changed.

1
2
java.lang.RuntimeException: Unable to load FastStringService
  at org.apache.groovy.json.internal.FastStringUtils.getService(FastStringUtils.java:56) ~[?:?]
  at org.apache.groovy.json.internal.FastStringUtils.toCharArray(FastStringUtils.java:66) ~[?:?]
  at org.apache.groovy.json.internal.BaseJsonParser.parse(BaseJsonParser.java:114) ~[?:?]
  at groovy.json.JsonSlurper.parseText(JsonSlurper.java:205) ~[?:?]

The following table lists the changes to the names of classes, packages, and modules.

For the full list of breaking changes, check out:

• Groovy 3.0 release notes
• Groovy 4.0 release notes

Breaking changes to the Java and REST APIs in EAP03

removed Jira Software Jira Service Management

We’ve removed access to a number of dependencies from Jira Software 10.0 and Jira Service Management 10.0, which are currently accessible in Jira Software 9.x and Jira Service Management 5.x:

Disabling runtime JavaServer Pages compilation

removed Jira Software Jira Service Management

JavaServer Pages (JSP) runtime compilation will be disabled in Jira Software 10.0 and Jira Service Management 10.0. JSP files added to the Tomcat directory that aren't shipped with the product won’t be served. Furthermore, no modifications to the JSP files will be reflected. Use Soy or Velocity templates instead.

End of support for the H2 database engine

removed Jira Software Jira Service Management

To resolve several security vulnerabilities, the JDBC driver for the H2 database engine is no longer bundled with Jira Software 10.0 and Jira Service Management 10.0. This means that we’re removing it from the list of supported platforms. Additionally, you’ll no longer be able to evaluate Jira Software 10.0 and Jira Service Management 10.0 using H2.

Removal of dependencies

removed Jira Software

In the previous EAP, we’ve announced our plansto remove access to a number of dependencies from Jira Software 10.0, which are currently accessible in Jira Software 9.x. Those dependencies have been removed in EAP 03. Here's the complete list of what’s been removed:

Removal of previously deprecated methods and classes

removed Jira Software Jira Service Management

In this EAP release, we’ve removed yet another set of methods and classes that have been deprecated since Jira Software 9.x and Jira Service Management 5.x.

Here’s what’s already been removed:

Here’s what you can expect us to remove in the future:

Removal of previously deprecated REST API endpoints

removed Jira Software Jira Service Management

In this EAP release, we’ve removed yet another set of REST API endpoints that have been deprecated since Jira Software 9.x and Jira Service Management 5.x.

Here’s what’s been removed:

Here’s what we’re planning to remove in the future:

Unbundling of atlassian-frontend-runtime-plugin

removed Jira Software

The atlassian-frontend-runtime-plugin provided common polyfills and the regenerator-runtime web resource. Since none of the supported browsers need these polyfills any longer and the plugin has been deprecated since Jira Software 9.2.0, it’ll be removed in Jira Software 10.0.

If your code is still using any web resources from this plugin, the following warnings may appear in in Jira logs:

1
2
This webresource is empty! All supported browsers no longer need these polyfills. Please remove your dependency on the "atlassian-frontend-runtime-plugin".

1
2
This webresource is deprecated and will soon be removed! All supported browsers no longer need the runtime. Please rebuild your sources without expecting the "regenerator-runtime" to be available.

The former babel-polyfill, core-js, custom-elements-v1, fetch, and focus-visible were already empty web resources, while the regenerator-runtime was still provided.

All instances of AUI Dialog 1 will be migrated to AUI Dialog 2

deprecated Jira Software Jira Service Management

We’re working on migrating all of the instances of the deprecated AUI Dialog 1 remaining throughout Jira Core and Jira Software to AUI Dialog 2.

We’re also planning to remove the following web resources as part of this work:

• com.atlassian.auiplugin:dialog
• jira.webresources:jira-accessible-dialog

Deprecated and removed feature flags

deprecated Jira Service Management

In this EAP release, we’ve removed the jira.users.and.roles.page.in.react feature flag.

The following feature flags have been deprecated and are marked for removal in an upcoming EAP release of Jira Software 10.0 and Jira Service Management 10.0:

• jira.quick.search
• com.atlassian.jira.custom.csv.escaper
• atlassian.cdn.static.assets
• com.atlassian.jira.agile.darkfeature.burnupchart
• optimistic.transitions
• com.atlassian.jira.advanced.audit.log
• velocity.chart.ui

Deprecation of http-builder from the JSM package

deprecated Jira Service Management

The http-builder library is no longer actively maintained and it’ll be removed from Jira Service Management 10.0. If you’re using this library in your Groovy scripts, we recommend that you switch to the native Groovy GET and POST methods.

Deprecation of jquery-migrate 1.x

deprecated Jira Software

We’re planning to upgrade jQuery and as part of that effort, we’ll also deprecate jquery-migrate 1.x in Jira Software 10.0 to remove it entirely in the next feature release.

Jira Software 10.0 won’t contain the upgraded jQuery and will be focused mainly around the deprecation of jquery-migrate 1.x and its removal from the superbatch Web Resource.

For more information on the deprecation of jquery-migrate 1.x, visit the jQuery Upgrade Guide. For queries about jquery-migrate 1.x warnings, refer to jQuery Migrate Warnings. For future jQuery updates, refer to the 3.0 and 3.5 Upgrade Guides.

Changes introduced in EAP 02 (27 March 2024)

For more details about what’s in scope of this EAP release, check out the following updates:

• added Centralized dependency management
• added Jira Software Data Center is migrated and fully exposes RESTv2
• removed Breaking changes to the Java and REST APIs in EAP02
• deprecated Planned removal of deprecated dependencies

Centralized dependency management

added Jira Software

Centralized dependency management in Jira Software 10 introduces a set of Maven POM files known as a Bill of Materials (BOM), which list the dependencies available to third-party apps.

This system aims to streamline responding to security threats and enhance efficiency of developing for Jira by ensuring that dependencies are uniform and up-to-date. This approach minimizes runtime errors such as NoSuchMethodException and allows for quicker responses to security vulnerabilities within these dependencies.

There are multiple BOM files, each serving different functions:

• jira-api-bom: This BOM is designed for external products. It offers a centralized location for managing the dependencies of external products, ensuring that they’re using the correct, up-to-date versions of dependencies.
• jira-deprecated-api-bom: This BOM lists libraries that may undergo changes or be removed from the public Bill of Materials in future updates.
• jira-internal-bom: This BOM is intended for internal products. It provides a centralized location for managing internal dependencies, ensuring consistency across all internal products.
• jira-bundled-plugins-bom: This BOM manages the versions of apps bundled with Jira.

Using artifacts for version management

BOMs (Bill of Materials) are Maven modules of the pom packaging type, which are designed to facilitate the management of imported dependencies as detailed in the Maven documentation.

Each BOM contains dependency management sections rather than direct dependencies. To use a BOM, you should first include it as a dependency with the import scope. For example:

1
2
<dependency>
    <groupId>com.atlassian.jira</groupId>
    <artifactId>jira-api-bom</artifactId>
    <version>${jira.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

Subsequently, other dependencies should be explicitly defined manually with the scope provided, omitting version specifications. The versions will be configured through the imported BOM artifacts. For example:

1
2
<dependency>
    <groupId>com.atlassian.security</groupId>
    <artifactId>atlassian-secure-utils</artifactId>
    <scope>provided</scope>
</dependency>

Adopting centralized BOMs in App Development

To adopt centralised BOMs, follow these steps:

1. Remove the jira-project dependency management import.
2. Add jira-api-bom as a dependency with scope import.
3. Consider adding jira-deprecated-api-bom if needed, but note that these dependencies are marked as deprecated and will be removed in future versions.
4. Remove redundant dependency management sections from your poms (for artefacts covered by the bom)
5. Since BOM does not define scope, if your dependency management section used to contain scope definition, you must now add it to the actual dependency declaration.
6. Conduct deep analysis of the dependency tree to ensure all dependencies are correctly managed, and no discrepancies exist between versions. All dependencies listed in the bom files
7. Ensure that dependencies, especially those in the provided scope, don't have a version field to allow the central pom to define it. This ensures consistency and prevents runtime issues.

Jira Software Data Center is migrated and fully exposes RESTv2

added Jira Software

For more information, check out the RESTv2 migration guide.

Breaking changes to the Java and REST APIs in EAP02

removed Jira Software

We’ve removed access to a number of dependencies from Jira Software 10.0 and Jira Service Management 10.0, which are currently accessible in Jira Software 9.x:

Planned removal of deprecated dependencies

deprecated Jira Software

We’re planning to remove access to a number of dependencies from Jira Software 10.0, which are currently accessible in Jira 9.x: