JIRA 3.6 Upgrade Guide

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

Applies to

users with custom workflow XMLs saved on disk - external to JIRA

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

Applies to

users who have modified JIRA source code or added custom code to define new notification events. Also of interest to users wishing to define new notification templates

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/

All custom event types added to the file system-event-types.xml should be added with an ID of 10000 and above

Custom Listeners

Applies to

users who have added custom listeners to JIRA.

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:

Event Name

Old ID

New ID

created

0

1

updated

1

2

assigned

2

3

resolved

3

4

closed

4

5

commented

5

6

reopened

6

7

deleted

7

8

moved

8

9

worklogged

9

10

workstarted

10

11

workstopped

11

12

genericevent

-1

13

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

Applies to

users who have modified JIRA source to add new permission types (ie. in addition to the standard 'user', 'group', 'assignee' 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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport