Tutorial - Adding content to the JIRA View Issue page
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 1 hour to complete this tutorial.
On this page:
Overview of the tutorial
This tutorial shows you how to add content to the View Issue page in JIRA. It demonstrates how to create a plugin that adds a web panel to the page if the issue has a due date. Our web panel displays a colorful indication of when an issue is due (or overdue).
Your completed plugin will consist of the following components:
- A plugin descriptor (XML file) that describes the plugin module to JIRA.
- A Java class (
DueDateIndicator) that calculates the due date for an issue and exposes it as an object context that we can use in JIRA UI templates.
- Resources for displaying the plugin UI. This includes an internationalisation properties file (called
tutorial-jira-add-content-to-view-issue-screen.properties) and a Velocity template (
due-date-indicator.vm) for rendering the web panel plugin module.
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.
- 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:
Step 1. Create the plugin project
In this step, you'll use two
atlas- commands to generate stub code for your plugin and set up the stub code as an Eclipse project. 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 your Eclipse workspace directory.
Enter the following command to create a plugin skeleton:
Choose 1 for JIRA 5 when asked which version of JIRA you want to create the plugin for.
As prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
- Change to the
directory created by the previous step.
Run the following command:
- Start Eclipse.
- Select File > Import.
Eclipse starts the Import wizard.
- Filter for Existing Projects into Workspace (or expand the General folder tree).
- Choose Next and browse to the root directory of your plugin (where the
pom.xmlfile is located).
Your Atlassian plugin folder should appear under Projects.
- Select your plugin and choose Finish.
Eclipse imports your project.
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):
Optionally modify the
nameelement to be something more readable:
This is the name for your plugin that will appear in the JIRA add-on administration page.
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. In your IDE (integrated development environment, such as Eclipse or IDEA) open the descriptor file located in your project under
You should see something like this (comments removed):
Note that some of the information from the POM is transferred to the plugin descriptor using variable names such as
Step 3. Add your plugin modules
Now you will use the plugin module generator (another
atlas- command) to generate the stub code for modules needed by the plugin.
For this tutorial, you will need a web panel plugin module. You'll add this via the
atlas-create-jira-plugin-module command. The command can also generate an i18n properties file for your JIRA UI text, which we'll add as well.
- Open a command window and go to the plugin root folder (where the
- Choose the option labeled Web Panel.
Supply the following information as prompted:
Enter Plugin Module Name
See Right Side of the 'View Issue' Page Location for more information.
- At the Show Advanced Setup prompt, enter 'y' (for 'Yes').
For the next five options, you can accept the default by pressing enter. For reference, the values are:
The DueDateIndicator Plugin
i18n Name Key
i18n Description Key
When prompted with Add Resource, choose 'y' and then enter the following information for the resource:
Enter Resource Name
Enter Resource Type
Enter Location (path to resource file)
- At the Add Resource Parameter prompt, enter 'N' (for 'No').
- For Add Resource, choose 'N' (for 'No').
- For Add Velocity Context Provider, choose 'y' and enter the following information for the context provider:
- Add Fully Qualified Context Provider Class:
- Add Fully Qualified Context Provider Class:
- For Add Conditions, choose 'N'.
- For Add Another Plugin Module, choose 'N'.
The SDK finishes generating your plugin module and returns you to the command prompt.
Step 4. Add a panel title
The SDK gave us most of what we need for the plugin configuration, but we'll need to add a title for our panel manually, as follows:
- Open your plugin module descriptor file,
atlassian-plugin.xml, for editing. It's in the src/main/resources directory.
Add the following
labelelement as a child of your
keyparameter value represents a key in your i18n properties file.
Remove the component declaration generated by the SDK in the plugin descriptor, since we'll be removing the file later.
Your plugin descriptor file should look something like this (comments removed for brevity):
- Save and close the file.
- Now open your i18n properties file
tutorial-jira-add-content-to-view-issue-screen.propertiesfor editing. It is also located in the
Specify the value of the
due-date-indicator.titlekey you just defined in your plugin descriptor in your i18n properties file by adding this
In the JIRA View Issue page, this value will appear as the title of your new web panel. Your i18n properties file should look like this:
Save and close the file.
Step 5. Write your Java class
So far you've created the framework for your web panel plugin module. Next write some Java code that makes the web panel do something interesting. Namely it:
- Retrieves the due date associated with the current issue
- Calculates the difference between the current data and the due date
We'll start with a little refactoring of the code that the SDK gave us:
- In the
- Remove the
MyPluginComponentImpl.javafile also found in the same directory.
- Remove the test files that the SDK gave us.
Testing is important of course, but outside the scope of this tutorial. You can remove the entire directory
DueDateIndicator.javafile as just renamed, and replace its contents with:
Notice that it now extends the abstract class AbstractJiraContextProvider and implements the class'
But that's just the beginning. The class will need to retrieve the current time as the number of milliseconds which have passed since midnight, 1st of January 1, 1970 UTC), by calling
java.lang.System.currentTimeMillis(). We will use this value to calculate the difference between the current time and the due date time of the current issue (using the
getTime()method against the due date's
Timestamp), which is also retrieved as the number of milliseconds that have passed since midnight, 1st of January 1, 1970 UTC.
Add a constant to your class named
MILLIS_IN_DAY, which gets the number of milliseconds in a day:
We'll use that in subsequent calculations.
getContextMapmethod we implemented needs to return a
Mapobject with a key and value that represents the number of days difference between the due date and the current date, so that it can be used by other parts of the module. To do this, initialise a new
Mapobject within the method (called
contextMap) to store this key and value.
Also within your
getContextMapmethod, initialise a new JIRA
currentIssueto store the current JIRA issue as an object through which you can access its due date as a Java
Timestamp, using the
Check to see if the current issue's due date has been set and if so begin calculating the number of days difference between the current date and due date. Since the time of the
Timestampwill be accessed using the
getTime()method which, like the
currentTimeMillis()method described above, returns the time as the number of milliseconds which have passed since midnight, 1st of January 1, 1970 UTC, we need to convert these to days by dividing each of these values by the
MILLIS_IN_DAYconstant and casting the values to integers:
Now that we have the number of days for the due date time (
dueDateTimeInDays) and current date time (
currentTimeInDays) both from a common reference point, we need to calculate the difference between these values, adding one day for the final calculation. Associate this value (
daysAwayFromDueDateCalc) with the keyword
contextMap). Add the following lines of code within the
DueDateIndicatorclass should return the
Mapobject back to your web panel plugin module to make it available to other resources in your plugin (i.e., our Velocity Template resource, which you define in the next step).
- Save the file.
The complete code for
DueDateIndicator should look like this:
Step 6. Write your Velocity template
So far, you've written a Java class that retrieves the difference in days between the current issue's due date and the current date. Now you will write a Velocity template to present this information in HTML format.
Your web panel plugin module already contains the following context provider:
This is your
DueDateIndicator Java class. As already coded, this class returns a
Map object with the property
daysAwayFromDueDate whose value is the number of days difference between the current issue's due date and the current date. The
daysAwayFromDueDate property is available to other resources in the plugin module, such as the Velocity template resource you already defined in the plugin descriptor using the SDK,
due-date-indicator.vm. However, while we declared it in the descriptor, we still need to add the file, as follows:
- Change to the
src/main/resourcesdirectory and create a new file named
Add the following if/then/else statement to the
This provides a colorful visual indicator of when the current issue is due. Notice that we've defined a new variable,
$overdueDays. Since the
daysAwayFromDueDateproperty returned by our Java class contains a negative value whenever an issue is overdue (which is what our if/then/else statement series relies upon), we've created this new variable to present the value of
daysAwayFromDueDateas a positive number.
Also note that is a deep-red orange color.
- Save the file.
Step 7. Build, install and run the plugin
Now you're ready to try out your plugin. Start JIRA as follows:
- In a new console, navigate to the project root directory
Enter the following Atlassian Plugin SDK command:
When JIRA finishes starting up, use a browser to open the JIRA address indicated in the console printout, such as
Log in using the default username and password for a dev mode instance, admin/admin.
If you're using a recent version of JIRA, you'll see a wizard for creating a new JIRA project upon successful login. Follow the steps to create one.
Now create a new issue. In your issue, add a due date and save.
- Navigate to your new issue, and voila! You should see your Due Date Indicator web panel: