Tutorial - Adding a board configuration page

In this tutorial, you will build a board configuration page for your JIRA Software add-on (Connect or P2). We won't go into the details of adding settings to the page, but this tutorial will provide a good starting point if you want your add-on to have separate configurations per board.

To create this board configuration page, you'll be creating a new web panel located in jira.agile.board.configuration, then adding code to render the web panel. That's it! This is what it will look like:

 

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 Software 7.1.0-OD-05.

Instructions for Connect add-ons

Step 1. Add a web panel with board context parameters

To create a board configuration page, create a web panel with the label and location set to jira.agile.board.tools. Your web panel should look similar to this example:

"webPanels": [
      {
        "key": "my-configuration-page",
        "url": "configuration?id={board.id}&type={board.type}",
        "name": {
          "value": "My Configuration Page"
        },
        "location": "jira.agile.board.configuration",
        "weight": 1
      }
    ]

Step 2. Add 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.

Note, two context parameters are available in the template for you to use. These are id (for board Id) and type (for board type), which you can see in the example template below.

Route:

app.get('/configuration', function(req,res){
	res.render("configuration", {id : req.query['id'], type : req.query['type'] });
});

Template:

<!DOCTYPE html>
<html>
  <head>
    <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>
  </head>
  <body>
    <p id="custom-message">My first config page for board: {{id}} with type: {{type}}.</p>
  </body>
</html>

Congratulations! You've just built a board configuration page for your JIRA Software Connect add-on.

Instructions for P2 add-ons

Step 1. Add a web panel with board context parameters

To create a board configuration page, create a web panel with the label and location set to jira.agile.board.tools. Your web panel should look similar to this example:

<web-panel key="my-configuration-page" location="jira.agile.board.configuration" weight="1">
    <label key="my.configuration.page.label">My Configuration Page</label>
    <resource type="soy" name="view" location=":soy/My.addOn.tpl.board.config.myConfigurationPage" />
</web-panel>

Step 2. Add code to render the web panel

The following example shows how to render the web panel using soy templates. You could use velocity templates instead, if you wish.

Note, two context parameters are available in the template for you to use. These are $board.id and $board.type, which you can see in the example below.

{namespace My.addOn.tpl.board.config}

/**
    Custom configuration page.
    @param board
*/
{template .myConfigurationPage}
    My first config page for board: {$board.id} with type: {$board.type}.
{/template}

Congratulations! You've just built a board configuration page for your JIRA Software P2 add-on.

Tips

  • If you are looking for somewhere to store configuration information, make use of the board properties.
  • Your add-on can define custom project or global permissions. This may be useful if you want to limit access to your add-on's board configuration page.
Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport