> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindsdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

This documentation describes the integration of MindsDB with [Jira](https://www.atlassian.com/software/jira/guides/getting-started/introduction), the #1 agile project management tool used by teams to plan, track, release and support world-class software with confidence.
The integration allows MindsDB to access data from Jira and enhance it with AI capabilities.

## Prerequisites

Before proceeding, ensure the following prerequisites are met:

1. Install MindsDB locally via [Docker](https://docs.mindsdb.com/setup/self-hosted/docker) or [Docker Desktop](https://docs.mindsdb.com/setup/self-hosted/docker-desktop).
2. To connect Jira to MindsDB, install the required dependencies following [this instruction](https://docs.mindsdb.com/setup/self-hosted/docker#install-dependencies).

## Connection

Establish a connection to Jira from MindsDB by executing the following SQL command and providing its [handler name](https://github.com/mindsdb/mindsdb/tree/main/mindsdb/integrations/handlers/jira_handler) as an engine.

```sql theme={null}
CREATE DATABASE jira_datasource
WITH
    ENGINE = 'jira',
    PARAMETERS = {
        "jira_url": "https://example.atlassian.net",
        "jira_username": "john.doe@example.com",
        "jira_api_token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "cloud": true
    };
```

Required connection parameters include the following:

* `jira_url`: The base URL for your Jira instance/server.
* `cloud` (optional): Set `true` for Jira Cloud or `false` for Jira Server. Defaults to `true`.
* Jira Cloud credentials:
  * `jira_username`
  * `jira_api_token`
* Jira Server credentials (set `cloud: false`):
  * Either `jira_personal_access_token`, **or**
  * `jira_username` and `jira_password`

<Tip>
  Refer this [guide](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) for instructions on how to create API tokens for your account.
</Tip>

## Usage

Retrieve data from a specified table by providing the integration and table names:

```sql theme={null}
SELECT *
FROM jira_datasource.table_name
LIMIT 10;
```

<Note>
  The above example utilize `jira_datasource` as the datasource name, which is defined in the `CREATE DATABASE` command.
</Note>

## Available tables

The handler registers the following tables:

* `projects`: Basic project metadata.
* `issues`: Normalized issue fields (project, summary, description, priority, status, labels, components, creator/reporter/assignee, timestamps).
* `attachments`: Attachments derived from issues.
* `comments`: Comments derived from issues.
* `users`: Users available to the current Jira context. Column set depends on `cloud`:
  * Cloud columns: `accountId, accountType, emailAddress, displayName, active, timeZone, locale, applicationRoles, avatarUrls, groups`
  * Server columns: `key, name, emailAddress, displayName, active, timeZone, locale, lastLoginTime, applicationRoles, avatarUrls, groups, deleted, expand`
* `groups`: User groups (`groupId, name, html`).

Attachments and comments are fetched by first loading issues. Use `LIMIT` whenever possible to reduce API calls.

## Query examples

List projects:

```sql theme={null}
SELECT id, key, name
FROM jira_datasource.projects;
```

Fetch recent issues for a project:

```sql theme={null}
SELECT key, summary, status, assignee, created
FROM jira_datasource.issues
WHERE project_key = 'ENG'
LIMIT 50;
```

Retrieve comments for a specific issue:

```sql theme={null}
SELECT body, author, created
FROM jira_datasource.comments
WHERE issue_key = 'ENG-123';
```