Atlassian Jira Service Management plugin

This plugin allows you to add a data source to monitor service desks from your Atlassian Jira Service Management 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.

Before you start

Prerequisites

  1. Create a scoped API token
  2. Check the required permissions

Creating an 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 API token types:

  • Standard
  • Scoped

It's highly recommended that you select the Scoped option, as Standard 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 required permissions. You can specify read in the search box to filter to read permissions and then click Scope type to sort the list.
      • 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
    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.

Check the 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:
    Select the type of token to use. See Before you start for more information.
  5. Token:
    Enter the API token generated from the email address in the Creating an API token section.

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

  6. Optional object indexing:
    Optionally, select if you want to import additional Jira objects into SquaredUp. Service Desks, Request Types and Queues are indexed by default. Additional objects may increase indexing time and aren't always necessary. Choose from:
    • Index customers
    • Index organizations

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

  8. 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 data source configurations at any time from Settings > Data Sources.

Next steps

Configurable data streams

The following data streams installed with this plugin have configurable Parameters.

Data stream
Description
Parameters
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:
    • List: 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.

Queues
Gets queues returned by the selected filters.
  1. Result type:
    Select how the query results are returned. Choose from:
    • List: 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 List is selected as the Result type.
Requests
Returns requests for the specified Customers, Organizations, Request Types, and Service Desks.
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 by.
  2. Result type:
    Select how the query results are returned. Choose from:
    • List: 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 List is selected as the Result type.
  4. Use timeframe:
    Select 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.

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket