Documentation for JIRA 4.4. Documentation for other versions of JIRA is available too.
On this page:
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).
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.
New properties in |
---|
|
|
|
|
|
|
|
|
|
Properties removed from |
---|
|
|
|
Properties changed in |
---|
|
seraph-config.xml
and Crowd IntegrationWhen 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:
The following table lists the changes to the seraph-config.xml
file in JIRA 4.2:
Elements in |
Change 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"/> |
Changed to <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> |
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.
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.
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.
Only labels custom-fields called "Labels" will be converted to the system field. All other label custom fields will remain as label custom-fields. If a particular label custom-field should be moved into the system field, it should be named "Labels" before the upgrade!
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.)
If you have upgraded to JIRA 4.2 and have disabled Legacy Mode, the Log Work fields will not automatically be available on the 'Resolve' and 'Close' transitions of JIRA's default workflow, nor will they be available on any other (custom) workflow transition.
To add these fields to a workflow transition, add the Log Work field to the appropriate screen used by that workflow transition. Refer to Adding Time Tracking capabilities to a screen on the Defining a Screen page for more information.
(The Log Work field is actually a group of time-tracking fields.)
Tip: If you use JIRA's default workflow, add the Log Work field to the Resolve Issue Screen.
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.
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.
For security reasons, from JIRA 4.2, you are no longer able to customise directories for storing the following types of JIRA content:
JIRA now stores these types of content in 'Default' directories within the JIRA home directory.
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:
For more information about these changes, please refer to JRA-21232.
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.
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.
If you use the GreenHopper plugin, please note that only version 5.3 is compatible with JIRA 4.2.
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.
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.
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:
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.
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.
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.