By integrating Jira with DX, you can analyze issues, resource allocation, sprint metrics, cycle times, and initiative progress. Please visit 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

Setup instructions

Follow the steps below to connect Jira to DX.

Step 1

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

Step 2

Create an API token from the Account Security section and copy your token into your notes to use it in the next step.

Step 3

Navigate to the new connection form in DX.
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'

API Reference

Here is a list of the endpoints we reference while importing data from Jira

Endpoint URL	Documentation Link	Permissions Needed
/rest/api/2/search	Search Issues	Browse Issues
/rest/api/2/issuetype/project	Get Issue Types for Project	Project Administration
/rest/api/2/universal-avatar/view/type/{type}/owner/{entityId}	View Avatar	View Project or User
/rest/api/2/project/search	Search Projects	Browse Projects
/rest/api/2/resolution/search	Search Resolutions	Administer JIRA
/rest/api/2/priority/search	Search Priorities	Administer JIRA
/rest/api/2/label	Get Label	Browse Issues
/rest/api/2/field	Get Fields	Browse Issues
/rest/api/2/users	Get Users	Administer JIRA or Manage Users
/rest/api/2/issue/{issueIdOrKey}/changelog	Get Issue Changelog	Browse Issues

Errors

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

Error	Description
`invalid_credentials`	Your API credentials entered are not valid.
`invalid_permissions`	Your API token does not have the permissions required by DX.
`no_resources`	Your service account does not have access to any projects or repositories.

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.

Managing access to Jira projects

Your service account created in Step 1 can be granted or revoked access to projects to control what is imported into DX.

Story points are 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.

Jira's official story point field
Custom fields with a name that contains two asterisks
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**".