Existing SMTP Mail Server 'From' address may break notifications (JRA-5089)

In JIRA 3, email notification 'From' addresses now contain the reporter name, eg. "Joe Bloggs (JIRA) <jira@company.com>", where "jira@company.com" is set by the admin as the SMTP mail server From address. If you have this address to already include a name (eg "Tech Support <jira@company.com>", then email notifications will fail with errors like:

2005-01-06 11:30:53,856 ERROR [atlassian.mail.queue.MailQueueImpl] com.atlassian.mail.MailException: Sending failed;
  nested exception is: javax.mail.internet.AddressException: 
Missing '<' in string ``"Joe Bloggs (JIRA)" <Tech Support <jira@company.com>>'' at position 62

Fix

The fix is to edit WEB-INF/classes/jira-application.properties, and change the following property value
to false:

• If using JIRA Standalone, the file is atlassian-jira/WEB-INF/classes/jira-application.properties, after which you should run bin/shutdown and bin/startup to restart.
• If using JIRA deployed as a webapp, copy webapp/WEB-INF/classes/jira-application.properties to edit-webapp/WEB-IFN/classes, make the change to the edit-webapp copy, run build to rebuild the webapp, and redeploy it on your app server.

Invalid characters break XML import

JIRA's recommended upgrade process involves deploying an XML backup of your data. Some users will find that the import fails with this error:

This is usually because the database contains control characters that cannot be
represented in Unicode, and hence XML.

Fix

The fix is to follow these instructions to remove the invalid characters from the XML before import.

MySQL Users dB upgrade (JRA-5635)

The size of the descriptor field in the jiraworkflow table has been increased. MySQL users will see warnings when they start their app server. This can be fixed by running the SQL below. This will also allow for Workflows of up to 4GB as opposed to just 64k

alter table jiraworkflows change DESCRIPTOR DESCRIPTOR LONGTEXT;

1. If you have written any Custom Field Type plugins please refer to this document
2. If you have created any Workflow plugins (custom Validators or Post Functions) please read this document.
3. If you have any custom file based workflows (workflows not created through JIRA's Workflow Editor) please read this document.
4. If you wish issues that are associated with the default system workflow and are closed to be bulk editable - please read this.

Notifications now respect permissions

JIRA 3.3 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.3 from JIRA 3.2.x. If upgrading from an older version of JIRA, please go to the complete list of Upgrade Guides, and read the notes for each version you are skipping during the upgrade.

When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

Known incompatibilities

3.3.x is not a good release for IBM shops:

1. JIRA 3.3.x may not work on Websphere 5.0.x and 5.1.x due to JRA-7699
2. When using DB2, JIRA may hang when deleting projects or performing workflow operations. See the full problem description (and possible workaround) in the documentation

Websphere or DB2 users, please stick with 3.2.x or move on to 3.4.x or higher, where these problems have been resolved.

Notes on upgrading

1. Due to web browser caches, changes to JIRA's Issue Navigator might appear corrupted or unstyled. Please refresh your browser's cache (press Shift+Reload on the Find Issue's page) for the changes to appear correctly.
2. JIRA's issue cache size will be automatically set to 0 during the upgrade, as it is no longer needed due to performance improvements in JIRA (JRA-7166)
3. If you have written any CustomFieldType or CustomFieldSearcher plugins please refer to this document
4. Users with outgoing trackback pings enabled (not the default) may wish to disable this until JRA-7589 is fixed, to avoid the risk of the mail queue hanging.
5. If you have bookmarks or deal with hard coded links to the issue navigator, you should read about the changed issue navigator parameters
6. If you are using JIRA Standalone, please do not simply copy your old conf/server.xml file to the new installation of JIRA. Please read this document.
7. If upgrading JIRA in an external Tomcat installation, be sure to delete the work/ temporary directory before restarting JIRA, to clear cached JSPs from the old JIRA.

JIRA 3.3.1 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.3.1 from JIRA 3.3.

When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below:

1. If you have implemented a cutom Issue Tab Panel plugin you need to be aware of this API change.

JIRA 3.4 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.4 from JIRA 3.3.3. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.

When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

1. Please do not copy jira-application.properties file from your old JIRA installation. Edit the file that is shipped with JIRA 3.4 and make needed changes. New properties have been added to this file so if you simply copy the old file across the following error would occur JRA-8645.
2. If you have written any CustomFieldType or CustomFieldSearcher plugins please refer to Upgrading Custom Field Types in JIRA 3.4
3. The default user preferences are now configured in the jira-application.properties file and are configurable through the admin section of JIRA. Any properties in the old file preferences-default.xml will no longer effect JIRA configuration.
4. Please note that to configure issue types per project you must have JavaScript turned on in your web browser.
5. If you are using MySQL please do not use Connector/J 3.1.11 JDBC Driver as it has the following bug. Connector/J 3.1.10 and earlier work fine.

JIRA 3.4.1 Upgrade Guide

This section contains specific information you need to know when upgrading to JIRA 3.4.1 from JIRA 3.4. If upgrading from JIRA 3.3.3 please read the previous section as well. If upgrading from an older version than JIRA 3.3.3, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.

When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

1. Please do not copy jira-application.properties file from your old JIRA installation. Edit the file that is shipped with JIRA 3.4 and make needed changes. New properties have been added to this file so if you simply copy the old file across the following error would occur JRA-8645.
2. If you have written a CustomFieldType that implements the com.atlassian.jira.issue.customfields.CustomFieldType interface directly rather than extending one of the Abstract classes that ship with JIRA please read Upgrading Custom Field Types in JIRA 3.4.1.
3. If you have written an Custom Field Searcher please have a look at Upgrading Custom Field Types in JIRA 3.4.1.
4. JIRA 3.4 and 3.4.1 do not generate an Issue Assigned event. The Issue Updated event is generated instead. In previous versions of JIRA the Issue Assigned event was generated when issues are assigned using the "Assign" operation on the View Issue page. This means that even when the "Assign" operation is used JIRA will send notifications to parties listed under the Issue Updated event. The patch to correct this behaviour is available at JRA-8533.

JIRA 3.4.2 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.4.2 from JIRA 3.4.1. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.4.1 to JIRA 3.4.2.

JIRA 3.4.3 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.4.3 from JIRA 3.4.2. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.4.2 to JIRA 3.4.3.

JIRA 3.5 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.5 ^{(release notes)} from JIRA 3.4.3. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

JIRA 3.5 Jira Service extension

In JIRA 3.5 the getName() and setName(String name) methods was added to the com.atlassian.jira.service.JiraService interface. This method should return and set the name of the service respectively. The name of the service can be used to identify a service uniquely. (Fixed made due to JRA-8352 bug)

Therefore, if you have implemented this interface, you will need to implement these methods and recompile your service(s) before deploying it into JIRA 3.5. If you have extended a JIRA class instead, e.g. com.atlassian.jira.service.AbstractService or com.atlassian.jira.service.JiraServiceContainer you do not need to modify your custom services.

Introduction of global Bulk Change permission

JIRA 3.5 introduces the global Bulk Change permission. This permission governs the ability to execute the bulk change operations:

• Workflow Transition
• Edit
• Move
• Delete

An upgrade task has been added to grant the new Bulk Change permission to all groups with the global JIRA Users permission.

The JIRA documentation includes further details on this new permission.

CustomFieldPersister changes

CustomFieldPersister is used to store custom field values to database. The methods of this class has been refactored to remove the redundant parameter, defaultValueMarker. For example, the create values method went from:

void createValues(CustomField field, Long issueId, String defaultValueMarker, PersistenceFieldType persistenceFieldType, Collection values, String parentKey);

to:

void createValues(CustomField field, Long issueId, PersistenceFieldType persistenceFieldType, Collection values, String parentKey);

You will need to update and recompile any CustomFieldType that you wrote to use this new interface.

VersionCFType Changes

This affects plugin writers who uses the version custom field VersionCFType. The change is that previously the Transport Object type was a single Version object, but it is now a collection that contains a single Version object.

This was done to handle an improved version custom field which can be a mutli-select version custom field as well

JIRA 3.5.1 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.5.1 from JIRA 3.5. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.5 to JIRA 3.5.1.

JIRA 3.5.2 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.5.2 from JIRA 3.5.1. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

Issue Event Changelog Can Now Be Null

In JIRA 3.5.2, the IssueEvent object thrown as a result of an edit operation, may now return null from a getChangeLog() call. The case where this happens is when a user chooses to edit an issue but only leaves a comment and makes no other changes to the issue. Prior to 3.5.2 no event was fired in this case and this was identified as a bug (JRA-9415) and has since been fixed. Check any calls to getChangeLog() for null.

JIRA 3.5.3 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.5.3 from JIRA 3.5.2. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.5.3 from JIRA 3.5.2.

JIRA 3.6 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.6.x from JIRA 3.5.x. If upgrading from an older version of JIRA, please go to the complete list of Upgrade Guides, and read the notes for each version you are skipping during the upgrade.

When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

Database Intensive Upgrade Task

To introduce the Custom events to JIRA, it was necessary to upgrade a large data set within JIRA's database for 3.5.x and earlier releases. Depending on the size of your JIRA data the upgrade task (number 150) might get your DBMS to do a lot of work which might take some time. The exact amount of time also depends on the processing power of the machine running JIRA's database.

Please be patient with the upgrade task and do not restart JIRA while the upgrade is in progress. The upgrade task will report on its progress to JIRA's log file as it upgrades your data.

The following is the sample output that the upgrade task will produce. As you can see the upgrade task took roughly 5 and a half minutes to modify over 660,000 records in the database.

11:14:09 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Phone Support Workflow v.6'.
11:14:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Support Workflow v.3'.
11:14:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Phone Support Workflow v.7'.
11:14:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Test'.
11:14:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Copy of Support Workflow'.
11:14:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Support Workflow v.4'.
11:14:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Inspecting workflow 'Support Workflow'.
11:14:18 INFO [jira.upgrade.tasks.UpgradeTask_Build150] ************************************************************
11:14:18 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating 660453 records in the 'NotificationInstance' table.
11:14:18 INFO [jira.upgrade.tasks.UpgradeTask_Build150] This might take a long time. Please do NOT stop JIRA.
11:14:18 INFO [jira.upgrade.tasks.UpgradeTask_Build150] ************************************************************
11:14:18 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_CREATED'.
11:15:12 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_UPDATED'.
11:15:51 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_ASSIGNED'.
11:16:10 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_RESOLVED'.
11:16:46 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_CLOSED'.
11:16:57 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_COMMENTED'.
11:18:57 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_REOPENED'.
11:19:17 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_DELETED'.
11:19:26 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_MOVED'.
11:19:31 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_WORKLOGGED'.
11:19:37 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_WORKSTARTED'.
11:19:41 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_WORKSTOPPED'.
11:19:43 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Updating records of type 'NOTIFICATION_ISSUE_GENERICEVENT'.
11:21:23 INFO [jira.upgrade.tasks.UpgradeTask_Build150] Update of 'NotificationInstance' records finished.

Workflow Post Functions

JIRA stores its workflows in the database. During the upgrade, these workflows will be upgraded automatically. However, if you have stored your workflows on disk (outside the database), you will need to follow these instructions to upgrade the workflows manually. 

Previously, workflow post functions referenced the event to fire through a string value of the event name. All post functions now reference the event through a numeric ID value. As mentioned, all workflows stored within JIRA will be automatically updated. However, all workflows saved to disk - external to JIRA - should be updated manually as follows. The actual workflow XML file should be updated as follows:

For each workflow post function that accepts the event ID as an argument: 

1. The value of the name attribute of the arg tag has to be changed from eventType to eventTypeId
2. The body of the arg tag has to change according to the following table:

   Event Name	Event Type Id
   created	1
   updated	2
   assigned	3
   resolved	4
   closed	5
   commented	6
   reopened	7
   deleted	8
   moved	9
   worklogged	10
   workstarted	11
   workstopped	12
   genericevent	13

By default, the only post functions that accept event IDs are FireIssueEventFunctions. Therefore, unless you have implemented your own custom post function that also deals with events, you will only need to update the arg tags for the FireIssueEventFunctions everywhere in the workflows.

For example, FireIssueEventFunction for create issue workflow transition looked like:

<function type="class">
    <arg name="class.name">com.atlassian.jira.workflow.function.event.FireIssueEventFunction</arg>
     <arg name="eventType">created</arg>
</function>

and needs to be changed to:

<function type="class">
    <arg name="class.name">com.atlassian.jira.workflow.function.event.FireIssueEventFunction</arg>
     <arg name="eventTypeId">1</arg>
</function>

Custom Events

Releases before JIRA 3.6 did not allow users create custom events. If you have modified the JIRA source to add custom events - please follow these instructions.

If you have previously defined a custom event within JIRA - it is necessary to add appropriate entries to the following files:

• system-event-types.xml- used to install and upgrade all event types within the system to the new 3.6 event type object.
• email-template-id-mappings.xml - maps the event id to an assocaited velocity template file.

The system-event-types.xml file requires name and description details of the previously added custom event. For example, if the custom event type "Issue Frozen" was added to the system - the following entry should be added to the XML file:

<eventtype id="10000">
   <name>Issue Frozen</name>
   <description>This is the 'Issue Frozen' event type.</description>
   <notificationName>ISSUE_FROZEN</notificationName>
   <eventName>issuefrozen</eventName>
</eventtype>

The elements provide the following information:

• id - the new id for the event type. All custom event types should be added from ID 10000 and above
• notificationName - the original name for the event as found in the Notification table
• eventName - the origianl name for the event as found in workflows

The email-template-id-mappings.xml file requires an entry mapping the new custom event to an associated velocity email template. This mapping is used when a notification is sent for this event. Following from the above example, the following entry would be made:

<templatemapping id="10000">
   <name>Issue Frozen</name>
   <template>issuefrozen.vm</template>
</templatemapping>

The id should match that of the event as specified in the system-event-types.xml The template entity should reference the Velocity template to be used in email notifications of this event. A HTML and text version should be provided in the appropriate directory (html or text) at:

<JIRA>/src/etc/java/templates/email/

Custom Listeners

For all users who have added custom written listeners to JIRA, it might be necessary to update the listener to follow the new JIRA 3.6 API.

 There are two things to look out for:

1. signature change of the workflowEvent method
2. change of return type of getIssue() method on the IssueEvent object

The signature of the method workflowEvent  in the IssueEventListener has changed from:

public void workflowEvent(int type, IssueEvent event);

to: 

public void workflowEvent(IssueEvent event);

Note: the type parameter has been removed.

If you have implemented IssueEventListener directly or have extended AbstractIssueEventListener and have overridden the method workflowEvent, you will need to change and recompile your listener before installing JIRA 3.6.

In JIRA 3.6, the event type ID can be retrieved by calling the following method on the IssueEvent object:

Long eventID = event.getId();

However, the returned value of the getId() method is different to the values of the type parameter that was passed to the workflowEvent method. The following table represents these differences:

Also, the getIssue() method of the IssueEvent object has changed to return an Issue object instead of a GenericValue object representing an issue.

Users who have created and added custom listeners must update the listener to now operate with the Issue object. For example:

Issue issueObject = event.getIssue();

As a quick fix, you can modify your listener to use event.getIssue().getGenericValue().

The event type ID constants are now only available from the class EventType. Any use of the original constants must be updated to use the EventType constants. For listeners that reference an event ID by its numeric value - it is necessary to ensure that the IDs now match those as defined in EventType.

Custom permission types

The SecurityType interface, used to implement permission types ('single user', 'group' etc) has had a getUsers() method added. If you have implemented your own SecurityType you will need to implement this. See the source of current implementations (eg. GroupCF) for tips.

Plugin upgrades required

As usual, you should check whether the plugins you use are compatible with the new release. Generally, plugins (like the Subversion plugin or JIRA toolkit ) need to be upgraded when JIRA is upgraded. See the list of plugins at:

http://confluence.atlassian.com/display/JIRAEXT/Home

JIRA 3.6.1 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.6.1 from JIRA 3.6. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.6.1 from JIRA 3.6.

JIRA 3.6.2 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.6.2 from JIRA 3.6.1. If upgrading from an older version of JIRA, please go to the complete list of Upgrade Guides, and read the notes for each version you are skipping during the upgrade.

When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

Maximum Active Databased Connections

In version of JIRA before 3.6.2, the maximum number of database connections was limited to 8 by default. If JIRA was used by more than 8 concurrent users or under very haeavy usages, the users could experience delays or JIRA could hang.

In JIRA 3.6.2 the default number of maximum active database connections has been increased to 20. When upgrading to JIRA 3.6.2, please ensure that your database will allow JIRA to establish 20 connections, or decrease this number to desired value. To adjust the number of connections change the value of the maxActive attribute of the jdbc/JiraDS resource in config/server.xml file. JIRA has to be restarted to apply the change.

JIRA 3.6.3 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.6.3 from JIRA 3.6.2. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.6.3 from JIRA 3.6.2.

JIRA 3.6.4 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.6.4 from JIRA 3.6.3. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading to JIRA 3.6.4 from JIRA 3.6.3.

JIRA 3.6.5 Upgrade Guide

This page contains specific information you need to know when upgrading to JIRA 3.6.5 from JIRA 3.6.4. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading to JIRA 3.6.5 from JIRA 3.6.4.

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

JIRA 3.7.1 Upgrade Guide

This page contains specific information you need to know when upgrading from JIRA 3.7 to JIRA 3.7.1. If upgrading from an older version of JIRA, please read the Upgrade Guide for each version your are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• There are no specific instructions you need to be aware of related to upgrading from JIRA 3.7 to JIRA 3.7.1.

JIRA 3.7.2 Upgrade Guide

This page contains specific information you need to know when upgrading from JIRA 3.7.1 to JIRA 3.7.2. If upgrading from an older version of JIRA, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.
When upgrading JIRA please follow the general upgrade instructions keeping in mind the information below.

• 3.7.2 will automatically perform a full reindex when upgrading. For more details please see JRA-11861

Upgrading from JIRA 3.7.2 to 3.7.3

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.7.1 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.7.3 to 3.7.4

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.7.2 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.7.4 to 3.8

Please follow the JIRA general upgrade instructions. Additionally, please note the following:

1. The 'Assign To' field name has been changed to 'Assignee' consistently across JIRA. This means that users need to be aware that the column heading in the Excel export has changed to 'Assignee' from 'Assign To'. Please be aware of this if for example you are exporting JIRA data to Excel and running macros on it. The field has been renamed for the following Issue Navigator Views:
   • Excel (all)
   • Word (all)
   • Full Content
2. The issuecommentedited.vm e-mail template for the new Issue Comment Edited event has been added to the WEB-INF/classes/email-template-id-mappings.xml file. The id of the e-mail template used for sending Filter Subscriptions has changed to 10000. If you have manually modified the WEB-INF/classes/email-template-id-mappings.xml file in the version of JIRA you are upgrading from, please do not simply copy the old file to JIRA 3.8. You will need to port your changes to the WEB-INF/classes/email-template-id-mappings.xml file that is shipped with JIRA 3.8. If you have not changed the WEB-INF/classes/email-template-id-mappings.xml file, you do not need to worry about this.
3. Two columns have been added to the jiraaction table to support editable comments.

Upgrading from JIRA 3.7.3 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.8 to 3.8.1

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.7.4 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.8.1 to 3.9

Please follow the JIRA general upgrade instructions. Additionally, please note the following:

In this version, there has been a change to the database which may cause problems for some customers.

The Recommended Upgrade Method

If you follow the recommended export/import upgrade procedure you should not experience any problems!

Pointing JIRA 3.9 at an existing, non-empty database

Some customers have a good reason for not following the recommended upgrade method. Using this method may result in database errors in your logs. You can avoid this if you modify your table structure manually, but the procedure is different depending on whether you have already started JIRA.

To avoid this, BEFORE you upgrade JIRA using this method, you can just drop the qrtz_cron_triggers table. This table has not been used by JIRA before 3.9, so it should be empty.

If you have ALREADY started JIRA 3.9 using your existing database, you may see the following log messages when JIRA starts up:

2007-04-18 15:31:53,345 main WARN [core.entity.jdbc.DatabaseUtil] Column  "CRON_EXPERSSION" of table "public.qrtz_cron_triggers" of entity  "QRTZCronTriggers" exists in the database but has no corresponding field
2007-04-18 15:31:53,347 main WARN [core.entity.jdbc.DatabaseUtil] Entity  "QRTZCronTriggers" has 3 fields but table "public.qrtz_cron_triggers"  has 4 columns.

The reason for this is that we have incorrectly changed a column in the qrtz_cron_triggers table. The intention was to fix a misspelling, but all we did was remove an underscore ("_")! The old column name is "CRON_EXPERSSION". The new column name is "CRONEXPERSSION". Note that both columns spell the word "expression" incorrectly.

To remove the error message, you must remove the old column as it is redundant. This column will not contain any data. The following table shows all columns in the qrtz_cron_triggers table. Columns that should be present are in green and columns that should be deleted are in red.

To delete the column, you can use SQL, but this may be slightly different between databases. Here's how it might look:

alter table qrtz_cron_triggers drop column CRON_EXPERSSION;

The data in this table

If you have users who have subscribed to issue filters, note that existing SimpleTriggers (time intervals) will be automatically converted into CronTriggers during the JIRA upgrade. In some cases, there may not be an exact mapping of time intervals to Cron Expressions, and approximations will be made (e.g. 'Every 5 weeks' will be converted to 'Once a month'). If this happens, the JIRA upgrade process will send an email to the user to inform them of the new schedule.

Upgrading from JIRA 3.8 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.9 to 3.9.1

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.8.1 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.9/3.9.1 to 3.9.2

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.8.1 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.9.2 to 3.9.3

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.9.1 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.9.3 to 3.10

Please follow the JIRA general upgrade instructions, plus note the following:

1. Plugins

There is a new version of the JIRA Calendar Plugin that links to the new 'Project Version' pages. This new version of the plugin is not backwards compatible.

Please note that the Kaamelot plugin for JIRA has not yet been updated. If you are currently using this plugin, you may want to hold off the upgrade to JIRA 3.10 until a compatible version of this plugin has been released.

2. Developer Notes

The ordering of the ListOrderedMap returned by SchemePermissions.getSchemePermissions() has changed. This also means that the order of the RemotePermission[] array returned by the RPC Plugin's JiraSoapService.getAllPermissions() method has changed. If you have extended your instance of JIRA please confirm that any remote applications retrieving permissions via SOAP still work. You may encounter problems if you have been retrieving specific permissions by their array index.

Database changes

In JIRA 3.10, the worklog records have moved from the 'jiraactions' database table to the new 'worklog' table. This new table contains the following columns:

               Table "public.worklog"
    Column    |           Type           | Modifiers
--------------+--------------------------+-----------
 id           | numeric(18,0)            | not null
 issueid      | numeric(18,0)            |
 author       | character varying(255)   |
 grouplevel   | character varying(255)   |
 rolelevel    | numeric(18,0)            |
 worklogbody  | text                     |
 created      | timestamp with time zone |
 updateauthor | character varying(255)   |
 updated      | timestamp with time zone |
 startdate    | timestamp with time zone |
 timeworked   | numeric(18,0)            |

Upgrading from JIRA 3.9.2 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.10 to 3.10.1

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.9.3 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.10.1 to 3.10.2

Please follow the JIRA general upgrade instructions.

Upgrading from JIRA 3.9.3 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.10.x to 3.11

Please follow the JIRA general upgrade instructions, plus note the following:

Administrative notes

• To take advantage of the performance enhancements in JIRA 3.11, it is recommended that you enable GZip compression (unless you are using mod_proxy).
• The jira-application.properties file has a new option, 'progress', for the following attribute:

   jira.table.cols.subtasks
  

  The 'progress' option controls the display of the 'Progress' field in issues and reports.
• JIRA 3.11 introduces a bug fix for JRA-12354. This means that the CVS and Perforce plugin will perform better at detecting commits for a particular issue key, avoiding partial matches on similar project keys. If users have taken advantage of the previous relaxed key matching, they can revert to the old behaviour by simply setting the following application property in the jira-application.properties file and restarting JIRA:

  jira.option.key.detection.backwards.compatible=true
  

Plugins

Updating plugins
If you are using any of the following plugins, you will need to update them to their latest versions when performing the upgrade:

• Perforce plugin
• Subversion plugin
• Toolkit Plugin
• Charting Plugin
• RPC Plugin

3rd Party and personal plugins may also be affected (esp. if using lucene to store dates). These will need to be updated as well.

If these are updated after the upgrade (instead of as part of the upgrade), you will need to do a reindex.

A failure to update these plugins will result in lots of errors that look like:

Error 1

2007-07-25 15:23:27,553 http-8090-Processor4 ERROR [charting.charts.createdvsresolved.CreatedVsResolvedChart] Could not create velocity parameters For input string: "20070725144811"
java.lang.NumberFormatException: For input string: "20070725144811"
	at java.lang.NumberFormatException.forInputString(NumberFormatException.java:48)
	at java.lang.Long.parseLong(Long.java:415)
	at org.apache.lucene.document.DateField.stringToTime(DateField.java:100)
	at org.apache.lucene.document.DateField.stringToDate(DateField.java:104)
	at com.atlassian.jira.ext.charting.data.DatePeriodStatisticsMapper.getValueFromLuceneField(DatePeriodStatisticsMapper.java:47)
	at com.atlassian.jira.ext.charting.data.OneDimensionalObjectHitCollector.adjustMapForValues(OneDimensionalObjectHitCollector.java:57)
	at com.atlassian.jira.ext.charting.data.OneDimensionalObjectHitCollector.collect(OneDimensionalObjectHitCollector.java:46)
	at org.apache.lucene.search.IndexSearcher$1.collect(IndexSearcher.java:137)
	at org.apache.lucene.search.Scorer.score(Scorer.java:49)
	at org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:146)
	at org.apache.lucene.search.Searcher.search(Searcher.java:118)
	at com.atlassian.jira.issue.search.providers.LuceneSearchProvider.search(LuceneSearchProvider.java:111)
...

Error 2

Caused by: java.lang.NoSuchMethodError: org.apache.lucene.document.Document.add(Lorg/apache/lucene/document/Field;)V
	at com.atlassian.jira.plugin.labels.LabelSearcher.index(LabelSearcher.java:95)
	at com.atlassian.jira.issue.index.indexers.impl.DefaultCustomFieldIndexer.addIndex(DefaultCustomFieldIndexer.java:54)
	at com.atlassian.jira.issue.index.IssueDocument.getDocument(IssueDocument.java:34)
	at com.atlassian.jira.issue.index.IssueDocumentBuilderImpl.get(IssueDocumentBuilderImpl.java:14)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer$IssueAndCommentCreator.handleIssueIndexing(SingleThreadedIssueIndexer.java:404)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer$AbstractIssueAndCommentHandler.indexIssuesAndComments(SingleThreadedIssueIndexer.java:318)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer.indexIssuesAndComments(SingleThreadedIssueIndexer.java:122)
	at com.atlassian.jira.issue.index.MultiThreadedIssueIndexer.indexIssuesAndComments(MultiThreadedIssueIndexer.java:41)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer$2.perform(SingleThreadedIssueIndexer.java:113)
	at com.atlassian.bonnie.ConcurrentLuceneConnection.withWriter(ConcurrentLuceneConnection.java:296)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer$1.perform(SingleThreadedIssueIndexer.java:107)
	at com.atlassian.bonnie.ConcurrentLuceneConnection.withWriter(ConcurrentLuceneConnection.java:296)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer.indexIssues(SingleThreadedIssueIndexer.java:102)
	at com.atlassian.jira.issue.index.SingleThreadedIssueIndexer$6.perform(SingleThreadedIssueIndexer.java:219)
...

If you see these errors, please ensure that you are using the latest compatible version of the plugin for 3.11. If there is no supported version for 3.11, please contact the plugin developer via the plugin's homepage.

Developer notes

Modification to SOAP clients
If you have written a SOAP client for any JIRA version prior to 3.11 and are invoking any methods to get RemoteIssueType you will encounter the bug JRA-13529. The reason for this is that we have added extra information to the RemoteIssueType object that indicates if the issue type is a subTask issue type. To avoid the problem you will need to regenerate your remote object stubs against the updated JIRA 3.11 wsdl.

If you would like your SOAP client to work against multiple versions of JIRA then you need to use the latest stubs that have been generated against JIRA 3.11. You will need to not use any of the new functionality and you will need to remember that the isSubTask variable in the RemoteIssueType objects will be defaulted to false.

ThreadLocalQueryProfiler searchers have been moved to ThreadLocalSearcherCache
There may be a number of plugins that reference the ThreadLocalQueryProfiler searcher methods directly. These need to now reference the ThreadLocalSearcherCache.

Lucene Upgrade
We upgraded our version of Lucene to 2.2. If your plugin uses to Lucene to index/read data, please ensure that it works with JIRA 3.11. If you are indexing/reading dates, more than likely it will have broken and you will need to use the new Lucene 2 methods.

Database changes

There were no database changes in this release.

Upgrading from JIRA 3.9.x and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.11 to 3.12

Please follow the JIRA general upgrade instructions, plus note the following:

1. Everyone who had the 'JIRA Administrators' global permission before the upgrade will automatically receive the new 'JIRA System Administrators' global permission during the upgrade. This will ensure that everyone can still perform the same functions they could previously.
2. The following new Seraph property can be used to fix JRA-10508:

   <!--  If this parameter is set to true, the cookie will never be set secure.  This is useful if you're logging
                 into JIRA via https, but want to browse JIRA over http.  This flag will ensure that the remember me option
                 works correctly. -->
           <init-param>
               <param-name>insecure.cookie</param-name>
               <param-value>true</param-value>
           </init-param>
   

3. Due to the Seraph upgrade, to fix JRA-10508 all users will be prompted to log in again. This will also affect users who have the 'Remember me' checkbox ticked.
4. If you are building JIRA from source, please note that Maven2 is now required for a build. This is because the JIRA Fisheye Plugin requires Maven2.
5. If you are using the JIRA Toolkit, it is recommended that you upgrade to the latest version in order to fix JRA-13553
6. Please note that the new Trusted Applications feature is not supported on Orion versions prior to 2.0.5. Also note that Resin2 has problems and you will need to update the Resin extra jars.
7. There is a new database table. Please see the following page for details

Upgrading from JIRA 3.10.2 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Using the Trusted Applications feature with Crowd

Please note that older versions of the Crowd client, (i.e. version 1.2.1 or earlier), can interfere with the correct operation of the Trusted Applications feature. If you are enabling Trusted Applications and using Crowd, please ensure that your Crowd client is version 1.2.2 or later.

Upgrading from JIRA 3.12 to 3.12.1

Please follow the JIRA general upgrade instructions

Upgrading from JIRA 3.11 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.12.1 to 3.12.2

Please follow the JIRA general upgrade instructions

Upgrading from JIRA 3.11 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.12.2 to 3.12.3

Please follow the JIRA general upgrade instructions

Upgrading from JIRA 3.11 and earlier

In addition to the above, please read the Upgrade Guide for every version you are skipping during the upgrade. The complete list of Upgrade Guides is available here.

Upgrading from JIRA 3.12.xx to 3.13

Upgrading from JIRA 3.12 and earlier