Overview

AddOnUpgradeManager is an UpgradeManager strongly inspired from JIRA Upgrade Manager. It offers a way to implement an Upgrade Manager dedicated to any JIRA Plugin.

Administration of JIRA Setting

As JIRA administrator, you have to managed JIRA following differents ways.

• The JIRA settings are suitable to you activity, then you have to manage the different project creation using defaults Schemes. I do no think that it is majority of uses.
• You or your users prefer to have some specifics settings concerning Issue Type, Issue Status, Workflows, ... Then, you apply asked settings through the Administration JIRA Web pages. In some company, you may have to reproduce theses settings on Development, Qualification and finaly Production environments. Here, some of you are looking for any useful Jelly Tags to avoid to apply them manually.
• You have the knowledge, the capacity and the time to create some new Jelly Tag (not yet provided by Atlassian) in order to simplify the way to apply you settings. Here, you have a Jelly script able to apply your settings. Great !

But, with future release of your settings, will you able to describe in Jelly all required tasks to perform a migration between two release of your settings ?

JIRA UpgradeManager

To apply each required upgrade between differents release of JIRA, Atlassian have developped a Upgrade mechanism the UpgradeManager, in charge of execution a set UpgradeTask.

Each UpgradeTask is identified by its own number. You are able to see these number in bottom of JIRA Pages ..

• (Enterprise Edition, Version: 3.6.5-#161)
• (Enterprise Edition, Version: 3.7.2-#186)

Between the release 3.6.5 and 3.7.2, they are probably 25 UpgradeTask.

Atlassian have defined 3 sets of UpgradeTask around the licence level :

License	Set of UpgradeTask
Standard	standardupgrades.xml
Professional	professionalupgrades.xml
Enterprise	enterpriseupgrades.xml

Why an UpgradeManager for plugins ?

And so, you may have understand my idea !

I am able to create my own set of UpgradeTask in charge of applying what I want on the JIRA settings !



Yes, but how may I declared theses UpgradeTask in UpgradeManager ?

Nothing has been done to do that ...



In the first release of my plugins in my company, I have developped a new release of UpgradeManager overriding the JIRA one. Also, I was able to define my own set of UpgradeTask, and they was executed at the restart of JIRA just after JIRA Upgrade.



Since, JIRA 3.3 or 3.4 (I forgot), these solution have been broken due to cyclic dependencies around my own UpgradeManager, the JIRA UpgradeManager, CustomFieldManager, PluginManager and others ...



Now, the implemented UpgradeManager in Kaamelot do not override JIRA UpgradeManager.

Description/Features

Kaamelot UpgradeManager is based on :

• An interface : IUpgradeManager
• An abstract Class : AAddOnUpgradeManager
• A XML file describing the set of UpgradeTask
• A Jelly Tag : ManageUpgrade

Usage

• Create your(s) UpgradeTask(s)
  
  You will have to extend the interface UpgradeTask (JIRA native), in order

   public interface UpgradeTask {
       /** @return  The build number that this upgrade is applicable to */
       public String getBuildNumber();
  
       /** A short (less than 50 chars) description of the upgrade action */
       public String getShortDescription();
  
       /** Perform the upgrade. */
       public void doUpgrade() throws Exception;
  
       /** Return any errors that occur.  Each entry is a string. */
       public Collection getErrors();
   }
  

• Define your Set of UpgradeTask
  
  You will have to create a XML file (upgrade-jira-plugin-MYPLUGIN.xml) as follow :

  <upgrades type="AddOns"  >
       <upgrade build="1">
           <class>com.mycompany.jira.upgrade.UpgradeTask_Build_1</class>
       </upgrade>
       <upgrade build="2">
           <class>com.mycompany.jira.upgrade.UpgradeTask_Build_2</class>
       </upgrade>
   </upgrades>

• Create your UpgradeManager
  
  The Kaamelot AddOnUpgradeManager is defined for the moment, just for exemple. Its UpgradeTask's Set (upgrade-jira-plugin-kaamelot-addon.xml) is empty. You will have to extend you own UpgradeManager extending AAddOnUpgradeManager and implementing abstracts methods.

        package com.mycompany.jira.upgrade;
        public class YourUpgradeManagerImpl extends AAddOnUpgradeManager {
           private static String addOnFileName = "upgrade-jira-plugin-kaamelot-addon.xml";
        	/** Return the fullFileName (Classpath relative) of your Set of UpgradeTask */
        	public String getAddOnFileName() {
        		return addOnFileName;
        	}
  
        	/** Return the Current BuildNumber. */
        	public String getCurrentAddOnBuildNumber() {
        		return "1";
        	}
  
        	/** Return the Required JIRA BuildNumber allow to apply your Set of UpgradeTask. */
        	public String getRequiredJiraBuildNumber() {
        		return "155";
        	}
  
        	/** Return Variable Key used to store the number of your last applied UpgradeTask */
        	public String getKeyParameter() {
        	   return "jira.plugin.version.kaamelot.addon";		
        	}
        }
  

• Build your plugin and deploy it in your JIRA.
• When JIRA is started, go to Adminitration Page on Jelly Runer, and execute the Upgrade as follow :
  
  

  <JiraJelly xmlns:jira="jelly:com.atlassian.jira.jelly.JiraAddOnTagLib">
        	<ManageUpgrade upgradeManagerClass="com.mycompany.jira.upgrade.YourUpgradeManagerImpl" >
        	</ManageUpgrade>
  </JiraJelly>

Now, you are able to define your owns UpgradeTasks and execute them on each of your environment.