Last updated Mar 22, 2024

JIRA Developer Documentation : Guide - Building a dashboard item for a JIRA Connect add-on

This guide will help you build a dashboard item for JIRA Connect add-on. You will need to be familiar with building JIRA add-ons on Atlassian Connect to use this guide. If you are building a dashboard item for a JIRA P2 add-on, see this guide instead: Building a dashboard item for JIRA P2 add-on

A dashboard item provides discrete dynamic content that a user can use to customize their dashboard, via the gadget directory. Dashboard items use modern rendering technologies, like AMD, Soy, LESS, etc. Dashboard items can also share web-resources, which improves page load performance by reducing the number of requests and the overall size of data to be transferred on a dashboard load. 

Note, it is not possible to build OpenSocial gadgets on Atlassian Connect. You should build dashboard items instead.

Before you begin

Defining the dashboard item

The Dashboard item page in the Atlassian Connect documentation shows how you should define a dashboard item in your add-on descriptor. 

You can see an example of this in the source for the sample Connect dashboard item that was referenced earlier. If you haven't built a Connect add-on before, here are a few things to take note of:

General development guidelines

We recommend that you read all of the guidelines below before developing a dashboard item. These are high level guidelines, as this guide is intended for experienced add-on developers. If you need help with a specific development issue, try browsing the JIRA development forums.

In this section:

Check out our sample dashboard item | Performance | Testing your dashboard item | Sandboxing

Check out our sample dashboard item

If you haven't seen our sample dashboard item yet, check it out here: https://bitbucket.org/atlassianlabs/atlassian-connect-jira-dashboard-item-example/

You can browse the source, clone it, modify it, and even run it in a JIRA development instance yourself.

Performance

  • Only use server-side rendering for mostly static information -- Anything that might be expensive (e.g. running a JQL query, generating data for a chart, etc) should not be done server-side. Instead, the data should be requested via an AJAX request and then rendered client-side.

Testing your dashboard item

  • Unit testing -- We recommend testing all new code with a JavaScript unit testing framework, like QUnit.

Sandboxing

Dashboard items are sandboxed in Atlassian Connect, as they run in iframes, so you don't need to worry about setting the correct context (e.g. namespacing CSS) as you would with a P2 dashboard item.

Design guidelines

There are no design guidelines specific to dashboard items. We recommend that you consult the Atlassian Design Guidelines, as you should when developing for any Atlassian product. Here are a few topics that may be relevant to your dashboard item:

Rate this page: