Atlassian Jira plugin

Monitor the Projects, Releases and Work Items from your Jira Software environment.

Click the following link for additional content such as blogs, videos, use cases, and more:

Atlassian Jira

Only the Jira Cloud offering is supported by this data source.

Adding a data source

To add a data source, open the relevant workspace and then click on the + next to Data Sources on the left-hand menu in SquaredUp. Search for the data source and click on it to open the Add data source page. Adding from the data sources page

Before you start

Prerequisites

1. Check the required permissions
2. Create a scoped API token
3. Configure the data source in SquaredUp

Check the required permissions

You will need the email address of a user and an Atlassian API token created by that user. The user account only needs read-only access to a project to return work items from that project.

Creating an API token

It is highly recommended that you select the Scoped API token, as this is more secure, using granular access control to enforce least privileged access. See Atlassian: Manage API tokens for your Atlassian account

It is recommended to generate a specific API token for your SquaredUp instance, so if you ever need to revoke it you will not impact any other applications.

The user can create a scoped API token using these steps:

1. Navigate to https://id.atlassian.com/manage-profile/security/api-tokens
   or from the user's profile: Account Settings > Security > Create and manage API tokens
2. Click Create API token with scopes.
   

3. On the Name and expiry tab, complete the following:
   1. Name:
      Enter a name, usually related to the application that will use the token, for example, SquaredUp.
   2. Expires on:
      Specify the date of the token expiry. This can be a maximum of one year ahead. Once the token expires a new one will need to be generated and provided in SquaredUp for the plugin to function.
   3. Click Next.
4. On the Select the app tab, complete the following:
   1. Select the Atlassian product you need access to, for example, Jira.
   2. Click Next.
5. On the Select scopes tab, do the following:
   1. Select the check box next to each of the required permissions. You can specify read in the search box to filter to read permissions and then click Scope type to sort the list.
      • For example, select the following:
        • read:account
        • read:jira-user
        • read:jira-work
        • read:me
        • read:servicedesk-request
          • If read:servicedesk-request is not available, select the following additional options:
            • read:user:jira
            • read:servicedesk.organization:jira-service-management
            • read:servicedesk.customer:jira-service-management
            • read:servicedesk:jira-service-management
            • read:requesttype:jira-service-management
            • read:customer:jira-service-management
   2. Click Next.
6. On the Create token tab, do the following:
   1. Review that the token details and scopes are correct.
      

   2. Click Create token.
7. On the Copy API token page, do the following:
   1. Copy the API Token that is displayed and keep it somewhere safe. You will not be able to see the token again and if lost you will need to generate a new one.
   2. Click Close. You are returned to the API tokens page and the token is added to the list.

Configuring the data source

1. Display name:
   Enter a name for your data source. This helps you to identify this data source in the list of your data sources.

2. Domain URL:
   The domain for the Atlassian instance you wish to use, in the format:
   https://your-domain.atlassian.net
3. Authentication:
   Select how to authenticate the connection to the data source. Choose from:
   • Sign-in button:
     Authenticate using SSO (single sign-on). Click the Sign in with Atlassian button to sign in with your user credentials.
     You are redirected to an authentication window where you must confirm permission access. If you have access to multiple tenants you are asked to select a specific one to grant access to.
     Click Accept to confirm the authorization and you are returned to the plugin configuration page.
   • Standard API token:
     Use a standard API token. See Before you start for more information.
   • Scoped API token:
     Use a scoped API token. See Before you start for more information.
4. If you are authenticating using a token, complete the following:
   1. User email address:
      Enter the email address of the Atlassian account that generated the API token.
   2. Token:
      Enter the API token generated from the email address in the Creating an API token section.
      Note

      If you selected the Standard option, the same API token can be used for the Jira Service Management and Confluence data sources.

5. Optional object indexing:
   Optionally, select if you want to import additional Jira objects into SquaredUp. Projects and Filters are indexed by default. Additional objects may increase indexing time and aren't always necessary. Choose from:
   • Index components
   • Index labels
   • Index versions

6. Restrict access to this data source:
   Optionally, enable this toggle if you only want certain users/groups to have access to the data source, or those with the permission to link it to new workspaces. See data source access control for more information.

7. Click Test and add to validate the data source configuration. SquaredUp will now attempt to connect to SquaredUp using the provided authentication method.

   Testing outcomes

   • Testing passed – a success message will be displayed and then the configuration will be saved.
   • Testing passed with warnings – warnings will be listed and potential fixes suggested. You can still use the data source with warnings. Select Save with warnings if you believe that you can still use the data source as required with the warnings listed. Alternatively, address the issues listed and then select Rerun tests to validate the data source configuration again. If the validation now passes, click Save.
   • Testing Failed – errors will be listed and potential fixes suggested. You cannot use the data source with errors. You are able to select Save with errors if you believe that a system outside of SquaredUp is causing the error that you need to fix. Alternatively, address the issues listed and then select Rerun tests to validate the data source configuration again. If the validation now passes, click Save.

   You can edit data source configurations at any time from Settings > Data Sources.

Testing and troubleshooting

If you encounter an error refer to the guidance or contact our support team in-app or via SquaredUp Support

For errors on dashboard tiles see Troubleshooting tiles.

Why is my data slow to load?

To prevent the tiles being slow to load you should limit the amount of data returned. The Parameters tab allows you to select the columns you need, so only these are returned. Using filters on the Filter | Group | Sort tab only hides the data after it has been returned.

Next steps

Dashboards

A number of pre-built dashboards are installed for this plugin. These dashboards can be found from the left-hand menu by clicking on your data source name under the heading Data Sources. You can use Explore data on each tile, or click Copy dashboard to copy it to the Dashboards section of your workspace where it can be edited to adapt it for your own use. Some dashboards use dashboard variables, so you should start by selecting the object that you're interested in from the dashboard variable dropdown list.

Organization Overview: This gives you a high-level view of activity across your Jira projects.

Project > KPI:

This dashboard is designed to display high level project metrics that will give you insight across your selected project, such as Work Items Closed in the last 7 days and In Progress by Assignee.

Project > Bugs:

This dashboard provides several different ways of analyzing the bugs in your projects. The data shown in these tiles can be adjusted by changing the timeframe at the top of the dashboard to a different window of time or by editing the individual tile and adjusting the JQL that is in the Parameters tab.

The value {{timeframe.startTime}} in the JQL is how the tile knows to use the timeframe at the top of the dashboard, however any date value that Jira would expect can be used instead. For example, currently the tile contains the following JQL:

type in (bug) and created > "{{timeframe.startTime}}"

but could be updated to:

type in (bug) and created > startofday(-30)

Mean time to close calculates the average time it takes for a high priority bug to be closed. By editing the JQL and setting the priority to your highest priority, that you use for incidents or outages, then you can create the DORA metric for MTTR (mean time to recover).

Bug Backlog Trend provides a line graph that shows the daily increase or decrease of open bugs. This trend is helpful in showing whether your overall count of bugs is increasing.

Priority of New Bugs is a simple table of newly raised bugs ordered by priority. It makes use of the Columns tab to create a column of type State, this means specific values can be mapped to return a green, amber, red or grey health dot.

Project > Releases:

Active releases and Release Completion Progress use the Release Overview data stream. They are configured to use the project chosen using the dashboard variable dropdown.

Filter > Stats:

Use the Dashboard variable dropdown to select from the Jira Filters you have access to, to see an overview.

Filter > Work Items:

Use the Dashboard variable dropdown to select from the Jira Filters you have access to, to see an list of work items.

Objects Indexed

SquaredUp indexes objects it finds in your Jira instance during import. These objects are used to build dashboards and are visible when searching across SquaredUp. Drilling down into an object will display the available data streams and properties. Below are the objects types imported:

• Project
• Release
• Component
• Label
• Filter
• Work Item Type

Data streams

You can use these data streams to create new tiles to show data, or if there are preconfigured dashboards installed you can copy or edit those.

The following data streams are installed with this plugin.

Was this article helpful?