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, if you connect with an API token
• your sprint and story point field IDs

Setup instructions

You can connect Jira to DX with OAuth or with an API token.

OAuth

1. Navigate to the connections page in DX and select + Connection in the top right.
2. Select Jira Cloud and enter a name for the connection.
3. Select Connect with Jira and follow the flow to authorize the connection.

Note: OAuth is not yet available for DX accounts on a custom domain or a dedicated instance. Use an API token instead.

Note: OAuth connections do not support multiple credentials. Each OAuth connection uses a single authorization.

API token

Follow the steps below to connect Jira to DX with an API token:

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.

• 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
    • read:issue-details:jira
    • read:priority:jira
    • read:cmdb-object:jira (only required if you allowlist Assets/CMDB object custom fields - without this scope those fields are skipped and the connection still works)
• 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/ (trailing slash required)
• For the username, use the generated service account email. It should end in serviceaccount.atlassian.com

Step 2 (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 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 if relevant

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

Notes

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.

Webhooks

DX supports Jira webhooks ingestion to sync issue, sprint, board, and worklog data in real-time. This is recommended in order to ensure real-time data accuracy in DX.

Webhooks keep this data current between scheduled imports. Anything a webhook payload does not carry—custom field values, issue links, fix versions, and story points—continues to come from the scheduled import, so webhooks complement it rather than replace it.

To enable webhook ingestion, follow the steps below:

1. Go to Settings > System > WebHooks > Create a WebHook
2. For URL, enter https://yourinstance.getdx.net/webhooks/jira with your unique subdomain
3. Enter your webhooks secret from DX—this can be found and copied in the Connections admin page. A webhook registered without a secret is rejected, because Jira only signs the request when one is set.
4. Under Issue related events, enable the following:
   • Issue: created, updated, deleted
   • Worklog: created, updated
5. Under Jira Software related events, enable the following:
   • Sprint: created, updated, started, closed
   • Board: created, updated, configuration changed
6. (Recommended) Add a JQL filter limiting the webhook to the projects you have allowlisted in DX. Left empty, Jira sends events for every issue in every project.
7. Click Create.

Sprint deleted, board deleted, and worklog deleted are not processed from webhooks—those payloads omit the field DX uses to identify which Jira site sent them. There is no need to enable them; deletions are reconciled by the scheduled import instead.

Webhooks for a project DX does not sync—one that is not allowlisted, or that the connection has lost access to—are acknowledged and discarded, so the scheduled import stays the source of truth for what is in scope.

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'

curl -u YOUR_EMAIL:YOUR_API_TOKEN -H 'Accept: application/json' 'YOUR_JIRA_URL/rest/agile/1.0/board/BOARD_ID/issue'

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.

Data Cloud API

Once the initial connection is created successfully, Jira Cloud credentials can be managed via the Data Cloud API.

• credentials.create
• credentials.update
• credentials.info
• credentials.list
• credentials.delete

Credential fields

{
  "id": 456,
  "settings": {
    "jira_user": "dx-automation@myfakecompany.serviceaccount.atlassian.net"
  },
  "secrets": {
    "api_token": "ATATT3xFakeExampleToken000000000000000123abc="
  }
}