Tutorial - Application links in JIRA
This tutorial applies to JIRA 5.0.
Level of experience:
This is an intermediate tutorial. You should have completed at least one beginner tutorial before working through this tutorial. See the list of developer tutorials.
It should take you approximately 1 hour to complete this tutorial.
On this page:
Overview of the Tutorial
This tutorial shows you how to build a JIRA plugin that communicates with a Confluence instance through an application link. The plugin will add a panel to the issue view page in JIRA. When a user opens the issue in JIRA, the plugin searches the Confluence space linked to the JIRA project and lists the pages that mention the issue. In other words, the panel lists any page in a Confluence space that references the currently viewed issue by issue key.
Here's how it'll look:
Getting this done will require a little administration work along with your development work. First, you'll need to set up an Application Link between the JIRA instance and the Confluence installation. You will then need to configure a project link between a JIRA project and Confluence space.
Your JIRA plugin will consist of the following components:
- Java classes encapsulating the plugin logic.
- Resources for display of the plugin user interface (UI).
- A plugin descriptor (XML file) to enable the plugin module in the Atlassian application.
When you have finished, all these components will be packaged in a single JAR file.
To complete this tutorial, you need to know the following:
- The basics of Java development: classes, interfaces, methods, how to use the compiler, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
- How to open the plugin project in your IDE, such as Eclipse or IDEA.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source as a ZIP archive by choosing download here: https://bitbucket.org/atlassian_tutorial/jira-applinks
Step 1. Create the plugin project
In this step, you'll use two
atlas- commands to generate stub code for your plugin. The
atlas- commands are part of the Atlassian Plugin SDK, and automate much of the work of plugin development for you.
- If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
- Open a terminal and navigate to the directory in which you want to create the plugin project.
Enter the following command to create a plugin skeleton:
- Choose the option to create a plugin for JIRA 5.0.
As prompted, enter the following information for your plugin:
- Confirm your entries when prompted.
Step 2. Review and tweak the generated stub code
It's a good idea to familiarise yourself with the project configuration file, known as the POM (Project Object Model definition file). In this section, you will review and tweak the POM file.
Add plugin metadata to the POM
The POM is located at the root of your project and declares the project dependencies and other information.
Add some metadata about your plugin and your company or organisation. You also need to add a dependency on Application Links here.
- In the command window, switch to the new directory created for your project, tutorial-jira-ual.
pom.xmlfile for editing, and add your company or organisation name and your website to the
Add a dependency on Application Links
- Save the file.
Step 3. Add your plugin module to the plugin descriptor
Now use the plugin module generator (another
atlas- command) to generate the stub code for the modules needed by the plugin. The plugin module type is an issue tab panel plugin module.
Add it as follows:
- In a command window, go to the root folder of your plugin project (where the
- For the module type to add, choose Issue Tab Panel.
- When prompted, enter the following information to describe your plugin module:
- Enter New Classname:
- Enter Package Name:
- Enter New Classname:
- When prompted with Show Advanced Setup, choose 'N' (for 'No').
- When prompted with Add Another Plugin Module, choose 'N'.
At this point, your plugin contains the following files:
The license for this plugin.
The Maven Project Object Model file.
The 'readme' file for this project.
The Issue Tab Panel class generated.
An empty Java class file generated by
The file containing i18n key/value pairs.
The Atlassian plugin descriptor.
The Velocity macro for rendering content on the Issue Tab Panel.
A test file for the Issue Tab Panel class.
An empty Java file generated by atlas-create-jira-plugin. Ignore or delete this.
An empty Java file generated by
A readme file for test resources.
A readme file for test resources.
The log output file created by
Step 4. Modify the plugin descriptor
Now adjust the plugin descriptor file,
atlassian-plugin.xml, to import the Application Links component (
EntityLinkService), as follows:
- In the command window, change to the src/main/resources directory.
component-importelement below to your
issue-tabpanelelement. We added this when we ran the
Step 5. Develop your plugin code
You have already generated the stubs for your plugin modules. Now you'll write some code that will make your plugin do something.
As a reminder, this plugin will communicate with a Confluence site via Application Links. It searches the Confluence search for mentions of the currently viewed issue, and displays the results on the view issue page.
To do this, our Issue Tab Panel needs to use the
EntityLinkService to retrieve and use the Application Link to Confluence.
The SDK code generator gave us a few of the methods we need, such as
showPanel(). We'll extend the code as follows:
- Open the
ConfluenceSpaceTabPanel.javafile for editing. You can find the file in the directory src/main/java/com/example/plugins/tutorial/jira/tabpanels under your project home.
First, add some import statments to the ones that the SDK gave us:
The other import statement can remain, except for the following. You need to remove it since we're using the Crowd package's user:
After the line that instantiates the logger, add the following code:
- Notice we're injecting the
ConfluenceSpaceTabPanelvia the class constructor.
getActionsmethod determines what appears in our tab. Replace its contents with the following:
This code uses the
EntityLinkServiceto find the Application Link that administrators have configured between the JIRA project and a Confluence space. If it doesn't find a link, it simply prints a message to the tab panel saying so.
Now that you have an
EntityLinkobject, use this to create a request factory to send authenticated HTTP requests to the linked Confluence installation:
This request factory takes care of authentication to Confluence, using the authentication type configured by the system administrator. With this request factory, you can now make an authenticated request to the Confluence REST API to perform the search.
Initialize a few variables:
Next, add a Java
trystatement with the contents shown:
This creates a request to the Confluence REST API that looks for the issue's key issue and executes the request, storing the results in the
Now parse the response of the REST GET request, put the results in a list we can present in the issue tab:
tryblock and add
Notice the catch statement for
CredentialsRequiredException. The request may throw this exception if this request factory attempts to use OAuth authentication. OAuth authentication requires a user (logged in to the local application) to obtain an "access token" from the remote application. This allows the user (of the local application) to make requests to the remote application on behalf of that user. As part of the OAuth authentication process, the user may be prompted to log in to an account on the remote application.
CredentialsRequiredExceptionis thrown if the user has not yet obtained the required access token. This exception contains a method which returns the authorisation URI through which users can authorise themselves on the remote application (and hence, may require them to log in to that application), to obtain the required access token. You should link the user to this URI so they can be prompted for an access token
Finally, add the
parseResponsemethod we invoked earlier.
- Save and close the file.
Putting it all together, your class should look something like this:
For additional information and TODO's, see the code comments in the file on BitBucket.
Step 6. Build, install and run the plugin
Now start JIRA with the plugin:
- Back at the command line, change to the project home directory.
- Open your browser and open the application started by
atlas-run, for example, by navigating to http://localhost:2990/jira.
- At the login screen, enter the username of
adminand a password of
- Follow the wizard to create a new project.
- Keep this window open while you perform the next steps.
Next configure the Confluence instance against which you'll test your plugin as described below. Notice that these steps include setting up an Application Link and a project link. The steps are not described in detail here. If you're new to Atlassian administration, you should see the JIRA documentation for details on how to accomplish these tasks.
Start the Confluence instance against which you'll test your plugin:
When Confluence finishes starting up, return to the browser window with JIRA opened, and navigate to the administration console.
In the JIRA administration console, click the Applications Links link in the left menu.
Follow the instructions in the wizard to set up a reciprocal Application Link between JIRA and your Confluence instance.
- Return to the Administration page of your newly created project and set up a project link between it and the built-in Demonstration space in Confluence.
- Create a new issue in your JIRA project.
- In the Demonstration space in Confluence, either create a new page or edit an existing one and add the issue key to the page. You can do this in the form of the JIRA issue macro.
- Save the page.
- Back in JIRA, view the issue you created and click the Confluence Space Tab Panel tab. You should see the title of the Confluence page in which you mentioned the issue. If you do not see your Confluence page, try re-indexing Confluence first and then try viewing the issue again.