JIRA 3.7 Upgrade Guide

JIRA 3.7 Upgrade Notes

This page lists a few things to be aware of when upgrading from previous releases of JIRA to JIRA 3.7. To perform the actual upgrade, see the upgrade documentation.

Note: If you are upgrading from a pre-3.6.5 release, please also refer to the relevant JIRA 3.x Upgrade Guides.

Database Schema Changes

Due to the upgrade of HSQLDB, and to improve compatibility with Firebird and Frontbase, various database tables and columns have been renamed. For more details on the changes please see the JIRA 3.7 Database Schema Changes document.

Therefore, the easiest way to upgrade to JIRA 3.7 is to follow the Upgrading JIRA safely instructions.

If in the past, instead of performing an XML backup and restore, you have been upgrading by "pointing" new version of JIRA at an old database, this is still possible, however the procedure is more complicated. You will need to use SQL scripts to perform database schema changes. For more information please see the SQL Scripts for 3.6.x to 3.7 schema upgrade document.

Request Context Changes

In order for plugins, customfields and portlets to function better outside of a web-context (e.g.: displaying a customfield in an e-mail), all direct references to the HttpServletRequest have been replaced by a VelocityRequestContext. If you have deployed your own plugins, customfields or portlets that use the HttpServletRequest directly (i.e.: any references to ${req}) than they should be changed to use the new ${requestContext} object. The ${requestContext} is an implementation of the VelocityRequestContext interface.

Currently the ${requestContext} supports the following properties:

• ${requestContext.baseUrl} - Returns the same as HttpServletRequest.getContextPath() or the base URL configured in your JIRA instance if no HttpServletRequest is available
• ${requestContext.requestParameters} - Returns an implementation of RequestContextParameterHolder or null if no HttpServletRequest is available
• ${requestContext.requestParameters.servletPath} - Returns the same as HttpServletRequest.getServletPath()
• ${requestContext.requestParameters.requestURL} - Returns the same as HttpServletRequest.getRequestURL()
• ${requestContext.requestParameters.queryString} - Returns the same as HttpServletRequest.getQueryString()

Integrity Checks

In JIRA 3.7 Database Integrity Checks (available from the Administration section) have been re-written to run as multiple transactions, which increased the throughput of the system while the checks are running. In large JIRA 3.6 (and earlier) installations, integrity checks could cause database lock escalation and stop users from performing operations (e.g. viewing issues).

Please note, that due to the change, each integrity check became about 10% slower.

As integrity checks are quite database intensive operations, it is still recommended to run them during off-peak hours (i.e. while the system is not under heavy load).

Change of commentLevel to groupLevel in the Comment and TransitionWorkflow jelly tags

We have changed the AddComment and TransitionWorkflow jelly tag attribute that specifies the group visibility level from 'commentLevel' to be 'groupLevel'. If you have existing jelly tags that use this attribute it will need to change. This was done so that we could introduce the 'roleLevel' attribute which allows you to specify a project role based visibility. Only one of the two attributes can be specified at a time.

Change of level to grouplevel in the XML view of a Comment

1. We have changed the XML view of a comment, as seen in the XML view of an Issue to contain either a 'grouplevel' attribute or a 'rolelevel' attribute. This attribute defines the visibility level specified on the comment. In the past the 'grouplevel' attribute was simply 'level'. If you have any existing custom code that expects the 'level' attribute in the Comment XML it must change to expect 'grouplevel'.
2. In previous versions of JIRA the XML view of the <comment> tag level attribute was always shown, even if there was no value for the level, it was rendered as an empty attribute. We have changed it so that the attributes themselves (grouplevel and rolelevel) do not display if there is no value.

Change to the RemoteComment object used via SOAP/RPC plugin

The RemoteComment object and therefore the remote SOAP/RPC api has changes to almost all properties. The 'roleLevel' attribute was added and the following attributes have changed:

1. level -> groupLevel
2. datePerformed -> created
3. username -> author

ActionManager removed

The ActionManager interface has been removed and its functionality has been delegated to new interfaces. For details please refer to ActionManager Removed documentation

Removal of 'Backend Actions'

1. We have removed the 'Backend Action' com.atlassian.jira.action.action.WorklogCreate if you were using this class in a plugin or custom code you will now need to use the com.atlassian.jira.issue.worklog.WorklogManager this now has method calls to return worklogs for a given user+issue and also create worklog entries.
2. We have removed the 'Backend Action' com.atlassian.jira.action.action.ActionCreate if you were using this class to create comments you will need to modify your code to use one of the create methods on the com.atlassian.jira.bc.issue.comment.CommentService

Issue Events

We have modified the com.atlassian.jira.event.issue.IssueEvent class to no longer use GenericValues. The GenericValue representing the comment is replaced by com.atlassian.jira.issue.comments.Comment class and the GenericValue representing the worklog is replaced by com.atlassian.jira.issue.worklog.Worklog class. If you have a custom listener in a previous version of JIRA this will need to be updated to use the newer IssueEvent class and com.atlassian.jira.event.issue.IssueEventDispatcher.dispatchEvent(...) methods.

Renaming of XML export file

By popular request, the XML filename (that is, the default filename when you choose to save the XML view in the Issue Navigator) has been changed from  issuenavigator.jspa to SearchRequest.xml. Should you have any external systems or programs that utilise the exported XML file, please be aware of the changed filename.

Confluence Users Only - Pre 2.2.10 Confluence Must Be Patched To Use JIRA Issues Macro

JIRA 3.7 Downgrade Notes

Once you have upgraded to JIRA 3.7, downgrading to a previous version is not a straightforward task and is not recommended. Please be aware that in JIRA 3.7 the database schema has changed.

If upgrade to JIRA 3.7 fails, the best way to proceed is to go back to the previous version of JIRA you were using, and to the latest pre-upgrade data that you have. The exact steps for doing this depend on how you have upgraded JIRA.

If you have created a new database for JIRA 3.7 by following the Upgrading JIRA safely instructions, you should be able to simply shutdown JIRA 3.7 and bring up the old version of JIRA your were using. The old version should be configured to use its old (unupgraded) database.

If you have upgraded JIRA by pointing JIRA 3.7 to an older database (and ran the SQL Scripts to upgrade the database schema), then you will need to:

1. Create a new database
2. Configure the old version of JIRA you were using to point at the new (empty) database
3. Restore the latest pre-upgrade backup that you have
4. Start the old JIRA installation