Skip to content

Connecting to JIRA#

First Steps with JIRA#

Set up an account with JIRA.

Your Atlassian account is your online Atlassian identity that exists independently of the Atlassian products you use. The account includes attributes like your email address and display name.

Cost

There are both free and paid options for this API.

Contact JIRA's sales team to get a quote about a product or service.

Rate Limits

Rate Limits apply to this API and will limit the number of requests per minute. JIRA's documentation contains specific details.

How to Connect DataDistillr to JIRA#

To set up a data source connection for JIRA, you will need to have:

  • A unique name for your data source connection to be used in queries
  • The domain of your Atlassian account
  • The email associated with your Atlassian account
  • The API Key generated through your Atlassian account

Data Source Form#

To locate the JIRA form, follow the steps in Connecting Your Data to DataDistillr. When you get to the window to choose the data source type, select API as shown below.

Data Source Selection

On the API screen, select JIRA from the list of API forms.

List of APIs

The following form will appear. Instructions are below on how to find the information required to fill each field on the JIRA API form.

Once you have filled out all the fields, press the green 'Save' button, and your API will be connected!

JIRA Form

Name#

Enter any name that will help you recognize this data source from within your query window.

Acceptable Characters Include

  • lowercase alphanumeric characters
  • underscores

Domain#

Domain refers to the URL associated with your JIRA instance.

In the JIRA app, click your profile icon in the top right corner of the page.

JIRA Home Page

In the section with your name, click the Account settings link, this will take you to another page that contains information about your Atlassian account.

Account Pop Up

In the left-hand sidebar, click the Products link and your domain will be located in the "Jira settings" section.

Find Domain

User#

This is the email that is tied to your Atlassian account.

In the JIRA app, click your profile icon in the top right corner of the page.

JIRA Home Page

In the section with your name, click the Account settings link. This takes you to another page that contains information about your Atlassian account.

Account Pop Up

In the left-hand sidebar, click the Email link and your email will located in the "Current email" section.

Find Domain

API Key#

An API key is generated within your account page. The following steps will navigate you to its location. Once created, copy the key and enter it in the JIRA form under 'API Key'.

In the JIRA app, click your profile icon in the top right corner of the page.

JIRA Home Page

In the section with your name, click the Account settings link, this will take you to another page that contains information about your Atlassian account.

Account Pop Up

In the left-hand sidebar, click Security. Then click Create and manage API tokens under the "API token" section.

Go to your API manager

Click API tokens in the left-hand sidebar and this will display all the API tokens you've generated. To generate a new API key, click the blue Create API token button.

Create a new API key

Give your new token a label. Be careful, as this is the only time you will be able to see the API token so make sure you copy it.

Label token

Endpoints#

The table below shows a list of endpoints available to connect within the DataDistillr application. If you need to connect to an endpoint not listed below, please use the Custom API Form.

Endpoint Required Optional Description
/board/{boardId} Returns the board with the matching board ID.
/board startAt
maxResults
type
name
projectKeyOrId
accountIdLocation
projectLocation
includePrivate
negateLocationFiltering
orderBy
expand
filterId		 Returns all boards.
/board/{boardId}/epic startAt
maxResults
done		 Returns all epics from the board, for the given board ID.
/board/{boardId}/issue startAt
maxResults
jql
validateQuery
fields
expand		 Returns all issues from a board, for a given board ID.
/board/{boardId}/project startAt
maxResults		 Returns all projects that are associated with the board.

The endpoints above will display as follows in the nav tree once your API has successfully connected.

JIRA Endpoints

Sample Queries#

The following queries are intended to help you get started, and make life simpler querying within your API.

For the following examples, suppose that my JIRA API data source was called myjiraapi and I want to query an endpoint. The endpoint goes after the JIRA data source name:

FROM Clause

FROM `myjiraapi`.`<ENDPOINT>`

Get Board#

This board will only be returned if the user has permission to view it.

SELECT *
FROM `myjiraapi`.`/board/:boardId`
WHERE `boardId` = '1' LIMIT 100

Get All Boards#

This only includes boards that the user has permission to view.

SELECT *
FROM `myjiraapi`.`/board` LIMIT 100

Get Epics#

This only includes epics that the user has permission to view. Note, if the user does not have permission to view the board, no epics will be returned at all.

SELECT *
FROM `myjiraapi`.`/board/:boardId/epic`
WHERE `boardId` = '1' LIMIT 100

Get Issues#

This only includes issues that the user has permission to view. An issue belongs to the board if its status is mapped to the board's column. Epic issues do not belong to the scrum boards. Note, if the user does not have permission to view the board, no issues will be returned at all. Issues returned from this resource include Agile fields, like sprint, closedSprints, flagged, and epic. By default, the returned issues are ordered by rank.

SELECT *
FROM `myjiraapi`.`/board/:boardId/issue`
WHERE `boardId` = '1' LIMIT 100

Get Projects#

If the user does not have permission to view the board, no projects will be returned at all. Returned projects are ordered by the name.

SELECT *
FROM `myjiraapi`.`/board/:boardId/project`
WHERE `boardId` = '1' LIMIT 100