Level of experience:
This is a beginner tutorial. This is a good tutorial to try if you have never developed an add-on before.
It should take you approximately half an hour to complete this tutorial.
On this page:
Overview of the tutorial
This tutorial shows you how to write a simple plugin that adds a new menu to JIRA's header. The menu includes two menu items that link to external web pages. In terms of plugins, this is almost as simple as it gets. But it's not without its use. You can use this sort of plugin to add links to JIRA to your websites that are important for your organization, such as your company's intranet or external website.
You can add UI elements to JIRA by adding module definitions to the plugin descriptor. In this tutorial, you'll add the following modules:
- A web section to define the new tab (section) in your JIRA top navigation bar.
- A number of web items to add the links and menu items to the new section.
Your completed plugin will consist of the following components:
- A plugin descriptor to enable the plugin in JIRA.
- The required plugin modules that define the new menu section and menu items.
Your plugin does not need any Java code because the plugin modules provided by the Atlassian Plugin Framework provide all the functionality required for this simple plugin.
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.
- The basics of using and administering JIRA.
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-menu-items-plugin
Step 1. Create the plugin project
In this step, you'll use an
atlas- command to generate stub code for your plugin.
- 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 where you want to put the project home.
Enter the following command to create a plugin skeleton:
- When prompted for the version of JIRA to target, choose 1 for JIRA 5.
As prompted, enter the following information:
- Confirm your entries when prompted.
The SDK generates the initial plugin project files in a directory named
Step 2. Review and tweak the generated stub code
It is 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.xml file. Open your plugin project in Eclipse and follow along in the next sections.
Add plugin metadata to the POM
The POM (Project Object Model definition file) 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.
- Edit the
pom.xmlfile in the root folder of your plugin.
Add your company or organisation name and your website to the
<organization>element (the following code blocks show how it looks in plain text):
- Save the file.
Review the generated plugin descriptor
Your stub code contains a plugin descriptor file
atlassian-plugin.xml. This is an XML file that identifies the plugin to the host application (JIRA) and defines the required plugin functionality.
You should see something like this (comments removed):
Step 3. Start JIRA
Let's start JIRA and see what we've got so far:
- From the command line, change to the directory created by the SDK,
- Enter the SDK command
This starts JIRA and loads your plugin. In the output, look for a line that looks something like this.
[INFO] jira started successfully in 134s at
It tells you that JIRA is done starting up and shows you the JIRA home page address.
- In a browser, open the JIRA home page address indicated in the
- Log in to JIRA using the default username and password combination, admin/admin.
- When prompted for the type of project to create, either create a project or click Cancel. JIRA prompts you to create a new project like this only when starting up a new instance.
- Choose Add-ons from the cog menu at the top right of the page.
- Click Manage Add-ons from the left menu.
- In the User-installed Add-ons list, look for the plugin you created, jira-menu-items. Alternatively, type the name in the filter field to find it quickly.
- Click on the add-on in the list to expand its details view.
The details of your plugin appear:
The plugin worked, but so far it doesn't do much. Let's make it add something to the JIRA UI.
Back in the command window where you started JIRA, enter Control+C to shut down JIRA for now.
Step 4. Add the plugin modules to the plugin descriptor
Add the new section and menu items to your plugin descriptor as follows:
- Open the plugin descriptor for editing:
Add the following web section as a child element to
atlassian-plugin. This defines the top-level section where we will put all our menu items and links:
weightattribute determines the order in which web items appear. Items are displayed top to bottom or left to right in order of ascending weight. The lightest weight is displayed first, the heaviest weights sink to the bottom. The weights for most applications' system sections start from 100, and the weights for the links generally start from 10. The weight is incremented by 10 for each in sequence so that there is ample space to insert your own sections and links.
Add the following web item. This defines the link on the top-level section, with text 'My Company'. We have pointed the link at the company website:
linkIdis not optional and must be the same as the location element of the web-section. It also provides an XML id for the link being generated.
Add another web item, to create a single menu item with text 'Web Site' that links to your company website.
Add another web item, to create a menu item labeled "Documentation" that links to your documentation website.
- Save the file.
atlassian-plugin.xml file should look something like this:
Step 5. Restart JIRA and see your plugin in action
- At the command line from your plugin directory, enter
- After JIRA starts up, log in again.
- Notice the new menu in the header. Clicking on the entries takes you to the URLs you entered.
When you have finished developing and testing your plugin, you can install it into your company's JIRA instance, so that the new menu items are available for other people to use. Your plugin JAR file is at
target\jira-menu-items-1.0.jar. You can install the plugin using the Universal Plugin Manager.