Introduction

To enable the Jira Cloud connector, you need a service account along with three pieces of information: a Jira site URL, Jira username, and Jira API token. Note that a Managed Account is required to connect DX Data Cloud.

See the schema reference for Jira Cloud >

Steps to connect

Step 1 must be completed by a Jira admin.

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. The more granular API permissions or scopes to configure are found in the API Reference table below.

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 Data Cloud > Connections screen within DX, then add a connection using your credentials generated in the previous steps.

ℹ️ 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	Get Users	Administer JIRA or Manage Users
/rest/api/2/issue/{issueIdOrKey}/changelog	Get Issue Changelog	Browse Issues

Errors

This table lists error codes that you may encounter 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**".