Atlassian Jira plugin

For more information about what this plugin does and the data streams it retrieves, see:

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

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

To add a data source 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 Configure data source page.

This plugin requires you to provide an Atlassian API token to authenticate the data source. If you do not have one already, a Jira admin can generate a new one here https://id.atlassian.com/manage-profile/security/api-tokens.

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

For detailed steps for API token management from Atlassian, see:

https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account.

Required permissions

When you configure the data source, you must provide the User email address of the account that created the token.

The user account you use here only requires read-only access to a project to return work items from that project.

Configuring the data source

Display name:
Enter a name for your data source. This helps you to identify this data source in the list of your data sources.
Domain url:
The domain for the Atlassian instance you wish to use, in the format:
https://your-domain.atlassian.net
User email address:
Enter the email address of the Atlassian account that generated the API token.
API token:
Enter a current API token generated from the email address in the Before you start section.
The same API token can be used for the Jira and Confluence data sources.
Optional: Restrict access to this data source:
You can enable this option if you only want certain users or groups to have access to the data source, or the permission to link it to new workspaces. See data source access control for more information.
Install dashboards:
Select whether you would like to install pre-built dashboards and perspectives with the data source. By default, this is set to on.
Click Test and add to validate the data source configuration. SquaredUp will now attempt to connect to SquaredUp using the provided authentication method.
- 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 any data source configurations at any time from Settings > Data Sources.

Testing

When you select Test and update, SquaredUp will test that the email address and API token are both valid and return data from Jira. If you encounter an error contact [email protected] for assistance.

Next steps

Dashboards

When configuring the Jira data source, you have the option to install the preconfigured dashboards. This is recommended as these dashboards provide a great starting point to understand how you can visualize your data. You can edit the tiles on the preconfigured dashboards, or clone or copy a tile elsewhere and then edit them.

Each dashboard uses dashboard variables, so you should start by selecting the project that you're interested in from the dashboard variable dropdown list.

Project Overview:

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.

Bug Analysis:

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.

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.

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
Users

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.

Data streams standardize data from all the different shapes and formats your tools use into a straightforward tabular format.

While creating a tile you can tweak data streams by grouping or aggregating specific columns.

Depending on the kind of data, SquaredUp will automatically suggest how to visualize the result, for example as a table or line graph.

Data streams can be either global or scoped:

Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

See Data Streams for more information.

The following data streams are installed with this plugin.

Data stream	Description
Releases Overview	The scoped Releases Overview data stream retrieves your Jira projects as objects - which can then be used to view the releases relative to the selected objects. Use the Objects tab to scope the data stream to Projects or Releases by selecting one or more items. You can also toggle the dynamic search and scope based on a key word such as `Alpha`, this will scope the data stream to all results containing `Alpha`. Alternatively, you can add a dashboard variable to the dashboard, and then select that variable under Collection when configuring the tile. The Releases Overview data stream does not use Timeframe, your data will be returned in the preview panel and you can move directly on to shaping the data or saving your tile.

Data stream

Description

Releases Overview

The scoped Releases Overview data stream retrieves your Jira projects as objects - which can then be used to view the releases relative to the selected objects. Use the Objects tab to scope the data stream to Projects or Releases by selecting one or more items. You can also toggle the dynamic search and scope based on a key word such as Alpha, this will scope the data stream to all results containing Alpha.

Alternatively, you can add a dashboard variable to the dashboard, and then select that variable under Collection when configuring the tile.

The Releases Overview data stream does not use Timeframe, your data will be returned in the preview panel and you can move directly on to shaping the data or saving your tile.

Configurable data streams

The following data streams have configurable Parameters.

Data stream	Description	Parameters
Filters	Gets work items returned by the selected filters.	Result type: Select how the query results are returned. Choose from: Full: All matching results are returned. This is the default option. Count: Returns a simple count based on the number of items matching the query. Aggregate: Select a column to aggregate results by by specifying it in the Group by field. Selecting a `Date` type column additionally displays the Bucket by field, allowing you to specify how to group date-based aggregations (for example, by Month). Columns: Specify only the columns you want to return to speed up the query. This field displays when Full is selected as the Result type.
Work Items	Retrieves work items scoped on any combination of your Jira projects, releases, filters, issue types, labels, components and users as objects. A common use is to scope on a filter that you use in Jira. This would then return a matching set of work items.	Advanced: Select the Advanced checkbox to restrict the number of fields returned in your query to improve performance. You can add fields by searching for one field at a time. You must always select the Status field. Use Timeframe: Select the Use Timeframe checkbox to use the tiles timeframe against different Jira fields, such as `Created` or `Resolved`. By default the tile will bring back all work items regardless of the timeframe.
Work Items / Closed	Retrieves closed work items scoped on any combination of your Jira projects, releases ,filters, issue types, labels, components and users as objects. A common use is to scope on a filter that you use in Jira. This would then return a matching set of work items.	Advanced: Select the Advanced checkbox to restrict the number of fields returned in your query to improve performance. You can add fields by searching for one field at a time. You must always select the Status field. Use Timeframe: Select the Use Timeframe checkbox to use the tiles timeframe against different Jira fields, such as `Created` or `Resolved`. By default the tile will bring back all work items regardless of the timeframe.
Work Items / Open	Retrieves open work items scoped on any combination of your Jira projects, releases, filters, issue types, labels, components and users as objects. A common use is to scope on a filter that you use in Jira. This would then return a matching set of work items.	Advanced: Select the Advanced checkbox to restrict the number of fields returned in your query to improve performance. You can add fields by searching for one field at a time. You must always select the Status field. Use Timeframe: Select the Use Timeframe checkbox to use the tiles timeframe against different Jira fields, such as `Created` or `Resolved`. By default the tile will bring back all work items regardless of the timeframe.
Work Items Over Time	This data stream allows you to return the count of work items during a specific time based on a JQL query. It uses the JQL operator DURING and takes the beginning of the tile’s timeframe until the current time. For example, you may want to see how many work items moved from a status of Testing to Closed during the last 7 days. It can also be used to show trends during a sprint period.	JQL query: You must use the operator WASIN as part of your JQL query, typically this replaces the use of = or IN. If the `$DATASET` variable is used, a value must be entered in the $Dataset field. For instance status was in (Open) Period: Select a time period to group the count of data into, by default it is Hourly. $Dataset: Enter a list of values to replace the query `$DATASET` placeholder. For example it could be a list of labels you want to query for. A current technical limitation means that if a Jira issue is switched from one priority to another and the $Dataset field contains both priorities, it will show up multiple times for a given time period.
JQL Query	This global data stream allows you to enter a JQL query in the same way you would in Jira work item navigator.	JQL Query: Enter the JQL you want to use. You can copy and paste the JQL from Jira, to make use of Jira's IntelliSense. Result type: Select how the query results are returned. Choose from: Full: All matching results are returned. This is the default option. Count: Returns a simple count based on the number of items matching the query. Aggregate: Select a column to aggregate results by by specifying it in the Group by field. Selecting a `Date` type column additionally displays the Bucket by field, allowing you to specify how to group date-based aggregations (for example, by Month). Columns: Specify columns to return to improve performance by restricting the number of fields returned in your query. You must always specify the Status field. The JQL Query data stream does not use the Timeframe as the JQL would override it.

Troubleshooting

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 Shaping tab only hides the data after it has been returned.

If you see an error about the data source being throttled and the data set being incomplete then select fewer columns on the Parameters tab, or edit your JQL query to reduce the data returned, see Data set is incomplete.

Was this article helpful?

Have more questions or facing an issue?

Submit a ticket