Atlassian Jira plugin

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

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

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.

Before you start

You will need a Jira API token. 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.

Detailed steps for API token management from Atlassian:

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

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

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.
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 Sample Dashboards:
Select whether you would like to install sample dashboards 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. If this process fails, see Testing and troubleshooting for assistance with the corresponding errors.

Testing and troubleshooting

When you select Test and update, SquaredUp will test that the email address and API token are both valid and return data from Jira.

The following errors or warnings may be displayed while using the data source. If you encounter an error, refer to the guidance below or contact [email protected] for assistance.

When configuring the Azure DevOps data source, you have the option to Install sample dashboards. This is recommended as these dashboards provide a great starting point to understand how you can visualise your data. The following dashboards are included with the Jira data source:

Project summary:

This dashboard is designed to display high level project metrics that will give you insight across your Jira instance. Active releases and Release completion progress use the Release Overview data stream, you can fine tune the information displayed by editing the tile and selecting the projects you are most interested in under the Objects tab.

The remaining tiles return data on issues across all projects by default. These can be edited as described above or you can change the timeframe at the top of the dashboard to a different window of time.

Lead time for closing features is a tile that calculates the average time it takes a Jira story to be resolved for all features closed within the current timeframe. This is a commonly used DORA metric for helping to show the efficiency of a team or department.

Defect ratio is a tile that calculates the ratio (0 – 1.0) of bugs fixed vs the total number of issues closed. This is a metric used to help show the impact of code quality on a project, the higher the number the more disruption there is in releasing new features. The tile makes use of our SQL analytics feature to do the calculation. You can fine tune this tile by changing the JQL in the Parameters tab of dataset1.

Bug analysis:

This dashboard provides several different ways of analysing 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. It can be tailored to suit your needs by editing the JQL in the Parameters tab to limit it to a specific project, priority or severity of bug.

Both dataset1 and dataset2 will need to be updated.

Summary 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 assigned to return a green, amber, red or grey health dot.

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
Issue Type
Users

Data streams

The following data streams are installed with this plugin.

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.

Data stream	Description
Issues	The Issues data stream retrieves issues 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 issues. The following parameters can be configured: 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 issues regardless of the timeframe.
Issues / Closed	The Issues closed data stream retrieves closed issues 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 issues. The following parameters can be configured: 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 issues regardless of the timeframe.
Issues / Open	The Issues open data stream retrieves open issues 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 issues. The following parameters can be configured: 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 issues regardless of the timeframe.
Issues Over Time	This data stream allows you to return the count of issues 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 issues 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. The following parameters can be configured: 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 issue navigator. The following parameters can be configured: JQL Query: Enter the JQL you want to use, we recommend copy and pasting the JQL from Jira, to make use of their IntelliSense. Advanced: Select the Advanced check box 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. NB: The JQL Query data stream does not use the Timeframe as the JQL would override it.
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. You can scope the data stream to Projects or Releases by selecting one or more items via the checkboxes. 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`. 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.

Was this article helpful?

Have more questions or facing an issue?

Submit a ticket