Atlassian Jira plugin

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

Atlassian Jira

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

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

Adding a 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.

Loom video thumbnail

Before you start

Creating a scoped API token

This plugin requires you to provide an Atlassian API token to authenticate the data source. When configuring the data source, you're given the choice between the following token types:

  • Token
  • Scoped token

It's highly recommended that you use a Scoped token, as unscoped tokens are planned to be deprecated by Atlassian. And importantly, scoped tokens provide a more granular access control to enforce least privileged access.

How to create a token

If you do not have one already, a Jira admin can do the following to generate one:

  1. Navigate to https://id.atlassian.com/manage-profile/security/api-tokens.
  2. Click Create API token with scopes.
  3. On the Name and expiry tab, complete the following:
    1. Name:
      Enter a name to identify 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 app tab, complete the following:
    1. Select API token app:
      Select Jira.
    2. Click Next.
  5. On the Select scopes tab, do the following:
    1. Select the check box next to each of the following permissions. You can specify read in the search box to filter to read permissions and then click Scope type to sort the list:
      • read:account
      • read:jira-user
      • read:jira-work
      • read:me
      • read:servicedesk-request
    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.

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

  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. User email address:
    Enter the email address of the Atlassian account that generated the API token.
  4. 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.

  5. (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.

  6. 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.

  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 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
Activity Feed
Get activity feed entries for selected project(s). Activities include events such as updating a status or making a comment etc.
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 installed with this plugin have configurable Parameters.

Data stream
Description
Parameters
Filters
Gets work items returned by the selected filters.
  1. 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).
  2. 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
Returns work items for the specified Jira projects, releases, filters, issue types, labels, components and users.
This is a "query builder" data stream where you can specify a work item Status to filter by and the Columns to return on the Parameters tab.
For example, selecting a project and two users as objects this returns any issue relating to either user in the selected project - similar to the query project = <project> AND user IN (<user1>,<user2>).
  1. Status:
    Select a status to filter work items by.
  2. 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).
  3. 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.
  4. Use Timeframe:
    Select the Use Timeframe checkbox to use the tile timeframe to return work items evaluated against the value selected from the Timeframe column field. For example, you can return work items that are Created or Resolved within the tile's timeframe period. If not selected, the tile brings 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.
  1. 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)
  2. Period:
    Select a time period to group the count of data into, by default it is Hourly.
  3. $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.
  1. 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.
  2. 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).
  3. 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