JIRA 4.0 will introduce a new dashboard, effectively making the Portlet Plugin Module obsolete. Legacy portlets will still be supported via a Legacy Gadget bridge; however, they will miss out on a lot of the new features that gadgets offer (e.g. the ability to share gadgets with other apps such as iGoogle). It therefore makes sense to convert portlets over to gadgets. Information about how to write a gadget can be found in the Gadget Development Hub, and specifically the page about gadgets and JIRA portlets.
If you've converted a portlet to a gadget, you will most likely need an upgrade task to convert existing data of your users into the new format used by the gadget you have written. This page describes the process of creating such an upgrade task.
Why an upgrade task?
Portlets generally have some configuration data associated with them by their users. For example, the First Response Time chart portlet, available in the Charting Plugin, allows users to configure how many days previous to draw the chart for (among other things). For efficiency reasons, gadgets do not use the same storage mechanism as portlets do to store these user preferences. An upgrade task is thus needed to convert existing user data over to the new format required by the new gadget.
JIRA 4.0 introduces a new plugin framework (version 2.2 or later of the Atlassian Plugin Framework, affectionately known as 'Plugins2'), which provides an events system that lets plugins register to listen for certain events (such as a 'Framework started' event). JIRA 4.0 also bundles SAL, which already includes a plugin upgrade framework. SAL provides a plugin upgrade manager that listens for the 'Framework started' event and will look for Plugin Upgrade Tasks to run in order to upgrade data for plugins.
What does all this mean? Effectively, plugin writers don't have to worry about providing an upgrade task framework. They can simply provide a Plugin Upgrade Task component and SAL will guarantee that their upgrade task is run on startup.
Let's look at what needs to be done to run an upgrade task to convert the First Response Time chart portlet data over to gadget data.
1. Convert your Portlet to a Gadget
2. Add dependency on SAL
First we'll need access to the SAL API in the charting plugin project. Add the following dependency to the plugin's
Re-generate your IDE's project descriptor (
mvn idea:idea or
mvn eclipse:eclipse) after this step to allow you to access the new SAL API classes in your project.
3. Convert your plugin to Plugins2
SAL is a Plugins2 bundle and your plugin will have to be converted to the Plugins2 format first before you can write an upgrade task that will be picked up by the PluginUpgradeManager. Gadgets are also only supported in Plugins2 bundles.
There are generic instructions available for how to do this, but let's look specifically at the Charting plugin example. The only thing that is needed is to add the
plugins-version="2" attribute in
4. Writing your upgrade task
Now that all the prerequisites are done, the Upgrade task for the plugin can be written. This class simply needs to implement the PluginUpgradeTask interface provided by SAL.
Here's an example implementation:
There are a few things to note about this implementation:
getPluginKey()determine if this upgrade task will run.
getPluginKey()needs to match the key of the plugin that is being upgraded (in this case the charting plugin).
getBuildNumber()returns the buildnumber for this upgrade task.
'1'will do for any plugin that hasn't had any upgrade tasks run against it yet. SAL's PluginUpgradeManager will run this upgrade task and store the buildnumber against the plugin once completed. After this, only upgrade tasks with a higher build number than '1' will be executed.
doUpgrade()uses some helpers provided by JIRA (i.e. the SimpleLegacyPortletUpgradeTask) to convert the legacy portlet to a gadget. This is entirely optional, however, and plugin authors are free to implement this method however they like.
Please ensure that the plugin upgrade task ONLY upgrades
portletConfigurations for the plugin that's being upgraded! Any other
portletConfigurations MUST be left untouched, as otherwise there's a risk of clobbering other portlets' data!
5. Register the upgrade task
Now we simply need to register the upgrade task as a component in the plugin:
The PluginUpgradeManager in SAL will automatically scan for components that implement the
PluginUpgradeTask interface. Please note that they have to be declared as
That's it. Simply re-package the plugin, deploy it to the instance of JIRA to upgrade and restart the JIRA instance. The plugin upgrade task should be executed when JIRA starts up.
It's highly recommended that you perform a backup of your JIRA instance before attempting this!