A Plugin for Atlassian Jira – Getting Started

12 December 2000
| |
Reading time: 7 minutes

Previous Page | Next Page | Pages: 0 1 2 3 4 5 6 7

Installing the tools

I am working on a MacBook Pro, so I have installed:

  • Java 8 JDK from Oracle
  • XCode from the App Store (this provides, inter alia, a command-line git client, which you will need – but there are other ways to obtain one)
  • IntelliJ IDEA direct from the Jetbrains site (I prefer a paid-for license, but the free community edition would do)
  • The Atlassian SDK – it turns out that Homebrew is the preferred way to install this, as the pkg installer makes unwarranted assumptions about your version of Java, Python and more

Start your project

The first thing to do is to decide how you’re going to version-control your work. I am using git with an in-house Bitbucket service, so I created a repository via the Web UI on bitbucket and cloned it to my workspace.

Use the sequence of instructions in the Hello World tutorial to create a plugin skeleton – but select your values for Maven group ID, Maven artifact ID, Maven version and Java package according to your real needs. For example (your inputs in bold):

$ git clone .../myPlugin.git
$ atlas-create-jira-plugin
Executing: /Applications/Atlassian/atlassian-plugin-sdk-6.3.12/apache-maven-3.2.1/bin/mvn com.atlassian.maven.plugins:maven-jira-plugin:6.3.21:create -gs /Applications/Atlassian/atlassian-plugin-sdk-6.3.12/apache-maven-3.2.1/conf/settings.xml
readlink: illegal option -- f
usage: readlink [-n] [file ...]
Warning: JAVA_HOME environment variable is not set.
Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=256M; support was removed in 8.0
[INFO] Scanning for projects...
[INFO] Using the builder org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder with a thread count of 1
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO] --- maven-jira-plugin:6.3.21:create (default-cli) @ standalone-pom ---
[INFO] Google Analytics Tracking is enabled to collect AMPS usage statistics.
[INFO] Although no personal information is sent, you may disable tracking by adding <allowGoogleTracking>false</allowGoogleTracking> to the amps plugin configuration in your pom.xml
[INFO] Sending event to Google Analytics: AMPS:jira - Create Plugin
[INFO] using stable product version: 7.12.0
[INFO] using stable data version: 7.12.0
Define value for groupId: : com.zuhlke.training.jira
Define value for artifactId: : myPlugin
Define value for version:  1.0.0-SNAPSHOT: : 
Define value for package:  com.zuhlke.training.jira: : 
Confirm properties configuration:
groupId: com.zuhlke.training.jira
artifactId: myPlugin
version: 1.0.0-SNAPSHOT
package: com.zuhlke.training.jira
 Y: : 
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] Generating project in Batch mode
[INFO] Archetype repository missing. Using the one from [com.atlassian.maven.archetypes:jira-plugin-archetype:5 -> https://maven.atlassian.com/public] found in catalog internal
[WARNING] The directory /Users/ihu/IdeaProjects/myPlugin already exists.
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 41.487 s
[INFO] Finished at: 2018-11-22T11:17:01+00:00
[INFO] Final Memory: 16M/223M
[INFO] ------------------------------------------------------------------------
$ ls -al myPlugin
total 40
drwxr-xr-x   8 ihu  staff   256 22 Nov 11:17 .
drwxr-xr-x   9 ihu  staff   288 22 Nov 11:15 ..
drwxr-xr-x  10 ihu  staff   320 22 Nov 11:15 .git
-rw-r--r--   1 ihu  staff  3659 22 Nov 11:15 .gitignore
-rw-r--r--   1 ihu  staff   310 22 Nov 11:17 LICENSE
-rw-r--r--   1 ihu  staff   625 22 Nov 11:17 README
-rw-r--r--   1 ihu  staff  1325 22 Nov 11:15 README.md
-rw-r--r--   1 ihu  staff  7658 22 Nov 11:17 pom.xml
drwxr-xr-x   4 ihu  staff   128 22 Nov 11:17 src
$ cd myPlugin
$ atlas-integration-test

You can now open (no need to import) the workspace in IDEA in order to configure README.md and .gitignore files appropriately. NB the Atlassian tool atlas-create-jira-plugin will create a README file (without an extension) – not to be confused with the markdown file README.md, which github or bitbucket servers will display on the project’s home page.

Before starting to modify anything, commit your initial checkpoint to version control. The easiest way is to open a terminal window in IDEA and enter the following two commands. Subsequent commits are more easily performed within the IDE, using CMD-K.

$ git add .
$ git commit -m 'Initial version'

Things to look out for

  • Make sure that the correct version of Java is used both to run your IDE and to run Jira (see above)
    • If you need multiple versions of Java JDK on your machine, consider the use of jEnv to manage the version in use (sorry Windows users – not available for you)
  • Configure IDEA via its preferences dialog to use atlas-mvn instead of the default bundled mvn executable
    • Maven home directory: /Applications/Atlassian/atlassian-plugin-sdk-6.3.12/apache-maven-3.2.1 (or similar)
  • If not automatically set, configure the IDEA project SDK to match your version of Java
    • Right-click the top level of the hierarchy under the Project Browser and select “open module settings”
    • Alternatively, click the prompt at the top of any Java source window if it warns you that the project SDK has not been set
  • Use the latest version of Jira both for the testkit and for Jira itself by adjusting the properties values at the bottom of the pom.xml file (I used 7.12.3 for both)
  • Add JVM arguments to the maven-jira-plugin in the POM to increase the amount of heap
    • See complete plugin configuration under “Final configuration” below
  • Look out for the scope of dependencies in the Maven POM – most artifacts should be “provided” or possibly “test” (e.g. com.google.code.gson:gson should be “provided”)
    • Search the target folder after executing atlas-run, atlas-package or atlas-integration-test to see which versions of libraries have been provided
    • Only specify “compile” scope for packages that Jira does not provide, but that your main plugin depends on (atlassian-spring-scanner-annotations appears to be an exception to this rule)
    • Give “runtime” scope to the dependency on atlassian-spring-scanner-runtime
  • Add the following property values to the POM:
  • Set the version of the junit dependency to ${junit.version}
  • Add the following dependencies to support integration testing:
    • com.atlassian.plugins.rest:atlassian-rest-module:3.2.18:provided
    • com.atlassian.sal:sal-api:3.1.0:provided
    • org.eclipse.gemini.blueprint:gemini-blueprint-core:${gemini.blueprint.version}:provided
    • com.atlassian.jira.tests:jira-testkit-client (just uncomment)
    • com.atlassian.jira:jira-tests:${jira-version}:test
    • org.slf4j:slf4j-log4j12:1.7.9:test
    • junit:junit-dep:${junit-version}:test
  • Do not let out-of-date tutorial documentation mislead you into adding a dependency on jira-func-test – this seems to be incompatible with Jira 7
  • In IDEA, if the source folders are not identified automatically, you may have to right-click the POM file and select “Maven -> import as Maven project” or “Maven -> reimport”
  • No Import-Package section should be needed in the main plugin’s atlassian-plugin.xml, because the imports are specified in the maven-jira-plugin configuration. However, you will need it in the test plugin (see below)
  • The fastdev console (see illustration below) is deprecated – if you enable it in the POM, you get lots of verbose warnings.
    • FastDev Console (FDC) would clash with QuickReload (qr) so you can only enable one or the other
    • Only if you have enabled FDC will you be able to initiate integration tests from the Web UI – this is useful if you wish to remote-debug the plugin code on the server. This is the only circumstance under which I found it useful to enable FDC
    • Whether you enable qr or FDC, running the atlas-package command will reload both the custom plugin and its plugin-tests plugin. However, in the FDC case, attempting to run the integration tests from the Web UI after a reload causes a server crash, while in the qr case it does nothing at all (the client receives a 404 error from the server because it tries to invoke a FastDev API)
    • However, there is a workaround – see Speeding up Plugin Testing at the end of this article.
  • Import-Package may specify ‘;version=”0″‘ if you don’t care which version of the dependency is required – normally you would not specify a version
  • Import-Package should usually specify ‘;resolution:=”optional”‘ – this ensures that the plugin will not fail to load just because some dependency is not available at the time
  • Before you can use the IDE effectively, it’s necessary to execute atlas-run, atlas-package or atlas-integration-test at least once. This downloads the required dependencies using the Maven dependency resolution mechanism.

Atlassian Plugin Test Console

Previous Page | Next Page | Pages: 0 1 2 3 4 5 6 7

Comments (0)


Sign up for our Updates

Sign up now for our updates.

This field is required
This field is required
This field is required

I'm interested in:

Select at least one category
You were signed up successfully.

Receive regular updates from our blog


Or would you like to discuss a potential project with us? Contact us »