JIRA 4.2 Upgrade Guide

On this page:

Upgrading from JIRA 4.1 to 4.2

General Upgrade Instructions

Please follow the instructions in the general JIRA upgrade guide (non-version specific), as well as the JIRA 4.2-specific instructions in the sections below. The general upgrade guide contains important tasks that are essential for getting your upgraded JIRA instance to work correctly (e.g. merging jira-application.properties customisations from the old instance to the upgraded instance).

Changes in jira-application.properties

If you are merging your old and new configuration files, as described in the Upgrade Guide, the following tables list the changes which have been made to the jira-application.properties file in JIRA 4.2.
The purpose of each new property is documented in the jira-application.properties file itself.

Changes in seraph-config.xml and Crowd Integration

When merging your old and new configuration files, as described in the Upgrade Guide, please take extra care with the seraph-config.xml file, since this file contains several new entries in JIRA 4.2.

If you simply copy your old seraph-config.xml to your new 4.2 installation, then:

• Your users will find that the Remember my login... functionality will not work.
• If you had Crowd integrated with JIRA prior to upgrading, your Crowd integration with JIRA will no longer work after the upgrade.

The following table lists the changes to the seraph-config.xml file in JIRA 4.2:

<param-name>login.cookie.key</param-name>
<param-value>seraph.os.cookie</param-value>

<param-value>seraph.rememberme.cookie</param-value>

<param-name>autologin.cookie.age</param-name>
<param-value>31536000</param-value>

<param-value>1209600</param-value>

<init-param>
    <param-name>cookie.encoding</param-name>
    ....
<init-param>

<authenticator class=
    "com.atlassian.crowd.integration.seraph.JIRAAuthenticator"/>

<authenticator class=
    "com.atlassian.crowd.integration.seraph.v22.JIRAAuthenticator"/>

<param-name>config.file</param-name>
<param-value>seraph-paths.xml</param-value>

<param-value>seraph-paths.xml</param-value>

Non-bundled Plugins

If you use or develop a plugin that is not bundled with JIRA, then please read the Updating JIRA Plugins for JIRA 4.2 guide. This guide describes changes in JIRA 4.2 which may affect the compatibility of your plugin with JIRA 4.2.

Updated Toolkit Plugin for JIRA 4.2

If you use the Toolkit Plugin with JIRA, you will need to update it to at least version 0.15 for compatibility with JIRA 4.2.

Labels Plugin is Now in Core JIRA

The Labels plugin functionality is now part of JIRA core, so the Labels plugin should no longer be installed. If an earlier version of the Labels plugin is installed when upgrading to JIRA 4.2, JIRA will not start up. An appropriate error message wil be shown in the logs and UI.

All existing labels will continue to exist. As part of the 4.2 upgrade process, any data in a pre-existing "Labels" custom field (e.g. if you were using the Labels plugin) will be migrated to the new "Labels" system field.

Time Tracking Changes

Prior to JIRA 4.2, the Original Estimate and Remaining Estimate fields could not be edited independently and their values would be synchronised after logging work.

From JIRA 4.2, time tracking is more flexible. The values in these fields are not tied to each other and they can be edited independently. Additionally, it is now possible to change the Original Estimate value after work has been logged.

Clean installations of JIRA 4.2 will automatically have access to this more flexible time tracking feature. However, if you are a JIRA customer upgrading to version 4.2, JIRA's time tracking feature will be set to Legacy Mode so that users can continue to operate JIRA's original work logging features as usual.

If you have upgraded to JIRA 4.2 and wish to use the newer and more flexible time tracking features, you will need to disable Legacy Mode in JIRA's Time Tracking settings. (You will need to deactivate Time Tracking before you can disable Legacy Mode.)

Changes to Sub-Tasks

On new installations of JIRA 4.2 or later, Sub-Tasks are enabled by default. However, upon upgrading to JIRA 4.2, your Sub-Task configuration will remain unchanged. Therefore, if Sub-Tasks are disabled on your JIRA site before upgrading to JIRA 4.2, Sub-Tasks will still be disabled after the upgrade is completed.

Changes to Attachment Creation

Attachments are uploaded 'inline', that is when a user selects a file it is immediately uploaded to the server. A temporary attachment will be created on the server for this file. Once the form the file was uploaded in is submitted, the temporary attachment will be converted to a real attachment for the issue in question. Due to this improvement, limiting the number of file upload boxes via the jira.attachment.number property is no longer necessary and can safely be removed from your jira-application.properties file.

System Path Changes for Attachments, Indexes, Automated Backups and Services

For security reasons, from JIRA 4.2, you are no longer able to customise directories for storing the following types of JIRA content:

• attachments,
• search indexes,
• automated XML backups and
• other JIRA services

JIRA now stores these types of content in 'Default' directories within the JIRA home directory.

• For new installations of JIRA 4.2, these types of content will only be stored within their default directories.
• If you upgrade to JIRA 4.2 from an earlier JIRA version that used custom directories to store these types of content, JIRA 4.2 will respect these custom directories. However, once you change to using the default directory for storing any of these types of content, you can no longer specify nor use a custom directory for that content type.

Note that you will need to copy your attachments to your JIRA Home Directory if you set your Attachments path to "default".

If you upgrade to JIRA 4.2 on a different machine (or different operating system) and previously:

• used custom directories to store attachments or search indexes, JIRA will warn you that it cannot create these custom directories if they do not exist on the new system.
  Hence, you can either:
  • Choose to use JIRA's default directories to store these types of content, or
  • Shutdown JIRA, recreate those custom directories (with permission for JIRA to write to them) and start the JIRA upgrade process again with the same XML backup.
    To identify these custom directories, JIRA will indicate them during the XML backup restore process.

• used custom storage directories for any JIRA service (such as an automated XML backup), JIRA will respect these custom directories and create them for you on the new system.

For more information about these changes, please refer to JRA-21232.

New Security Option Available in seraph-config.xml

Seraph can now be configured to invalidate your session upon login, which is a more secure configuration than before.

What this means is that the session you establish with JIRA before logging in is effectively destroyed and recreated with a new identity. This means that the session cookie value will be different after logging in. The implications of this are that you can be sure that even if you as a user have been unknowingly tricked into following a poison link to JIRA that forces you to use a session id that an attacker also already has access to, the act of logging in will free you from that session and you will not enable the attacker to gain access to your account.

In addition to the new identity, the new session will maintain, as best it can, the state of your interactions with JIRA. Your current project, current filter, etc, will remain after login. This is nice because sometimes you use JIRA without realising you are not authenticated, and logging in should disrupt your work as little as possible.

By default, seraph is configured to invalidate sessions in JIRA 4.2. This can be turned off in the seraph configuration file, typically called seraph-config.xml.

Here's a sample of the part of the config file that enables session invalidation:

<init-param>
    <param-name>invalidate.session.on.login</param-name>
    <param-value>true</param-value>
</init-param>
<init-param>
    <param-name>invalidate.session.exclude.list</param-name>
    <param-value>ASSESSIONID,dashboardPage</param-value>
</init-param>

In the example above you can see that in addition to the invalidate.session.on.login parameter which activates the feature, there is a second (optional) parameter which can hold a list of session keys which are to be excluded from the new session after login. By default, all session attributes are copied to the new session. If there are any to be excluded from this, they should be defined in a comma separated list for the invalidate.session.exclude.list parameter.

'Contact Administrators' Link has been Removed

Please note that the 'Contact Administrators' link has been removed from the JIRA footer. If you have users who rely on this link, please publish a list of administrators elsewhere before upgrading to JIRA 4.2.

GreenHopper Versions 5.2 and Older are Not Compatible

If you use the GreenHopper plugin, please note that only version 5.3 is compatible with JIRA 4.2.

Crowd Versions 2.0.6 and Older are Not Supported

If you have integrated your JIRA instance with Atlassian Crowd, please upgrade to Crowd 2.0.7. Crowd versions up to and including 2.0.6 will not work with JIRA 4.2. See the Crowd 2.0.7 release notes.

Users of Fisheye/Crucible

Please note that there is a compatibility issue with the crowd-integration-client-2.0.7.jar and Fisheye/Crucible that is described in this JIRA issue.

Various Platforms are No Longer Supported

As mentioned in our End of Support Announcements for JIRA page, from JIRA 4.2, we will no longer provide support for the following platforms with JIRA:

• Oracle WebLogic and IBM WebSphere applications servers, as mentioned in Deprecated Application Servers for JIRA announcement,
• Java Platform 5, as mentioned in the Deprecated Java Platforms for JIRA announcement and
• Internet Explorer 6 web browser, as mentioned in Deprecated Web Browsers for JIRA announcement.

Internet Exporer 7 and 8 users must have "native XMLHTTP support" enabled

There is a known bug that will make transitioning issues impossible from Internet Explorer 7 and 8 when "native XMLHTTP support" is disabled. See http://jira.atlassian.com/browse/JRA-22609 or the JIRA Knowledge Base for details.

Other Known Issues

Before you begin the upgrade, please check for known issues. Sometimes we find out about a problem with the latest version of JIRA after we have released the software. In such cases we publish information about the known issues in the JIRA Knowledge Base. Please check for known issues and follow the instructions to apply any necessary patches.

If you encounter a problem during the upgrade and cannot solve it, please create a support ticket and one of our support engineers will help you.

Upgrading from JIRA 4.0 and Earlier

In addition to the points listed above, please read the Upgrade Guide for every version you are skipping during the upgrade, particularly the JIRA 4.0 Upgrade Guide as JIRA 4.0 introduced significant licensing and technical changes. The complete list of Upgrade Guides is available here: Production Releases.