> ## Documentation Index
> Fetch the complete documentation index at: https://domoinc-openapi-sync-dataflows.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# JIRA Rest API Connector

## Intro

JIRA helps teams get organized and work together to build incredible products, but product teams are just one part of your organization. With Domo, you can combine data from multiple sources into a single platform--pulling data from product development, marketing, sales, operations, and finance for a real-time, holistic view of your business. Once your data is in Domo, you can get stunning, dynamic JIRA visualizations with real-time data, on any device.

Domo's JIRA connector allows you to connect to your JIRA account to extract data from JIRA. You can import data including issue tracking, completed tickets per team, ticket resolution time, and project management metrics, using either custom or predefined queries. To learn more about the JIRA API, see [https://developer.atlassian.com/jira...e-query-issues](https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials/jira-rest-api-example-query-issues "https://developer.atlassian.com/jiradev/jira-apis/jira-rest-apis/jira-rest-api-tutorials/jira-rest-api-example-query-issues").

The JIRA Rest API Connector is a "Cloud App" connector, meaning it retrieves data stored in the cloud. In the Data Center, you can access the connector page for this and other Cloud App connectors by clicking **Cloud App** in the toolbar at the top of the window.

You connect to your JIRA account in the Data Center. This topic discusses the fields and menus that are specific to the JIRA connector user interface. General information for adding DataSets, setting update schedules, and editing DataSet information is discussed in [Adding a DataSet Using a Data Connector](https://domo-support.domo.com/s/article/360042926274?language=en_US "Adding a DataSet Using a Data Connector").

<table class="mt-responsive-table" data-aura-rendered-by="33:195;a">
  <tbody>
    <tr>
      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          <b>
            Primary Use Cases
          </b>
        </p>
      </td>

      <td class="mt-noheading" colspan="1" rowspan="1">
        <ul>
          <li>
            <p>
              Tracking progress and movement of tickets
            </p>
          </li>

          <li>
            <p>
              Number of tickets assigned to specific users or groups
            </p>
          </li>

          <li>
            <p>
              Seeing if too many tickets of a certain type are open (bugs)
            </p>
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          <b>
            Primary Metrics
          </b>
        </p>
      </td>

      <td class="mt-noheading" colspan="1" rowspan="1">
        <ul>
          <li>
            <p>
              Bug / issue / ticket tracking (by age, type, status, submitter)
            </p>
          </li>

          <li>
            <p>
              Completed tickets per team
            </p>
          </li>

          <li>
            <p>
              Ticket resolution time
            </p>
          </li>

          <li>
            <p>
              Project management metrics (tracking individual tasks of a larger project or epic).
            </p>
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          <b>
            Primary Company Roles
          </b>
        </p>
      </td>

      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          Product managers
        </p>
      </td>
    </tr>

    <tr>
      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          <b>
            Average Implementation Time
          </b>
        </p>
      </td>

      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          {" "}

          This can vary wildly depending on the implementation and the user's level of knowledge of their JIRA system.{" "}
        </p>
      </td>
    </tr>

    <tr>
      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          <b>
            Ease of Use (on a 1-to-10 scale with 1 being easiest)
          </b>
        </p>
      </td>

      <td class="mt-noheading" colspan="1" rowspan="1">
        <p>
          7
        </p>
      </td>
    </tr>
  </tbody>
</table>

## Best Practices

* You should usually use "Replace" with the JIRA connector, as "Append" does not work well.
* If the query is for data across a long time period, scheduling should be kept to a minimum (once a day). For shorter queries, more frequent updates are appropriate.

## Prerequisites

To connect to your JIRA account and create a DataSet, you must have the following:

* The username and password/API key you use to log into JIRA. The Jira cloud users must use an API Key. You can create one here:

  [http://id.atlassian.com](http://id.atlassian.com)

* The URL for your company's JIRA instance

* The JQL query you will use to pull data (if you are building a custom report)

Credentials are received upon account creation. A JIRA Admin is likely to have created username and passwords for most users in your company if you use an on-premise JIRA implementation.

### SSO

Single Sign-On (SSO) credentials will NOT work. However, you can work around SSO limitations by doing the following:

1. Have your JIRA administrator create a local account with a username and password specifically for API use.
2. Create an API key at
   [http://id.atlassian.com/](http://id.atlassian.com/ "http://id.atlassian.com/").
3. On the JIRA connector page in Domo, enter the API key you created instead of the password. (Depending on the account, you may need to enter your username or JIRA account email address as the username.)

## Connecting to Your JIRA Instance

This section enumerates the options in the **Credentials** and **Details** panes in the JIRA Rest PAI Connector page. The components of the other panes in this page, **Scheduling** and **Name & Describe Your DataSet**, are universal across most connector types and are discussed in greater length in [Adding a DataSet Using a Data Connector](https://domo-support.domo.com/s/article/360042926274?language=en_US "Adding a DataSet Using a Data Connector").

### Credentials Pane

This pane contains fields for entering credentials to connect to your JIRA instance. The following table describes what is needed for each field:

<table border="1" cellpadding="1" cellspacing="1" data-aura-rendered-by="33:195;a">
  <thead>
    <tr>
      <th colspan="1" rowspan="1">
        <p>
          Field
        </p>
      </th>

      <th colspan="1" rowspan="1">
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td colspan="1" rowspan="1">
        <p>
          Username
        </p>
      </td>

      <td colspan="1" rowspan="1">
        <p>
          Enter the username you use to log into your JIRA instance.
        </p>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        <p>
          Password
        </p>
      </td>

      <td colspan="1" rowspan="1">
        <p>
          {" "}

          Enter the password you use to log into your JIRA instance. The

          <span>
            {" "}

            Jira Cloud users must use an API Key. You can create one here:

            <a href="http://id.atlassian.com" rel="noopener" target="_blank">
              {" "}

              [http://id.atlassian.com\{](http://id.atlassian.com\{)" "}
            </a>
          </span>
        </p>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        <p>
          Server URL
        </p>
      </td>

      <td colspan="1" rowspan="1">
        <p>
          <span>
            {" "}

            Enter the URL for your JIRA instance (for example,

            <a href="http://onjira.mycompany.com" rel="noopener" target="_blank">
              {" "}

              onjira.mycompany.com{" "}
            </a>

            ).{" "}
          </span>
        </p>
      </td>
    </tr>
  </tbody>
</table>

Once you have entered valid JIRA credentials, you can use the same account any time you go to create a new JIRA Rest API DataSet. You can manage connector accounts in the Accounts tab in the Data Center. For more information about this tab, see [Managing User Accounts for Connectors](https://domo-support.domo.com/s/article/360042926054?language=en_US "Managing User Accounts for Connectors").

### Details Pane

This pane contains a primary **Reports** menu, along with various other menus which may or may not appear depending on the report type you select.

<table border="1" cellpadding="1" cellspacing="1" data-aura-rendered-by="33:195;a">
  <thead>
    <tr>
      <th colspan="1" rowspan="1">
        <p>
          Menu
        </p>
      </th>

      <th colspan="1" rowspan="1">
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td colspan="1" rowspan="1">
        <p>
          Report
        </p>
      </td>

      <td colspan="1" rowspan="1">
        <p>
          {" "}

          Select the

          <span />

          report you want to run. The following reports are available:{" "}
        </p>

        <table border="1" cellpadding="1" cellspacing="1">
          <tbody>
            <tr>
              <th colspan="1" rowspan="1">
                {" "}

                Report{" "}
              </th>

              <th colspan="1" rowspan="1">
                {" "}

                Description{" "}
              </th>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Issue Query{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Allows the user to query issues using JQL (JIRA Query Language).{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Boards{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns a list of scrum boards.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Board Sprints{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns a list of sprints for the selected board.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Sprint Issues{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns issues for the selected sprints.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Fields{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns a list of fields used in the user's JIRA account.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Group Members{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns a list of users that belong to the specified group. You must have admin access to run this report.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Projects{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns a list of all projects the user has access to.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Project Versions{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns a list of all versions of the specified project.{" "}
              </td>
            </tr>
          </tbody>
        </table>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        JQL Query{" "}
      </td>

      <td colspan="1" rowspan="1">
        <p>
          <span>
            Enter a JQL query to pull custom data.
          </span>

          <a href="https://confluence.atlassian.com/display/JIRA/Advanced+Searching" target="_blank" title="Jira Documentation">
            {" "}

            Jira Documentation{" "}
          </a>

          .{" "}
        </p>

        {" "}

        <Note>
          <div class="info-box-wrapper">
            <div class="info-box-icon-container" />

            <div class="info-box-content-container">
              <div class="info-box-content">
                <b>
                  Note:
                </b>

                You need to always add order by clause in the query. On the Jira side, there is a
                limitation that does not sort the issues in any order, causing the connector to miss and duplicate some
                items.{" "}
              </div>
            </div>
          </div>

          {" "}
        </Note>

        <table border="1">
          <tbody>
            <tr>
              <th colspan="1" rowspan="1">
                {" "}

                Description{" "}
              </th>

              <th colspan="1" rowspan="1">
                {" "}

                Query Examples{" "}
              </th>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                All issues created at the start of the month, 3 months ago.{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                created >= STARTOFMONTH(-3){" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                All issues created at the start of the day, 10 days ago.{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                created >= STARTOFDAY(-10){" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                All issues updated since a specific date.{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                updated >= '2020-01-01'{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                All issues assigned to me.{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                assignee = currentUser(){" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                All issues for project 'Some Project' that are closed{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                project = 'Some Project'

                <br />

                and status = closed{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                All issues reported by a specific user{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                reporter = '

                <a href="http://user.name" rel="noopener" target="_blank">
                  {" "}

                  user.name{" "}
                </a>

                '{" "}
              </td>
            </tr>
          </tbody>
        </table>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        Data Option{" "}
      </td>

      <td colspan="1" rowspan="1">
        <table border="1">
          <tbody>
            <tr>
              <th colspan="1" rowspan="1">
                {" "}

                Data Option{" "}
              </th>

              <th colspan="1" rowspan="1">
                {" "}

                Description{" "}
              </th>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Comments Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns JIRA tickets with their related comments.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Changelog Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns changelogs per issue applicable to the query. The Changelog report is only available to Jira Cloud
                users.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Labels Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns labels for issues applicable to the query.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Linked Issues Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns linked issues for issues applicable to the query.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Sprint Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns details of sprints for issues applicable to the query.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Standard Ticket Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns columns for nearly every parameter for JIRA tickets, such as issue summary and description, creation
                date, resolution date, impacted customer name, environment, etc.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Ticket History Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns historical information about tickets.{" "}
              </td>
            </tr>

            <tr>
              <td colspan="1" rowspan="1">
                {" "}

                Worklog Report{" "}
              </td>

              <td colspan="1" rowspan="1">
                {" "}

                Returns worklogs per issue applicable to the query.{" "}
              </td>
            </tr>
          </tbody>
        </table>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        Filter Type{" "}
      </td>

      <td colspan="1" rowspan="1">
        <span>
          Select to include or exclude specific fields from the returned dataset.
        </span>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        Flatten All Fields{" "}
      </td>

      <td colspan="1" rowspan="1">
        {" "}

        Select which fields you want to see expanded in data.{" "}
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        Sublists To Flatten{" "}
      </td>

      <td colspan="1" rowspan="1">
        <p>
          Enter the sublists to be flattened.
        </p>

        <p>
          {" "}

          Note: If you clear the

          <b>
            Flatten All Fields
          </b>

          checkbox, the

          <b>
            Sublists To Flatten
          </b>

          field appears.{" "}
        </p>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        Reset Schema{" "}
      </td>

      <td colspan="1" rowspan="1">
        {" "}

        Select this checkbox to include only columns that are imported in the current execution.

        <br />

        This option only
        works for the

        <b>
          Replace
        </b>

        update method.{" "}
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        {" "}

        Group Name{" "}
      </td>

      <td colspan="1" rowspan="1">
        <span>
          {" "}

          Enter the group that contains the users you wish to retrieve. This report requires an Administrator account.{" "}
        </span>
      </td>
    </tr>
  </tbody>
</table>

### Other Panes

For information about the remaining sections of the connector interface, including how to configure scheduling, retry, and update options, see [Adding a DataSet Using a Data Connector](https://domo-support.domo.com/s/article/360042926274?language=en_US "Adding a DataSet Using a Data Connector").

### FAQs

<AccordionGroup>
  <Accordion title="When should I use this connector?">
    The JIRA REST API connector allows you to connect to a JIRA server instance and bring your JIRA data into Domo. This connector requires a local username and password.
  </Accordion>

  <Accordion title="Which endpoint(s) does each report call in this connector?">
    <table data-aura-rendered-by="33:195;a">
      <tbody>
        <tr>
          <th colspan="1" rowspan="1" width="20%">
            Report Name
          </th>

          <th colspan="1" rowspan="1" width="20%" />

          <th colspan="1" rowspan="1" width="60%">
            Endpoint URL(s)
          </th>
        </tr>

        <tr>
          <td colspan="1" rowspan="3">
            Agile API:
          </td>

          <td colspan="1" rowspan="1">
            Agile Boards
          </td>

          <td colspan="1" rowspan="1">
            /rest/agile/1.0/board
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Board Sprints
          </td>

          <td colspan="1" rowspan="1">
            /rest/agile/1.0/board/{boardId}/sprint
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Sprint Issues
          </td>

          <td colspan="1" rowspan="1">
            /rest/agile/1.0/board/{boardId}/sprint/{SprintId}/issue
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Fields
          </td>

          <td colspan="1" rowspan="1" />

          <td colspan="1" rowspan="1">
            /rest/api/2/field
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Group Members
          </td>

          <td colspan="1" rowspan="1" />

          <td colspan="1" rowspan="1">
            /rest/api/2/group/member
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Issue Query
          </td>

          <td colspan="1" rowspan="1" />

          <td colspan="1" rowspan="1">
            /rest/api/2/search
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Projects
          </td>

          <td colspan="1" rowspan="1" />

          <td colspan="1" rowspan="1">
            /rest/api/2/project
          </td>
        </tr>

        <tr>
          <td colspan="1" rowspan="1">
            Project Versions
          </td>

          <td colspan="1" rowspan="1" />

          <td colspan="1" rowspan="1">
            /rest/api/2/project/{projectId}/versions
          </td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="What kind of credentials do I need to power up this connector?">
    You need the username, password, and server URL for your Jira instance.
  </Accordion>

  <Accordion title="Domo is reporting that my Jira credentials are invalid. What am I doing wrong?">
    Possible reasons for this error include:

    * Your Jira server has not had API access enabled. Contact your Jira administrator to ensure that API access is turned on.
    * You're using your email address instead of your actual Jira username. In many cases, these may be the same; however, it's not uncommon for "
      [user.name@company.com](mailto:user.name@company.com)" to be your email while " [user.name](http://user.name)" is your actual username.
  </Accordion>

  <Accordion title="Can I use my SSO account to login?">
    SSO implementations are not supported in Jira. However you can work around these limitations.

    * Jira Server – Your Jira administrator can create a local account with a user name and password specifically for API use.
    * Jira Cloud – You can create an API key at
      [ATLASSIAN](https://id.atlassian.com/login "ATLASSIAN"). On the connectors page, enter the API key you’ve created instead of the password.
      Note: Depending on your account, you may need to enter your username or your Jira account email address as the username.
  </Accordion>

  <Accordion title="How frequently will my data update?">
    Data from Jira's servers is usually made available to the API immediately.
  </Accordion>

  <Accordion title="How do I know if my query is right?">
    Jira's platform provides a handy tool to verify if your query is valid. An easy way to access this tool is simply to do a search in Jira's search bar. Once on the search screen, you will see a green check box next to the query string for your search to indicate that it is valid. Otherwise you will see a red X. You can switch back to the basic search functionality to build a query from the available selectors, and then switch again to advanced to see the resulting query.
  </Accordion>

  <Accordion title="I keep running into connection errors (gateway timeout, bad gateway, connection timed out, connection reset, etc...). How do I fix that?">
    The most common cause of connection errors is that your Jira server has too much load to handle your requests. Contact your Jira administrator to see about allocating more resources to your Jira server.
  </Accordion>

  <Accordion title="Can this connector pull custom fields?">
    Because Jira returns so much data, the connector enables you to specify fields either as inclusive or exclusive. If you choose inclusive, only the fields you specify will be returned. If you choose exclusive, all fields will be returned except for those that you specify.

    **Note**: Field ids must be entered. If the field names are entered, then they will be ignored.
  </Accordion>

  <Accordion title="How can I pull the data from boards?">
    Select the report type as **Agile API** and the agile report as **Agile Boards** to get the list of all agile boards you have access to.
  </Accordion>

  <Accordion title="Can I use OAuth on this connector?">
    If you wish to use OAuth on Jira instances, use the Jira Cloud connector. Jira Cloud connector supports OAuth2 authentication. You can authenticate to the Jira Cloud connector with the same credentials you use to log into your Jira account online.
  </Accordion>
</AccordionGroup>

## Troubleshooting

* Jira requires a fair amount of configuration from the side of the JIRA admin to ensure that API access is enabled. Common issues include setting the timeouts too short or not providing sufficient resources to the JIRA server.
* If users have trouble understanding how to format JQL, the easiest thing is to log into the JIRA front end. Via the search bar, JIRA provides a tool that can construct a JQL query with preset filters. After constructing your query, if you hit the
  **Advanced** button, JIRA presents you with your selections in JQL format.