On this page:
From JIRA 4.4, version-specific 'upgrade guides' are now referred to as 'upgrade notes'. This change was made to avoid potential naming ambiguity with the general Upgrading JIRA guide and to match the naming conventions used for the equivalent documents of other Atlassian products.
Upgrading from JIRA 4.3 to 4.4
Please follow the instructions in the general Upgrading JIRA guide, as well as the JIRA 4.4-specific instructions in the sections below. The general 'Upgrading JIRA' guide contains important tasks that are essential for getting your upgraded JIRA installation to work correctly and if necessary, migrating existing configurations.
If you are upgrading a JIRA WAR installation:
Please ensure you read through all content in the section below for Upgrading a JIRA 4.3.x (or Earlier) WAR Installation, including the subsection on Migrating Your Database Configuration.
Changes to the
In JIRA 4.4.0 and later, advanced configuration options are no longer stored in the
jira-application.properties file. Instead, the default values for nearly all these JIRA properties are stored in the new
jpm.xml file (located in the JIRA Installation Directory) and any properties whose values you have customised are defined in either the new
jira-config.properties (located in the JIRA Home Directory) or the JIRA database (for more commonly edited properties). The values of any properties defined in the
jira-config.properties and JIRA database override those values stored in the
jpm.xml file. For more information, see Advanced JIRA Configuration.
When upgrading and migrating your existing configurations to JIRA 4.4.x (most of which is handled automatically if you use the new 'automated upgrade' tools), any properties whose values you had customised in the
jira-application.properties file of your earlier JIRA installation, will be read and migrated across to the new
jira-config.properties file or JIRA database of your upgraded JIRA installation.
In JIRA 4.4.x, the
jira-application.properties file is still required, although only the
jira.home property is used.
Database Configuration Changes
JIRA 4.4.0 and later uses a new file called
dbconfig.xml (located within your JIRA Home Directory), which defines all JIRA database connection information for your JIRA installation.
Here is an example of a
dbconfig.xml file defining a direct JDBC connection to an external PostgreSQL database:
A direct JDBC connection means that JIRA's entire database configuration information is encapsulated within the
dbconfig.xml file, with no references to a 'datasource'.
dbconfig.xml file defining a direct JDBC connection to a JIRA database, effectively replaces values which defined the JIRA 'datasource' and 'database' connections from the
conf/server.xml (JIRA Standalone only) files, respectively (within the JIRA Installation Directory of version 4.3.x or earlier). For JIRA WAR version 4.3.x or earlier, the JIRA database connection is typically defined in the
jira.xml file within the
conf subdirectory of the Tomcat installation running JIRA (instead of
From JIRA 4.4.0, the
entityengine.xml file is no longer used to store any information about your JIRA database/datasource. However, this file is still required by JIRA for other purposes.
Migrating Existing Configurations to Your New JIRA During the Upgrade
Upgrading a JIRA 4.3.x Standalone Installation on Linux or Windows
If you are upgrading a JIRA 4.3.x installation on Solaris, do not use the Linux Installer to upgrade JIRA. Instead, use either the manual (i.e. 'in-place' database upgrade) or migration (i.e. XML export/import) procedures and refer to the additional notes below.
This upgrade feature automates the following tasks for you:
- Backs up the Installation and Home Directories of the existing JIRA installation to be upgraded.
- Installs JIRA 4.4.x whilst migrating the following from your existing JIRA installation to the new JIRA 4.4.xinstallation:
- Legacy database configurations defined as a datasource within the application server (used in JIRA 4.3.x and earlier) to the new database configuration used in JIRA 4.4 and later. See Database Configuration Changes (above) for details.
- TCP port values in your existing JIRA installation's
- Custom values in your existing JIRA installation's
Be aware that in the
setenv.batfile, only the following values are migrated:
The upgrade feature detects and notifies you of any files (other than
setenv.bat) in the
atlassian-jira subdirectory of your existing JIRA Installation Directory, which had been deleted, added or modified from a 'default' JIRA installation. This informs you of any customisations you will need to migrate manually over to your upgraded JIRA installation directory.
- The upgrade process requests that you conduct a backup of your database using your database's backup utilities. If your database does not support online backups, you can stop the upgrade process, shut down JIRA, perform your database backup and then restart the upgrade process to continue on.
- If you have made customisations to your
seraph-config.xmlfile or any other files in your JIRA installation directory, these must be migrated manually.
- If your attachments and index files are located outside your JIRA Home Directory, then backups of these directories must be performed manually.
Upgrading a JIRA 4.2.x (or Earlier) Standalone or JIRA 4.3.x (or Earlier) WAR Installation
When migrating your existing JIRA configurations over to your new JIRA installation, ensure that any specific configurations to the following files of your existing JIRA installation have been re-applied to the equivalent files in your new JIRA installation before you start your upgraded JIRA installation:
jira-application.properties(located in the
<jira-application-dir>/WEB-INF/classessubdirectory of your JIRA Installation Directory.)
- Standalone distributions only —
server.xml(located in the
confsubdirectory JIRA Installation Directory).
Migrating Your Database Configuration
Both the manual and migration upgrade procedures require you to have properly configured a
dbconfig.xml file in your JIRA Home Directory (which defines a direct JDBC connection as shown in the example above), before you start your upgraded JIRA installation.
If you are creating this
dbconfig.xml file manually and you are not changing your JIRA database, it may help to migrate specific parameter values from within the following areas of your old JIRA Installation Directory:
<datasource name="defaultDS"/>element of the
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/>element of the
For JIRA WAR, the
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/> element is typically located in the
jira.xml file within the
conf subdirectory of the Tomcat installation running your old JIRA server.
The following table shows which element values in the
dbconfig.xml file for JIRA 4.4.x (or later) match the parameter values in the
jira.xml) files of your JIRA 4.3.x (or earlier) installation:
Avoid Migrating Your Database Configuration This Way
If you do not create a
dbconfig.xml file but instead, re-apply database configurations (in the
jira.xml files) from your old JIRA installation to your new JIRA installation, then upon starting your new JIRA installation, JIRA will write a new
<JIRA Home Directory>/dbconfig.xml file defining your existing database configuration. However, this
dbconfig.xml file will actually define a datasource connection to JIRA's database (defined in your
jira.xml file), as opposed to a direct JDBC connection shown in the example above. We strongly recommend avoiding this database migration approach, as it will complicate future upgrades of JIRA.
JIRA Configuration Tool
New 'View (Read-Only) Workflow' permission
Users require a new project permission called 'View (Read-Only) Workflow' to access the workflow viewer feature from the 'View Issue' page. On new installations of JIRA, this permission is granted to users automatically. However, for JIRA 4.4 upgrades, JIRA administrators will need to assign this permission to their users manually.
External Password Management
The 'External Password Management' option in the 'General Configuration' area of JIRA has been removed as this is now handled through User Directories.
Issue Linking when Resolving an Issue
On clean installations of JIRA 4.4, when a user resolves or closes an issue which utilises JIRA's default workflow, the user will be able to link that issue to another before submitting the transition.
If you have upgraded to JIRA 4.4, this feature will not automatically be available and it must be configured manually through the JIRA administration console.
To add this feature to any workflow transition of any other custom workflow, add the Linked Issues field to the appropriate screen used by that workflow transition.
Old Issue Import Functionality Removed
The old issue import functionality has been removed and has been completely replaced by the JIRA importers plugin feature, which is included with JIRA.
XML Backups Always Generate a ZIP Archive File
JIRA's XML backup utility now always generates a ZIP archive file. As a result of this change, the option to 'Backup As Zip' has been removed from the user interface.
'Contact Administrators' Reintroduced
The 'Contact Administrators' link has been reintroduced in JIRA 4.4. It operates a little differently from previously — please see the following two options on the 'General Configuration' page:
Contact Administrators Form
Provides an email form for users to fill in when they click the 'Contact Administrators' link (which appears when necessary throughout the JIRA interface, e.g. on the Login screen). Applies only if outgoing email is enabled. Can be used with or without the custom 'Contact Administrators Message' below. Default: OFF
Contact Administrators Message
Displays a custom message when users click the 'Contact Administrators' link (which appears when necessary throughout the JIRA interface, e.g. on the Login screen). The 'Contact Administrators Message' will be displayed at the top of the 'Contact Administrators Form', if the form is enabled (see above), or by itself if the form is not enabled.
Earlier Versions of JIRA with the Visual Workflow Designer Plugin
Since the Visual Workflow Designer feature is now included with JIRA 4.4, if you used the JIRA Workflow Designer plugin with your earlier JIRA version, please remove it from your JIRA Home Directory before upgrading JIRA.
If you forget to do this before commencing the upgrade, then conduct the following after upgrading JIRA:
- Shut down your upgraded JIRA installation.
- Remove the old version of the Visual Workflow Designer plugin from your JIRA Home Directory.
- Restart your upgraded JIRA installation.
JIRA 4.4 introduces several changes that may break existing plugins which are not bundled with JIRA.
If you have a developed a plugin, then please read the Plugin Developer Notes for JIRA 4.4 guide. This guide describes changes in JIRA 4.4 which may affect the compatibility of your plugin with JIRA 4.4.
If you are using a plugin developed by a third party, please check with the plugin's author to see if the plugin has been tested with JIRA 4.4.
Please note that JIRA 4.4 may not ship with the very latest translations of all languages at this time. However, French, German and other translations can be obtained or updated easily via the Universal Plugin Manager by searching for "language pack". See Managing JIRA's Plugins for details on using this feature.
You can also download and install these language packs manually from our Plugin Exchange site.
Language packs for other languages which are not available through the Universal Plugin Manager or our Plugin Exchange site can be downloaded from our translation site (https://translations.atlassian.com/).
Java Platform Support
Please be aware that Oracle JDK / JRE 1.6 update 18 or later is now required to run JIRA. See Supported Platforms for more information.
An Exception is Generated After Starting a New JIRA Installation
Due to a bug (JRA-24818), an
ArrayIndexOutOfBounds exception is generated after starting a new JIRA 4.4 installation. However, this exception will not cause any issues with JIRA's functionality.
SOAP API Returns IDs Instead of Values for Multiselect Fields
Due to a bug (JRA-25034), people using the SOAP API to get values for multiselect fields will now just see the "ids" (numbers) of each multiselect value, instead of their human-readable display name. Note that these fields can still be set using values (as opposed to ids).
Our proposed solution is here — please watch the issue for progress and resolution.
Automated Upgrade Encounters Problems Reading the JIRA Installation Directory
The automated upgrade feature of the Windows and Linux installers may report the error: "Problems reading the installation directory." This is usually caused by a missing HTTP connector definition in the
conf/server.xml file of the JIRA Installation Directory. For more information on how to resolve this issue, please refer to our JIRA Knowledge Base article Unable to Upgrade to JIRA 4.4 due to Problems Reading the Installation Directory.
JIRA Installations Connected to Microsoft SQL Server Databases
If you are upgrading to JIRA version 4.4 or later, Microsoft SQL Server's default 'READ_COMMITTED_SNAPSHOT' database setting of 'OFF' may prevent the JIRA upgrade from completing successfully.
Hence, you should change this database setting to 'ON' before you restart your upgraded JIRA 4.4 or later installation. To do this, run the following SQL query:
jiradb is the name of your JIRA SQL Server database).
To confirm that this SQL query ran successfully, run the following SQL query:
If you receive a value of '1', then the former statement ran successfully and your JIRA database's 'READ_COMMITTED_SNAPSHOT' setting is 'ON'.
- Once you have upgraded to JIRA version 4.4 or later, you may wish to revert your JIRA database's 'READ_COMMITTED_SNAPSHOT' setting to 'OFF' again.
- For more information about this setting, please refer to the relevant page on Microsoft's MSDN site.
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.