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 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. Here is how it is done:
Open a command window and go to your plugin's root folder, that is, the folder where your
pom.xmlresides.Type
atlas-runand press Enter. It is possible to pass more options as arguments to this command for which the details can be found at https://developer.atlassian.com/docs/developer-tools/working-with-the-sdk/command-reference/atlas-run.You will see a lot of things happening as Maven downloads all the dependent libraries in to your local repo. As usual, it is going to take 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 Unblock to allow incoming network connections.
When the installation is completed, you will see messages similar to the following:
Open
http://localhost:2990/jirain your browser.Log in using the username
adminand passwordadmin.Test your plugin! You can always go to Administration | Add-ons | Manage add-ons menu 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 due to some reason, all you need to do is to package the plugin JAR and install it via UPM (Universal Plugin Manager) as described at https://confluence.atlassian.com/display/UPM/Installing+add-ons#Installingadd-ons-Installingbyfileupload. Or, you can copy it across to JIRA_Home/plugins/installed-plugins directory and restart JIRA.
You can package the plugin using the following command:
atlas-mvn clean package
Use atlas-mvn clean install if you also want to install the package plugin into your local repo.
There is only one single command that does the whole thing: atlas-run. When you execute this command, it does the following:
Builds your plugin
.jarfile. It also builds the.obrfile, which is the OSGi Bundle Repository file; that is essentially a.jarfile containing our plugin and all dependent plugins, if we have any. More details on .obr files can be read at https://developer.atlassian.com/docs/faq/advanced-plugin-development-faq/bundling-extra-dependencies-in-an-obr.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
/targetfolder.Copies the
.jarfile in to the/target/jira/home/plugins/installed-pluginsdirectory.Starts 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 main two folders are the container folder that has the Tomcat container set up and the jira folder that has the JIRA WAR along with the JIRA home setup.
You will find the database (HSQLDB), indexes, backups, and attachments under /target/jira/home, and you will see your jira-webapp at /target/container/tomcat8x/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 reuse the data that we have used for testing.
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 it:
Mention the JIRA version as an argument to
atlas-run; make sure you runatlas-cleanif you already have the latest version deployed:a. Run
atlas-clean(if required)b. 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
pom.xml:a. Go to your
pom.xmlb. Modify the
jira.versionproperty value to the desired version.c. Modify the
jira.data.versionto a matching version.This 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 added some data on to virtual JIRA; how do you retain it when you clean start-up JIRA next time?
This is where a new SDK command comes to our rescue.
After atlas-run is finished, that is, after you pressed Ctrl + C, execute the following command:
atlas-create-home-zip
This will generate a file named generated-test-resources.zip under the target/jira folder. Copy this file to the /src/test/resources folder or any other known location. Now modify the pom.xml to add the following entry under configurations in the maven-jira-plugin:
<productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>
Modify the path accordingly. This will reuse the data the next time you run atlas-run after an atlas-clean.
Missing JAR file exception? Make sure the local-repository attribute in the settings.xml points to the embedded Maven repository that comes with the SDK. If the problem still persists, manually download the missing .jar files and use atlas-mvn install to install them in to the local repository.
Watch out for the proxy settings or antivirus settings that can potentially block the download in some cases!
BeanCreationException? Make sure your plugin is version 2. Check atlassian-plugin.xml to see if the plugins-version="2" entry is there or not. If not, add the entry, as shown here:
<atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}"
plugins-version="2">Run atlas-clean followed by atlas-run.