Jira Data Center

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 Jira service account
• allowlist DX IP addresses if your Jira instance is behind a firewall or has IP restrictions
• your sprint and story point field IDs

Setup instructions

Follow the steps below to connect Jira to DX:

Step 1

Create a dedicated Jira service account for DX.

1. Create the account

   • Create a standard Jira user (e.g., dx-service-account@yourcompany.com).
   • Assign the account the necessary application access (e.g., Jira Software or Jira Core) so it can log in and use Jira.
   • Do not use an anonymous or guest account — the account must authenticate.

2. Grant project-level permissions

   • Add the account to each project you want to import from.
   • At a minimum, grant the Browse Projects permission in each project so it can view issues.

3. Enable POST access for searches

   • We use the POST /rest/api/2/search endpoint (as documented in the Jira Data Center REST API reference) to retrieve Jira issue data.
   • The service account must be able to authenticate and send POST requests to this endpoint.

Refer to Atlassian’s Jira Data Center documentation for more details on managing project role memberships.

Step 2

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 3

• 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 2 into their respective fields

Step 4 (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

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

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 Data Center connection, it checks two 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_USERNAME:YOUR_PASSWORD -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/api/2/project?maxResults=5'

curl -u YOUR_USERNAME:YOUR_PASSWORD -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/api/2/resolution'

curl -X POST -u YOUR_USERNAME:YOUR_PASSWORD -H 'Content-Type: application/json' -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/api/2/search' -d '{"jql": "project is not EMPTY", "maxResults": 1}'

If any of these commands fail with a 401 Unauthorized error, your credentials may be invalid. If they return empty results or a 403 Forbidden error, your service account may not have the required permissions to access these resources. The POST search test is particularly important as DX relies on this endpoint for data extraction.