View all connectors

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 (likely something like 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

API reference

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

Endpoint Documentation
/rest/api/2/project Link
/rest/api/2/project/{projectIdOrKey} Link
/rest/agile/1.0/board Link
/agile/1.0/board/{boardId}/sprint Link
/rest/api/2/priority Link
/rest/api/2/universal_avatar/type/{type}/owner/{ownerId} Link
/rest/api/2/resolution Link
/rest/api/2/status Link
/rest/api/2/field Link
/rest/api/2/group/{groupname}?includeInactiveUsers=&startAt= Link
/rest/api/2/issue/{issueIdOrKey} Link
/rest/api/2/groups/picker Link
/rest/api/2/search Link
/rest/api/2/issuetype Link

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

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