In this recipe, we will see how to deploy a plugin into JIRA. We will see both the automated deployment using the Atlassian plugin SDK and the manual deployment.
Make sure you have the development environment set up as we discussed earlier. Also, the skeleton plugin should now have the plugin logic implemented in it.
Installing a JIRA plugin using the Atlassian plugin SDK is a cakewalk. The following steps show how it is done:
Open a command window and go to your plugin's root folder, that is, the folder where your
pom.xmlfile resides.Type
atlas-runand press Enter. It is possible to pass more options as arguments to this command. The details regarding this can be found at https://developer.atlassian.com/display/DOCS/atlas-run.You will see a lot of things happening as Maven downloads all the dependent libraries into your local repository. As usual, it is going to take a lot of time when you run it for the first time.
If you are on Windows, and if you see a security alert popping up, click on Unblock to allow incoming network connections.
When the installation is complete, you will see the following message:
[WARNING] [talledLocalContainer] INFO: Server startup in 123558 ms [INFO] [talledLocalContainer] Tomcat 6.x started on port [2990] [INFO] jira started successfully and available at http://localhost:2990/jira [INFO] Type CTRL-C to exit
Open
http://localhost:2990/jirain your browser.Log in using the username as
adminand password asadmin.Test your plugin! You can always go to Administration | Plugins | Manage Add-ons to confirm that the plugin is deployed properly.
If you already have a local JIRA installed, or if you want to manually install your plugin, all you need to do is to package the plugin JAR and install it via the Universal Plugin Manager (UPM), as described in detail at https://confluence.atlassian.com/display/UPM/Installing+Add-ons#InstallingAdd-ons-Installingbyfileupload. Or, you can copy it across to the
JIRA_Home/plugins/installed-pluginsdirectory and restart JIRA.You can package the plugin using the following command:
atlas-mvn clean packageUse
atlas-mvn clean installif you also want to install the packaged plugin into your local repository.
There is only one single command that does the whole thing: atlas-run. When you execute this command, it does the following tasks:
Builds your plugin JAR file
Downloads the latest/specified version of JIRA to your local machine if it is the first time you are running the command
Creates a virtual JIRA installation under your plugin's
/targetfolderCopies the JAR file into the
/target/jira/home/plugins/installed-pluginsdirectoryStarts JIRA in the Tomcat container
Now, if you look at your target folder, you will see a lot of new folders that were created for the virtual JIRA installation! The two main folders are the container folder, which has the Tomcat container setup, and the jira folder, which has the JIRA WAR along with the JIRA home setup!
You will find the database (HSQLDB), indexes, backups, and attachments under /target/jira/home. You can also see your jira-webapp at /target/container/tomcat6x/cargo-jira-home/webapps/jira.
If you have any JSPs that need to be put under the webapp, you will have to copy it to the appropriate folder under the aforementioned path!
It is also possible to use a specific version of JIRA or to re-use the data that we have used for testing. To find out how, just read on.
As mentioned earlier, atlas-run deploys the latest version of JIRA. But what if you want to deploy the plugin into an earlier version of JIRA and test it? There are two ways to do this:
Mention the JIRA version as an argument to
atlas-run. Make sure you runatlas-cleanif you already have the latest version deployed.Run
atlas-clean(if required).Run
atlas-run -v 5.0oratlas-run -version 5.0if you are developing for JIRA version 5.0. Replace the version number with a version of your choice.
Permanently change the JIRA version in your plugin's
pom.xmlfile.Go to your
pom.xmlfile.Modify the
jira.versionproperty value to the desired version.Modify the
jira.data.versionproperty value to a matching version.
Following is how it will look for JIRA 5.0:
<properties> <jira.version>5.0</jira.version> <jira.data.version>5.0</jira.data.version> </properties>
Suppose you have added some data onto virtual JIRA; how do you retain it when you clean startup JIRA next time? This is where a new SDK command comes to our rescue. After the atlas-run command has finished its execution, that is, after you have pressed Ctrl + C, execute the following command:
atlas-create-home-zip
This will generate a file named generated-test-resources.zip under the target folder. Copy this file to the /src/test/resources folder or any other known locations. Now modify the pom.xml file to add the following entry under configurations in the maven-jira-plugin plugin section:
<productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>Modify the path accordingly. This will re-use the configurations the next time you run atlas-run.
Following are some points to remember:
Missing a JAR file exception? Make sure the
local-repositoryattribute in thesettings.xmlfile points to the embedded Maven repository that comes with the SDK. If the problem still persists, manually download the missing JAR files and useatlas-mvn installto install them into the local repository.Getting a
BeanCreationExceptionerror? Make sure your plugin is of version 2. Check youratlassian-plugin.xmlfile to see if theplugins-version="2"entry is there or not. If not, add the entry shown as follows:<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.artifactId}" plugins-version="2">Run
atlas-cleanfollowed byatlas-runafter you have added the preceding entry.