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

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.

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. Atlassian plan to deprecate Standard tokens.

If your user does not have one already, the user can create a scoped API token using these steps:

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
Click Create API token with scopes.
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.
On the Select the app tab, complete the following:
1. Select Jira.
2. Click Next.
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.
On the Create token tab, do the following:
1. Review that the token details and scopes are correct.
2. Click Create token.
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

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:
Select the type of token to use. See Before you start for more information.
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.
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
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.
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.

Testing and troubleshooting

When you select Test and Add SquaredUp will test that the email address and API token are both valid and return data from Jira. If you get an error for a newly created API token, wait a couple of minutes and then click Rerun tests, as it takes a few minutes for the API token to be created. If you still encounter an error contact our support team in-app or via SquaredUp Support

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.