Tutorial - Adding a dropdown to an agile board

In this tutorial, you will add a new dropdown to your JIRA Software add-on (Connect or P2). This dropdown will appear in the top right corner of an Agile board, next to the Board dropdown. This is done via a plugin point (added in JIRA Agile 6.6.50). This tutorial provides separate instructions, depending on whether you are building a Connect add-on or a P2 add-on.

To add this new dropdown, you will be creating a new web-section. The location of the web-section will be jira.agile.board.tools.  You will then add a web-item or web-panel inside the web-section. That's it! See the screenshot below to see what it looks like.

Screenshot: Example web-section with a web-panel in jira.agile.board.tools.

About these Instructions

You can use any supported combination of OS and IDE to create this plugin. These instructions were written using Sublime Text editor on Mac OS X. If you are using a different IDE and/or OS, you should use the equivalent operations for your specific environment.

This tutorial was last tested with JIRA 6.5-OD-07 and JIRA Agile 6.7.6.

On this page:

Instructions for Connect add-ons

Step 1. Create a web-section in your atlassian-connect.json

Your web-section should look similar to this example:

"webSections": [
        "key": "board-links",
        "location": "jira.agile.board.tools",
        "weight": 10,
        "name": {
          "value": "My Extension"

Step 2. Add a web-panel with board context parameters

Your web-panel should look similar to this example:

"webPanels": [
        "key": "my-web-panel",
        "url": "web-panel?id={board.id}&mode={board.screen}",
        "name": {
          "value": "My Web Panel"
        "location": "board-links",
        "layout": {
          "width": "100px",
          "height": "100px"

Step 3. Add server side code to render the web panel

The server-side code required to render the web-panel is shown below. This code is for Node.js with the Express framework, but you can use a different technology stack if you wish.


app.get('/web-panel', function(req,res){
	res.render("webpanel", {id : req.query['id'], mode : req.query['mode'] });


<!DOCTYPE html>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta name="ap-local-base-url" content="http://localhost:2990">
    <link rel="stylesheet" type="text/css" href="http://localhost:2990/jira/atlassian-connect/all.css">
    <script src="http://localhost:2990/jira/atlassian-connect/all-debug.js" type="text/javascript"></script>
    <p id="custom-message">We are viewing board {{id}} in {{mode}} mode.</p>


(tick) Congratulations! You've just added a dropdown to an Agile board in your Connect add-on.

Instructions for P2 add-ons

Step 1. Create a web-section in your plugin.xml

Your web-section should look similar to this example:

<web-section location="jira.agile.board.tools" key="my.custom-board-tool-section" weight="10"> 
	<label key="gh.board.tools.reference.button"/> 
	<condition class="com.atlassian.greenhopper.client.web.condition.BoardModeCondition"> 
		<param name="mode">work</param> 

Step 2. Add a web panel, which will be placed in your new web-section

Your web-panel should look similar to this example:

<web-panel key="board-tools-webpanel" location="my.custom-board-tool-section" weight="100">
	<resource name="view" type="velocity" location="templates/board-tools-webpanel.vm" />
	<context-provider class="com.atlassian.jira.plugin.webfragment.contextproviders.DefaultVelocityContextProvider" />

Step 3. Create a velocity template that will be rendered inside the web-panel

Three context parameters are available in the template. These are $board.id, $board.type, $board.screen

The mode parameter is an enumeration with the following possible values:

  • plan, which is tied to the Backlog page

  • work, which is tied to Active Sprints page

  • report, which is tied to the Reports page

<div> We are viewing a board with id $board.id in $board.screen mode. </div>

Context parameters can also be used in web-item links, as shown below:

<web-item section="my.custom-board-tool-section" key="my-custom-web-item" weight="10">
	<label key="gh.rapid.operations.configure"/>

(Optional) Add conditions

You can add a condition so that the web-section is only displayed if the board is in a specific mode. The following code shows an example where the web-section only displays on the Active Sprints/Kanban board. See the screenshot below for an example of this.

Note, the possible values for the mode parameter are planwork and report.

<condition class="com.atlassian.greenhopper.client.web.condition.BoardModeCondition">
	<param name="mode">work</param>

Screenshot: Active sprints view with a dropdown provided by a plugin



(tick)   Congratulations! You've just added a dropdown to an Agile board in your Connect add-on.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport