Jira Cloud

By integrating Jira with DX, you can analyze cycle time metrics, resource allocation, sprint metrics, and initiative progress. Please refer to the API documentation below and our schema explorer to see what data DX imports.

Prerequisites

To connect Jira to DX, you need:

• a Managed account
• a Jira service account and API token
• your sprint and story point field IDs

Setup instructions

Follow the steps below to connect Jira to DX:

Step 1

Create a Jira service account to be used for DX—the service account must have access to the projects that you want to import.

Step 2

Create a Scoped Token

• Begin service account creation via admin.atlassian.com under Directory → Service accounts
• Grant the service account access to the Jira App with the User Role
• Ensure the group that the service account belongs to is granted the “Browse users and groups” global permission in Jira
• When directed, specify the following scopes for the token:
  • Read:
    • read:jira-work
    • read:jira-user
    • read:sprint:jira-software
    • read:project:jira
    • read:user:jira
    • read:board-scope:jira-software
  • Manage:
    • manage:jira-configuration
• Save this token to be used when connecting via DX
• Find your cloud ID to build your base API URL at https://<my-site-id>/_edge/tenant_info
  • This should be show a hash with a single key value pair that looks like {"cloudId":"15ace26c-a7e9-49d6-9e1e-5e90906e946e"}
• Use https://api.atlassian.com/ex/jira/<cloud-id> as the base URL
  • eg. https://api.atlassian.com/ex/jira/15ace26c-a7e9-49d6-9e1e-5e90906e946e
• For the username, use the generated service account email. It should end in serviceaccount.atlassian.com

Step 3 (Optional)

Complete this step if your story point and field IDs are non-standard. To find your sprint and story point field IDs:

• Click the Settings gear in the top right corner of Jira and select “Work Items”
• Find fields in the left hand side bar and select it
• Search for the field you want and select “Add field to screen” using the three dots on the right of the row
• In the end of the URL where you see fieldId=ID (e.g. fieldId=customfield_10020) select and use that ID

Step 4

• Navigate to the connections page in DX and select “+ Connection” in the top right.
• Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.
  • Your username will be an email address and API token will be a long string beginning with ‘ATATT3x’
• Enter your sprint and story point IDs from step 3 into their respective fields if relevant

Step 5 (Optional)

Complete this step if you would like the data connector to pull custom fields. Sprint, story point, parent link, and epic link fields will be pulled automatically.

1. After successfully saving a connection, click ‘Edit Connection’
2. Select the fields you would like to allow list from the Allowlisted custom fields dropdown

Notes

Board Support - DX currently only ingests scrum or simple Jira boards. Kanban boards are not ingested because they do not support sprints, which are the foundation of DX’s sprint-based reporting in Data Cloud (e.g. Sprint Completion, Predictability, and Spillover). If you have multiple board types in the same project, only the sprint-focused ones will appear in DX, and issues in unsupported boards can still be tracked through our issue-based reports.

Deprecated Authentication Alternative: Unscoped Token - To setup a connection, you can also use an unscoped API Token created using the Create API Token option under Manage API Tokens at id.atlassian.com. When using an unscoped token, you must use the <my-id>.atlassian.net version of your base URL (e.g., https://my-company.atlassian.net). We recommend using scoped tokens, but will continue accepting unscoped tokens indefinitely.

API reference

The table below lists the specific API endpoints that are used by DX.

Errors

The table below lists potential error codes when adding a connection in DX.

Troubleshooting

Team filtering doesn’t work

DX matches Jira user emails with DX user emails to map user identities and teams. DX can only import Jira user emails when profile visibility is set to public, which is the default for Managed accounts but not for Unmanaged accounts.

If your Jira workspace is currently an Unmanaged account, please migrate to a Managed account to enable the importing of new user emails. To backfill email addresses for existing users, please contact DX support.

Story points not being populated on Jira issues

DX ingests issue story points by looking at the following fields, in order. Once a valid number value is found, the subsequent look ups are skipped.

1. Jira’s official story point field
2. Custom fields with a name that contains two asterisks
3. Custom fields with a name that contains the case-insensitive substring “story point”

If you are not using Jira’s official story point field, have multiple custom fields with the substring “story point” in their names, or are using a custom field that does not have the substring “story point” in it’s name; please add two asterisks to the name of the field you want DX to ingest.

Example 1:

A customer has a two custom fields that tracks story points. One called “Estimated Story Points” and another called “Actual Story Points”. They would like DX to ingest the “Actual Story Points” field, so they edit the name to include two asterisks, “Actual Story Points**”.

Example 2:

A customer uses a custom field called “Effort” to track their story points. They would like DX to ingest this field, so they edit the name to include two asterisks, “Effort**”.

Curl commands

When connection verification fails

When DX verifies a Jira connection, it checks three key endpoints to ensure proper access. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

curl -u YOUR_EMAIL:YOUR_API_TOKEN -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/api/2/users?startAt=0'

curl -u YOUR_EMAIL:YOUR_API_TOKEN -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/api/2/project/search?expand=description,insight'

curl -u YOUR_EMAIL:YOUR_API_TOKEN -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/api/2/resolution/search'

If any of these commands fail with a 401 Unauthorized error, your API token may be invalid or expired. If they return empty results or a 403 Forbidden error, your service account may not have the required permissions to access these resources.