JIRA 4.4 Upgrade Notes

On this page:

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.

Changes to the jira-application.properties file

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.0 and later, 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:

<?xml version="1.0" encoding="UTF-8"?>

<jira-database-config>
  <name>defaultDS</name>
  <delegator-name>default</delegator-name>
  <database-type>postgres72</database-type>
  <schema-name>public</schema-name>
  <jdbc-datasource>
    <url>jdbc:postgresql://dbserver:5432/jiradb</url>
    <driver-class>org.postgresql.Driver</driver-class>
    <username>jiradbuser</username>
    <password>password</password>
    <pool-size>15</pool-size>
  </jdbc-datasource>
</jira-database-config>

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'.

Tip: A 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 <jira-application-dir>/WEB-INF/classes/entityengine.xml and 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 server.xml).

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

Use the upgrade feature of the Linux and Windows Installers to upgrade JIRA.

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:

1. Backs up the Installation and Home Directories of the existing JIRA installation to be upgraded.
2. Installs JIRA 4.4  whilst migrating the following from your existing JIRA installation to the new JIRA 4.4 installation:
   
   • 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 server.xml file.
   • Custom values in your existing JIRA installation's jira-application.properties and setenv.sh / setenv.bat files.
     Be aware that in the setenv.sh / setenv.batfile, only the following values are migrated:
     
     • JVM_SUPPORT_RECOMMENDED_ARGS
     • JVM_MINIMUM_MEMORY
     • JVM_MAXIMUM_MEMORY
     • JIRA_MAX_PERM_SIZE

The upgrade feature detects and notifies you of any files (other than jira-application.properties and setenv.sh / 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.

Please Note:

• 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.xml file 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

Use either the manual (i.e. 'in-place' database upgrade) or migration (i.e. XML export/import) procedures to upgrade your existing JIRA 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/classes subdirectory of your JIRA Installation Directory.)
• Standalone distributions only — server.xml (located in the conf subdirectory 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:

• The <datasource name="defaultDS"/> element of the <jira-application-dir>/WEB-INF/classes/entityengine.xml file
• The <Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"/> element of the conf/server.xml file.

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 entityengine.xml and server.xml (or 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 entityengine.xml and server.xml/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 server.xml/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

The JIRA Configuration Tool (included with JIRA 4.4 Standalone) can only work with and modify JIRA 4.4 database configurations (above).

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 JIRA's default workflow, add the new Linked Issues field to the Resolve Issue Screen. (See Defining a Screen for more information.)

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:

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.

Other Plugins

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.

Translations

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.

Known Issues

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:

ALTER DATABASE jiradb SET READ_COMMITTED_SNAPSHOT ON

(where jiradb is the name of your JIRA SQL Server database).

To confirm that this SQL query ran successfully, run the following SQL query:

SELECT is_read_committed_snapshot_on FROM sys.databases WHERE name= 'jiradb'

If you receive a value of '1', then the former statement ran successfully and your JIRA database's 'READ_COMMITTED_SNAPSHOT' setting is 'ON'.

Please Note:

• 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.

Upgrading from JIRA 4.2.x and Earlier

In addition to the points listed above, please read the Important Version-Specific Upgrade Notes for the versions of JIRA you are skipping.