# Jira

Jira is Atlassian's project management and issue tracking platform used by software teams worldwide. The Sling Jira connector extracts data from the Jira Cloud REST API v3 and Agile API, supporting projects, issues, boards, sprints, comments, worklogs, changelogs, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `email` **(required)** -> Your Atlassian account email address
* `api_token` **(required)** -> Your Atlassian API token
* `domain` **(required)** -> Your Jira Cloud domain (e.g., `your-company.atlassian.net`)

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your API Token

1. Log in to your Atlassian account at [id.atlassian.com](https://id.atlassian.com)
2. Go to **Security** > [**API tokens**](https://id.atlassian.com/manage-profile/security/api-tokens)
3. Click **Create API token**
4. Give your token a descriptive label (e.g., "Sling Integration")
5. Click **Create** and copy the token

Your domain is the subdomain of your Jira Cloud instance (e.g., if your Jira URL is `https://acme.atlassian.net`, the domain is `acme.atlassian.net`).

### Using `sling conns`

Here are examples of setting a connection named `JIRA`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set JIRA type=api spec=jira \
  secrets='{ email: user@company.com, api_token: ATATT3xFfGF0..., domain: your-company.atlassian.net }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export JIRA='{ type: api, spec: jira, secrets: { email: "user@company.com", api_token: "ATATT3xFfGF0...", domain: "your-company.atlassian.net" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  JIRA:
    type: api
    spec: jira
    secrets:
      email: "user@company.com"
      api_token: "ATATT3xFfGF0..."
      domain: "your-company.atlassian.net"
```

**With anchor date for historical data:**

```yaml
connections:
  JIRA:
    type: api
    spec: jira
    secrets:
      email: "user@company.com"
      api_token: "ATATT3xFfGF0..."
      domain: "your-company.atlassian.net"
    inputs:
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync Jira data to a PostgreSQL database:

```yaml
source: JIRA
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: jira.{stream_name}

streams:
  # sync all endpoints
  '*':

  # Issues with incremental sync
  issues:
    mode: incremental
```

**Incremental sync for issues:**

```yaml
source: JIRA
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: jira.{stream_name}

streams:
  # Reference data (small, always full refresh)
  issue_types:
  priorities:
  resolutions:
  statuses:
  fields:

  # Core data
  projects:
  users:
  labels:

  # Agile
  boards:
  sprints:

  # Project details
  project_versions:
  project_components:

  # Issues (incremental)
  issues:
    mode: incremental

  # Issue details (depend on issues queue)
  issue_comments:
  issue_worklogs:
  issue_changelogs:
```

## Endpoints

| Endpoint             | Description                                    | Incremental |
| -------------------- | ---------------------------------------------- | ----------- |
| `issue_types`        | All issue types (Task, Story, Bug, Epic, etc.) | No          |
| `priorities`         | All issue priority levels                      | No          |
| `resolutions`        | All issue resolution types                     | No          |
| `statuses`           | All workflow statuses                          | No          |
| `fields`             | All fields including custom fields             | No          |
| `projects`           | All accessible projects                        | No          |
| `users`              | All users in the Jira instance                 | No          |
| `labels`             | All issue labels                               | No          |
| `boards`             | All agile boards (Scrum, Kanban)               | No          |
| `sprints`            | All sprints across all boards                  | No          |
| `project_versions`   | Versions/releases for each project             | No          |
| `project_components` | Components for each project                    | No          |
| `issues`             | All issues via JQL search                      | Yes         |
| `issue_comments`     | Comments on issues                             | No          |
| `issue_worklogs`     | Time tracking worklogs on issues               | No          |
| `issue_changelogs`   | Field change history for issues                | No          |

To discover available endpoints:

```bash
sling conns discover JIRA
```

## How It Works

### Queues and Dependencies

The Jira connector uses a queue-based system for parent-child relationships:

* **`projects`** populates the `project_keys` queue, which feeds into `project_versions` and `project_components`
* **`boards`** populates the `board_ids` queue, which feeds into `sprints`
* **`issues`** populates the `issue_keys` queue, which feeds into `issue_comments`, `issue_worklogs`, and `issue_changelogs`

This means child endpoints automatically iterate over the parent data, so you get comments/worklogs/changelogs for all synced issues without additional configuration.

### Incremental Sync

The `issues` endpoint supports incremental sync using the `updated` timestamp field. On subsequent runs with state persistence, only issues updated since the last sync are fetched, using Jira's JQL query: `updated >= "YYYY/MM/DD HH:MM" ORDER BY updated ASC`.

## Rate Limiting

The Jira Cloud API has rate limits that vary by plan:

* **Free/Standard:** Varies by endpoint
* **Premium/Enterprise:** Higher limits

The connector automatically:

* Limits to 5 requests per second
* Uses up to 3 concurrent requests for child endpoints (5 for issue details)
* Retries with exponential backoff on 429 (rate limit) responses
* Retries with linear backoff on 500+ server errors

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/jira.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.