Using the JIRA API via Chrome App

Background

I started making a JIRA plugin (in JAVA) and was bothered by the all the fluff that was needed and terrible documentation from Atlassian. All I really needed was to call the JIRA API and handle the JSON data returned. So, I whipped up a Chrome App in a couple hours.

Bootstrap and jQuery

Typically I avoid these if at all possible. Not because they aren’t great or anything, but because I consider them ‘shortcuts’ and find more value in doing everything by hand. In a previous project, getting rid of jQuery cut my package size in half. For this project, I decided to use both in the interest in pumping out a Proof of Concept as fast as possible.

The Source Code

This project is hosted on GitHub. Pull down the package and load in Chrome by enabling developer options and loading the unpacked package. Alternatively, use this Chrome App to load the App.

Calling the JIRA API

The user is shown a login page. The user enters the JIRA URL, like https://example-jira.atlassian.net/, and their username and password (note this will not work if you only use oAuth to login). When the user submits the form I make an AJAX call to the endpoint rest/auth/latest/session using Basic Auth. If the login is successful a dummy dashboard is shown, else an error message is display on the login form.

Screenshot

JIRA API

Making a JIRA Plugin

Background

I wanted to make a plugin for Atlassian’s JIRA platform that can be used on the cloud based solution. This walk-through will cover the necessary steps to get going and create a JIRA Plugin that will be it’s own page. I will cover getting the SDK, setting up Eclipse, and adding a new page to JIRA. This turned out to be more painful than it should have been thanks to confusing and outdated documentation.

Setup

This post will cover development in OSX (El Capitan more specifically). If you are a Windows user, check out the official documentation.

Verify the Java Developer Kit (JDK) is Installed

  1. Open Terminal
    Screen Shot 2016-05-05 at 1.44.40 PM
  2. Enter: javac -version
    Screen Shot 2016-05-05 at 1.45.45 PM

    • If Java is installed, then move onto the next section.
  3. If you see the following prompt select “OK” (if you select “More Info…” your default browser will open a link to Oracle.com
    Screen Shot 2016-05-05 at 1.48.38 PM
  4. In your browser, navigate to the JDK8 downloads page
    Screen Shot 2016-05-05 at 1.50.41 PM
  5. Scroll down to the first section titled, “Java SE Development Kit…”
    Screen Shot 2016-05-05 at 1.51.43 PM
  6. Select the radio button, “Accept License Agreement”
    Screen Shot 2016-05-05 at 1.53.13 PM
  7. Select the proper download for your system
    Screen Shot 2016-05-05 at 1.54.58 PM
  8. Run the .dmg file from your Downloads folder
    Screen Shot 2016-05-05 at 1.57.47 PM
  9. Double-click on the box icon to begin the installation
    Screen Shot 2016-05-05 at 1.58.42 PM
  10. Select “Continue”
    Screen Shot 2016-05-05 at 1.59.42 PM
  11. Select “Install”
    Screen Shot 2016-05-05 at 2.00.39 PM
  12. Enter your password and select “Install Software” to continue
    Screen Shot 2016-05-05 at 2.01.49 PM
  13. After the install completes, select “Close”
    Screen Shot 2016-05-05 at 2.03.18 PM
  14. Close the JDK installer window
    Screen Shot 2016-05-05 at 2.04.41 PM
  15. Right-click on the installer on your desktop and select, “Eject…”
    Screen Shot 2016-05-05 at 2.06.07 PM
  16. Delete the .dmg file from your Downloads
    Screen Shot 2016-05-05 at 2.08.03 PM
  17. In Terminal, enter javac -version
    Screen Shot 2016-05-05 at 2.11.23 PM

    • If your system can not locate Java, then you may need to set your PATH

Install the Atlassian SDK

  1. In your browser, download the PKG file
    Screen Shot 2016-05-05 at 2.19.48 PM
  2. Run the .dmg file from your Downloads folder
    Screen Shot 2016-05-05 at 2.41.51 PM
  3. Double-click the icon to begin the installation
    Screen Shot 2016-05-05 at 2.42.36 PM
  4. Select the “Open” button in the alert
    Screen Shot 2016-05-05 at 2.43.26 PM
  5. Enter your password and select “OK”Screen Shot 2016-05-05 at 2.44.37 PM
  6. Select “Next >”
    Screen Shot 2016-05-05 at 2.46.09 PM
  7. Select “Next >”
    Screen Shot 2016-05-05 at 2.46.41 PM
  8. After the install completes, select “Finish”
    Screen Shot 2016-05-05 at 2.48.18 PM
  9. Close the installer window
    Screen Shot 2016-05-05 at 2.48.54 PM
  10. Right-click on the installer on your desktop and select, “Eject…”
    Screen Shot 2016-05-05 at 2.50.26 PM
  11. Delete the .dmg file from your Downloads
    Screen Shot 2016-05-05 at 2.51.37 PM
  12. In Terminal, enter atlas-version
    Screen Shot 2016-05-05 at 2.53.10 PM

Running JIRA Locally

  1. In Terminal, enter mkdir tutorial
    Screen Shot 2016-05-05 at 4.03.55 PM
  2. Enter cd tutorial
    Screen Shot 2016-05-05 at 4.05.04 PM
  3. Enter atlas-run-standalone --product jira
    Screen Shot 2016-05-05 at 4.25.53 PM

    • You will be asked to join the developer mailing list, just enter n so the process can continue unimpeded
  4. In your browser, open the URL displayed in Terminal
    Screen Shot 2016-05-05 at 4.30.25 PM
  5. Login using admin for both the Username and Password
    Screen Shot 2016-05-05 at 4.44.32 PM
  6. Select “Continue”
    Screen Shot 2016-05-05 at 4.34.10 PM
  7. Select “Next”
    Screen Shot 2016-05-05 at 4.35.45 PM
  8. Select “Skip quick tour”
    Screen Shot 2016-05-05 at 4.36.33 PM
  9. Enter Test Project for the Project name and TEST for the Key, and then select “Create Project”
    Screen Shot 2016-05-05 at 4.38.06 PM
  10. Select “Skip”
    Screen Shot 2016-05-05 at 4.39.30 PM
  11. Close your browser
    Screen Shot 2016-05-05 at 4.41.27 PM
  12. In Terminal, press [Control] + [D]
    Screen Shot 2016-05-05 at 4.46.53 PM

Creating A JIRA Plugin

Create an Empty Plugin

  1. In Terminal, enter atlas-create-jira-plugin
    Screen Shot 2016-05-06 at 1.09.58 PM
  2. Enter com.timothycope.demo for the groupID
    Screen Shot 2016-05-06 at 1.13.01 PM
  3. Enter demo for artifactId
    Screen Shot 2016-05-06 at 1.14.21 PM
  4. Enter 1.0-SNAPSHOT for version
    Screen Shot 2016-05-06 at 1.15.36 PM
  5. Enter com.timothycope.demo.plugin for packageScreen Shot 2016-05-06 at 1.21.45 PM
  6. Enter Y
    Screen Shot 2016-05-06 at 1.23.01 PM
  7. Enter cd demo
    Screen Shot 2016-05-06 at 1.32.46 PM
  8. Enter atlas-run
    Screen Shot 2016-05-06 at 1.34.51 PM
  9. If you don’t get the error shown in the screenshot above continue to step 10, otherwise:
    1. Enter nano pom.xml
      Screen Shot 2016-05-06 at 1.39.25 PM
    2. Use the down-arrow key to scroll to the “<properties>” section (near the end of the file)
      Screen Shot 2016-05-06 at 1.41.58 PM
    3. Decrement the <jira.verison> number
      Screen Shot 2016-05-06 at 1.44.11 PM

      • UPDATE: Set the JIRA version to the minimum you want to support. For the available versions see this list. I ended up setting mine to 7.2.0-OD-02-009. Apparently, 1000.0.0 was published on accident.
    4. Press [Control] + [O]
      Screen Shot 2016-05-06 at 1.45.34 PM
    5. Press [Enter]
      Screen Shot 2016-05-06 at 1.46.01 PM
    6. Press [Control] + [X]
      Screen Shot 2016-05-06 at 1.47.30 PM
    7. Enter atlas-run -U
      Screen Shot 2016-05-06 at 2.55.42 PM

      • If you do not see the JIRA instance start, but instead see the same message as before then: Repeat decrementing the version number and running atlas-run -U until it works.
  10. In your browser, open the JIRA url presented in terminal
    Screen Shot 2016-05-06 at 3.04.08 PM
  11. Enter admin for both the Username and PasswordScreen Shot 2016-05-06 at 3.07.11 PM
  12. Select “Continue”
    Screen Shot 2016-05-06 at 3.08.33 PM
  13. Select “Next”
    Screen Shot 2016-05-06 at 3.09.23 PM
  14. Select “Skip quick tour”
    Screen Shot 2016-05-06 at 3.09.59 PM
  15. Enter Test Project for the Project name and TEST for the Key, and then select “Create Project”
    Screen Shot 2016-05-06 at 3.11.18 PM
  16. Select “Skip”
    Screen Shot 2016-05-06 at 3.12.26 PM
  17. Select the gear icon and then “Add-ons”
    Screen Shot 2016-05-06 at 3.14.09 PM
  18. Scroll down the page and you should see two “demos”; one is the plugin and the other its unit testsScreen Shot 2016-05-06 at 3.16.02 PM
  19. Close your browser and in Terminal press [Control] + [D]
    Screen Shot 2016-05-06 at 3.19.37 PM

Update the Generic Plugin’s Data

  1. Enter nano pom.xml
    Screen Shot 2016-05-06 at 3.21.48 PM
  2. Use the down-arrow key to scroll to the <organization> section
    Screen Shot 2016-05-06 at 3.23.27 PM
  3. Change the value for name to “Timothy Cope”
    Screen Shot 2016-05-06 at 3.25.24 PM
  4. Change the value for url to “http://timothycope.com/”
    Screen Shot 2016-05-06 at 3.26.14 PM
  5. Press [Control] + [O]
    Screen Shot 2016-05-06 at 3.27.00 PM
  6. Press [Enter]
    Screen Shot 2016-05-06 at 3.27.27 PM
  7. Press [Control] + [X]
    Screen Shot 2016-05-06 at 3.28.00 PM
  8. Enter atlas-run
    Screen Shot 2016-05-06 at 3.45.31 PM
  9. Navigate to the JIRA url shown in Terminal, login, and view Add-ons
    Screen Shot 2016-05-06 at 3.50.01 PM
  10. Close your browser and in Terminal press [Control] + [D]
    Screen Shot 2016-05-06 at 3.52.06 PM

Setup Eclipse

Getting Eclipse

  1. In your browser navigate to the Eclipse Downloads page for the Luna release
    Screen Shot 2016-05-06 at 3.56.36 PM
  2. Select the link for Eclipse IDE for Java EE Developers, Mac Cocoa 64-bit and then select “Download”
    Screen Shot 2016-05-06 at 3.59.15 PM
  3. Double-click on the .tar file in your Downloads folder
    Screen Shot 2016-05-06 at 4.00.57 PM
  4. (Optional) Drag the “eclipse” folder to Applications
    Screen Shot 2016-05-06 at 4.02.55 PM
  5. Open the eclipse folder
    Screen Shot 2016-05-06 at 4.04.10 PM
  6. Right-click on the eclipse icon and select “Open”
    Screen Shot 2016-05-06 at 4.06.04 PM
  7. Select “Open”
    Screen Shot 2016-05-06 at 4.06.51 PM
  8. (Optional) Right-click on the eclipse icon in your dock and select “Options” -> “Keep in Dock”
    Screen Shot 2016-05-06 at 4.09.04 PM
  9. Enter ~/tutorial and then select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  10. Select “Eclipse” and then “Preferences” from the menu
    Screen Shot 2016-05-09 at 8.20.01 AM
  11. In the search box, type “Installed JREs” and select the result
    Screen Shot 2016-05-09 at 8.21.53 AM

    • Verify that the version is 1.8 (We installed JDK v8 earlier) and close the window by selecting “Cancel”
  12. Select “Help” and then “Install New Packages” from the menu
    Screen Shot 2016-05-09 at 8.28.11 AM
  13. Select “Add…”
    Screen Shot 2016-05-09 at 8.29.56 AM
  14. Enter Sonatype M2Eclipse for Name and http://download.eclipse.org/technology/m2e/releases for Location and the select “OK”
    Screen Shot 2016-05-09 at 8.31.47 AM
  15. Select “Maven Integration for Eclipse” and then “Next >”Screen Shot 2016-05-09 at 8.35.02 AM
  16. Select “Next >”
    Screen Shot 2016-05-09 at 8.35.54 AM
  17. Select “I accept the terms of the license agreement” and then “Finish”
    Screen Shot 2016-05-09 at 8.36.37 AM
  18. Select “Yes”
    Screen Shot 2016-05-09 at 8.40.30 AM
  19. Select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  20. Select “Eclipse” and then “Preferences” from the menu
    Screen Shot 2016-05-09 at 8.43.11 AM
  21. Expand “Maven” and select “Installations” and then select “Add…”
    Screen Shot 2016-05-09 at 8.45.09 AM
  22. Select “Directory…”
    Screen Shot 2016-05-09 at 8.47.07 AM
  23. Browse to your “Applications > Atlassian > atlassian-plugin-sdk-<version> > apache-maven-<version>” directory and select “Open”
    Screen Shot 2016-05-09 at 8.55.59 AM
  24. Select “Finish”
    Screen Shot 2016-05-09 at 8.56.28 AM
  25. Select “apache-maven-<version>” and then select “Apply”
    Screen Shot 2016-05-09 at 8.57.31 AM
  26. Select “Maven” from the left navigation menu and ensure “Download repository index updates on startup” is unchecked
    Screen Shot 2016-05-09 at 8.59.54 AM
  27. Select “OK” and then close Eclipse
    Screen Shot 2016-05-09 at 9.00.49 AM
  28. Delete the .tar file from your Downloads folder
    Screen Shot 2016-05-06 at 4.12.10 PM

Getting the Project Ready to Import into Eclipse

  1. In Terminal, enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-06 at 4.16.40 PM
  2. Open Eclipse and select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  3. Select “File” and then select “Import” from the menu
    Screen Shot 2016-05-09 at 9.04.13 AM
  4. Expand “General”, select “Existing Projects into Workspace”, and then select “Next >”
    Screen Shot 2016-05-09 at 9.05.49 AM
  5. Select “Browse…”, browse to the root directory of your workspace, and then select “Open”
    Screen Shot 2016-05-09 at 9.16.23 AM
  6. Select “Finish”
    Screen Shot 2016-05-09 at 9.57.09 AM
  7. Close the Welcome page by selecting the “X” on its tab
    Screen Shot 2016-05-09 at 9.59.03 AM
  8. In the Project Explorer, expand “src/main/resources” and double-click “atlassian-plugin.xml”
    Screen Shot 2016-05-09 at 10.00.18 AM
  9. Select the “Source” tab
    Screen Shot 2016-05-09 at 10.08.10 AM
  10. Close Eclipse
    Screen Shot 2016-05-09 at 10.09.26 AM

Adding to the Plugin

  1. In Terminal, enter atlas-create-jira-plugin-module
    Screen Shot 2016-05-09 at 10.16.11 AM
  2. Enter 21
    Screen Shot 2016-05-09 at 10.16.43 AM
  3. Enter DemoServlet
    Screen Shot 2016-05-09 at 10.18.00 AM
  4. Enter com.timothycope.demo.servlet
    Screen Shot 2016-05-09 at 10.19.08 AM
  5. Enter n
    Screen Shot 2016-05-09 at 10.20.11 AM
  6. Enter n
    Screen Shot 2016-05-09 at 10.20.54 AM
  7. Enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-09 at 10.22.51 AM
  8. Enter atlas-run
    Screen Shot 2016-05-09 at 10.31.11 AM
  9. In your browser, navigate to the JIRA url listed in Terminal
    Screen Shot 2016-05-09 at 10.41.04 AM
  10. Log in using admin for the Username and Password
    Screen Shot 2016-05-09 at 10.41.55 AM
  11. Navigate to /jira/plugins/servlet/demoservlet
    Screen Shot 2016-05-09 at 10.47.58 AM

    • The URL comes from the “atlassian-plugin.xml” section <url-pattern>
  12. Close the browser and in Terminal, press [Control] + [D]
    Screen Shot 2016-05-09 at 10.51.32 AM

Adding a Template Renderer to the Plugin

  1. In Terminal, enter atlas-create-jira-plugin-module
    Screen Shot 2016-05-09 at 10.53.58 AM
  2. Enter 1
    Screen Shot 2016-05-09 at 10.54.48 AM
  3. Enter com.timothycope.tutorial.TemplateRenderer
    Screen Shot 2016-05-09 at 11.02.45 AM
  4. Press [Enter]
    Screen Shot 2016-05-09 at 11.03.46 AM
  5. Press [Enter]
    Screen Shot 2016-05-09 at 11.05.02 AM
  6. Enter n
    Screen Shot 2016-05-09 at 11.05.26 AM
  7. Open Eclipse and select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  8. Open “pom.xml”
    Screen Shot 2016-05-09 at 11.10.52 AM
  9. Select the “pom.xml” tab and scroll down to the “<dependencies>” section
    Screen Shot 2016-05-09 at 11.13.09 AM
  10. Add the following dependency:
    Screen Shot 2016-05-09 at 11.16.47 AM
  11. Scroll down to <instructions> and comment out the <Atlassian-Plugin-Key>
    Screen Shot 2016-05-09 at 11.20.35 AM
  12. Save the changes and exit EclipseScreen Shot 2016-05-09 at 11.23.40 AM
  13. In Terminal, enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-09 at 11.25.29 AM
  14. Enter atlas-runScreen Shot 2016-05-09 at 11.32.14 AM
  15. In your browser, navigate to the JIRA url listed in Terminal
    Screen Shot 2016-05-09 at 10.41.04 AM
  16. Log in using admin for the Username and Password
    Screen Shot 2016-05-09 at 10.41.55 AM
  17. Select the gear icon and then select “Add-ons”
    Screen Shot 2016-05-09 at 11.35.26 AM
  18. Select “Manage add-ons”
    Screen Shot 2016-05-09 at 11.38.15 AM
  19. Scroll down to the “demo” plugin and expand
    Screen Shot 2016-05-09 at 11.39.55 AM

    • Note that the plugin is currently disabled
  20. Close the browser and in Terminal, press [Control] + [D]
    Screen Shot 2016-05-09 at 11.46.55 AM

Creating the Template

Make the HTML Template

  1. In Terminal enter cd src/main/resources
    Screen Shot 2016-05-09 at 11.50.57 AM
  2. Enter mkdir templates && cd $_
    Screen Shot 2016-05-09 at 11.54.43 AM
  3. Enter touch index.vm
    Screen Shot 2016-05-09 at 11.56.31 AM
  4. Enter nano index.vm
    Screen Shot 2016-05-09 at 11.57.20 AM
  5. Enter the following HTML code
    Screen Shot 2016-05-09 at 12.02.19 PM
  6. Press [Control] + [O]
    Screen Shot 2016-05-09 at 12.03.24 PM
  7. Press [Enter]
    Screen Shot 2016-05-09 at 12.03.39 PM
  8. Press [Control] + [X]
    Screen Shot 2016-05-09 at 12.04.51 PM

Update Servlet to Respond Using the Template

  1. Open Eclipse and select “OK”
    Screen Shot 2016-05-09 at 9.26.44 AM
  2. Open the “DemoServlet.java” file (refresh your project if you do not see it)
    Screen Shot 2016-05-09 at 12.21.24 PM
  3. Add the following imports:
    Screen Shot 2016-05-09 at 12.28.05 PM

    • The second set of imports is due to an issue I ran into
  4. Add the annotation to our class:
    Screen Shot 2016-05-09 at 12.33.48 PM
  5. Add a variable and annotation for the Component Import:
    Screen Shot 2016-05-09 at 12.36.01 PM
  6. Add a variable to hold the template’s location:
    Screen Shot 2016-05-09 at 12.38.02 PM
  7. Add in the constructor
    Screen Shot 2016-05-09 at 12.40.01 PM
  8. Replace the content in the doGet() with the following:
    Screen Shot 2016-05-09 at 12.47.07 PM
  9. Open “atlassian-plugin.xml” and scroll down to the “<component-import>” section
    Screen Shot 2016-05-09 at 12.49.22 PM
  10. Ensure the templateRenderer used is Atlassian’s and not ours by changing the Component Import to:
    Screen Shot 2016-05-09 at 12.51.44 PM
  11. Save and close Eclipse
    Screen Shot 2016-05-09 at 12.53.44 PM
  12. In Terminal, Enter cd ~/tutorial/demo
    Screen Shot 2016-05-09 at 12.56.32 PM
  13. Enter atlas-mvn eclipse:eclipse
    Screen Shot 2016-05-09 at 12.57.54 PM
  14. Enter atlas-run
    Screen Shot 2016-05-09 at 1.05.08 PM
  15. In your browser, navigate to the JIRA url listed in Terminal
    Screen Shot 2016-05-09 at 10.41.04 AM
  16. Log in using admin for the Username and Password
    Screen Shot 2016-05-09 at 10.41.55 AM
  17. Select the gear icon and then select “Add-ons”
    Screen Shot 2016-05-09 at 11.35.26 AM
  18. Select “Manage add-ons”
    Screen Shot 2016-05-09 at 11.38.15 AM
  19. Scroll down to the “demo” plugin and expand
    Screen Shot 2016-05-09 at 1.07.52 PM

    • Note the plugin should be active now that we’ve fixed the Component Import
  20. Navigate to /jira/plugins/servlet/demoservlet
    Screen Shot 2016-05-09 at 1.10.01 PM
  21. Close the browser and in Terminal, press [Control] + [D]
    Screen Shot 2016-05-09 at 1.12.01 PM

Updating the SDK

In the tutorial folder run atlas-update. If you get permission errors the easiest fix is:
sudo chmod -R 777 {path_to_sdk}
For me the path was /Applications/Atlassian.

Further Reading