> For the complete documentation index, see [llms.txt](https://docs.whalesync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.whalesync.com/connectors/jira.md).

# Jira

Two-way sync Jira issues, statuses, assignees, sprints, and custom fields with Airtable, Notion, Google Sheets, and more. Each Jira project syncs as a table.

## Jira Connector Guide

This guide covers how to connect Whalesync to [Jira](https://www.atlassian.com/software/jira), how your projects and issues appear in Whalesync, and which fields sync.

In Whalesync terms, a Jira Cloud **site** is the base you pick, each **project** on it is a table, and each **issue** in the project is a record. Three more tables, **Users**, **Sprints**, and **Versions**, list what the people, sprint, and version fields point at; they are read only.

### Connecting to Jira

Whalesync connects by signing in with your Atlassian account, and acts as that Jira user. See [Authorize Jira](https://docs.whalesync.com/connectors/jira/authorize-jira.md) for the sign-in and the Jira permissions the user needs.

1. In Whalesync, choose Jira and sign in with Atlassian.
2. Pick the Jira site to sync. Every Jira Cloud site the sign-in reaches is listed.
3. Pick the projects to sync.

### Syncing Data

Every project the connected user can browse in Jira is available as a table. A project's table holds all of its issues, whatever their type, subtasks included, and its **Issue type** column says which type each one is.

A table's columns are the fields on the project's create screens, across all its issue types, plus the ones every issue has: Key, Link, Status, Status category, Resolution, Reporter, Creator, Subtasks, Time spent, and the created, updated, and resolved times. So two projects with different fields have different columns, and a custom field appears only in projects where it's on a create screen. Reading create screens takes Jira's Create issues permission. In a project where the connected user can't create issues, the table has only Summary, Description, Priority, Assignee, Labels, Components, Fix versions, Due date, and Parent, and none of the project's custom fields.

An issue moved to another project leaves the first project's table and appears in the second's, if that project is synced too. Its Key changes with the move.

## Supported Fields

<table><thead><tr><th>Jira field</th><th>Status</th><th>Notes</th></tr></thead><tbody>
<tr><td>Summary</td><td>✅ Supported</td><td>Required when creating an issue from another app.</td></tr>
<tr><td>Description, Environment</td><td>✅ Supported</td><td>Synced as formatted text. See <a href="#descriptions">Descriptions</a>.</td></tr>
<tr><td>Issue type</td><td>✅ Supported</td><td>Set when Whalesync creates an issue: Task when the record names none, or the project's first type that isn't a subtask if it has no Task. Jira changes an existing issue's type by moving the issue, which Whalesync doesn't do, so changing it is reported as a sync issue for that issue.</td></tr>
<tr><td>Status</td><td>✅ Supported</td><td>A select of the project's statuses. Changed through the project's workflow. See <a href="#status-changes">Status changes</a>.</td></tr>
<tr><td>Priority</td><td>✅ Supported</td><td>Synced by name.</td></tr>
<tr><td>Assignee, Reporter</td><td>✅ Supported</td><td>Links to the Users table.</td></tr>
<tr><td>Labels</td><td>✅ Supported</td><td>A multi-select. Jira adds a label the first time an issue uses it.</td></tr>
<tr><td>Components</td><td>✅ Supported</td><td>A multi-select of the project's components, synced by name.</td></tr>
<tr><td>Fix versions, Affects versions</td><td>✅ Supported</td><td>Links to the Versions table.</td></tr>
<tr><td>Sprint</td><td>✅ Supported</td><td>Links to the Sprints table: every sprint the issue has been in. Jira keeps an issue in one open sprint, so Whalesync puts the issue in the last sprint the record lists.</td></tr>
<tr><td>Parent</td><td>✅ Supported</td><td>A link to another issue in the same project, such as a subtask's parent or an epic. A parent in another project reads as empty.</td></tr>
<tr><td>Due date, Start date</td><td>✅ Supported</td><td>A date.</td></tr>
<tr><td>Story point estimate</td><td>✅ Supported</td><td>A number.</td></tr>
<tr><td>Original estimate, Remaining estimate</td><td>✅ Supported</td><td>In hours, written to Jira in whole minutes. Clearing an estimate leaves Jira's value as it is.</td></tr>
<tr><td>Subtasks</td><td>➡️ Supported (1-Way)</td><td>Read only. Links to the issue's subtasks. Set a subtask's Parent to change them.</td></tr>
<tr><td>Status category</td><td>➡️ Supported (1-Way)</td><td>Read only. To Do, In Progress, or Done, from the status.</td></tr>
<tr><td>Resolution</td><td>➡️ Supported (1-Way)</td><td>Read only.</td></tr>
<tr><td>Creator</td><td>➡️ Supported (1-Way)</td><td>Read only. A link to the Users table.</td></tr>
<tr><td>Time spent</td><td>➡️ Supported (1-Way)</td><td>Read only, in hours.</td></tr>
<tr><td>Key, Link, Created at, Updated at, Resolved at</td><td>➡️ Supported (1-Way)</td><td>Read only. The key, such as <code>PROJ-123</code>, changes when an issue moves to another project.</td></tr>
<tr><td>Rank, Team</td><td>➡️ Supported (1-Way)</td><td>Read only, as text.</td></tr>
<tr><td>Attachments, Comments, Work log, Linked issues, Watchers, Votes</td><td>✖️ Not supported</td><td>No column.</td></tr>
<tr><td>Development, Vulnerability</td><td>✖️ Not supported</td><td>No column. Other apps fill these in.</td></tr>
</tbody></table>

### Custom fields

Each custom field on a project's create screens is a column of that project's table.

<table><thead><tr><th>Custom field type</th><th>Status</th><th>Notes</th></tr></thead><tbody>
<tr><td>Short text, URL</td><td>✅ Supported</td><td></td></tr>
<tr><td>Paragraph</td><td>✅ Supported</td><td>Synced as formatted text, like Description.</td></tr>
<tr><td>Number</td><td>✅ Supported</td><td></td></tr>
<tr><td>Date picker</td><td>✅ Supported</td><td>A date.</td></tr>
<tr><td>Date time picker</td><td>✅ Supported</td><td>A date and time, read and written in UTC.</td></tr>
<tr><td>Select list (single choice), Radio buttons</td><td>✅ Supported</td><td>Synced by option value. The option has to exist in Jira.</td></tr>
<tr><td>Select list (multiple choices), Checkboxes</td><td>✅ Supported</td><td>Synced by option values. Each option has to exist in Jira.</td></tr>
<tr><td>Select list (cascading)</td><td>✅ Supported</td><td>A select whose options are each parent and each <code>Parent &gt; Child</code>.</td></tr>
<tr><td>Labels</td><td>✅ Supported</td><td>A multi-select, like the Labels field.</td></tr>
<tr><td>User picker</td><td>✅ Supported</td><td>Links to the Users table.</td></tr>
<tr><td>Group picker</td><td>✅ Supported</td><td>Synced by group name.</td></tr>
<tr><td>Version picker</td><td>✅ Supported</td><td>Links to the Versions table.</td></tr>
<tr><td>Project picker</td><td>✅ Supported</td><td>A select of project keys.</td></tr>
<tr><td>Text field (read only)</td><td>➡️ Supported (1-Way)</td><td>Read only.</td></tr>
<tr><td>Other types</td><td>➡️ Supported (1-Way)</td><td>Read only, as text.</td></tr>
</tbody></table>

### Users, Sprints, and Versions

These tables are read only. They're there for the people, sprint, and version fields to link to: to set an issue's assignee from another app, sync the Users table too and link the record to a user in it. See [Reference fields](https://docs.whalesync.com/features/additional-features/reference-fields.md).

* **Users** lists the site's users, including app and customer accounts, with their name, email, account type, and whether they're active.
* **Sprints** lists the sprints on the site's boards, with their name, state, goal, board, and dates.
* **Versions** lists every project's versions, with their name, project, description, release and start dates, and whether they're released or archived.

## Descriptions

Description, Environment, and Paragraph fields are formatted text. Headings, bold, italic, underline, strikethrough, code, subscript, superscript, links, lists, quotes, code blocks, dividers, and tables come through in both directions.

Some of Jira's formatting has no equivalent elsewhere, so it syncs as what it shows. Mentions sync as the person's name, emoji as the character, dates as the day, status lozenges as their text, smart links as plain links, and panels and expands as their contents. Action items sync as list items with their check mark in the text.

Images in a description aren't synced. When a description changes in another app, Whalesync keeps the images the issue has in Jira by adding them at the end.

## Status changes

Jira changes an issue's status through its workflow's transitions, not by editing the field. When a record's Status changes, Whalesync moves the issue through the transition that leads from its current status to the new one.

* **If no single transition leads there**, the change is reported as a sync issue that names the statuses the issue can move to from where it is, such as *Jira can't move PROJ-12 from "To Do" to "Done" in one step. From there it can go to "In Progress".* Change the status one step at a time, or change it in Jira.
* **If the transition asks for fields**, Whalesync fills them in from the record. When a field the transition requires has no value, the sync issue names it. Set the field in Jira, or sync it. For a field Whalesync can't write, such as Resolution, change the status in Jira.
* **If the issue's status blocks edits**, as Closed often does, and the record changes the status too, Whalesync moves the status first and then makes the edits.

## Watcher emails

Synced edits email an issue's watchers unless the connected user is a project admin.

When Whalesync edits an issue's fields, it asks Jira not to email the watchers. Jira honors that only for a user who is an admin of the issue's project. Whalesync doesn't ask for status changes or new issues, which send whatever emails the project's notification scheme sets. To keep synced edits from emailing watchers, connect Jira as a user who is an admin of the projects you sync.

## Changes made in Jira

Jira doesn't send Whalesync webhooks, so a change made in Jira isn't synced within seconds. Whalesync finds it the next time it checks the project for changes.

## Things to Keep in Mind

* **Only projects the connected user can browse are listed.**
* **Whalesync connects to Jira Cloud.** Jira Data Center and Jira Server are not supported.
* **Whalesync doesn't create statuses, options, components, versions, or sprints.** A value Jira doesn't have is reported as a sync issue for that issue, with Jira's reason, such as *Jira rejected the request: …*. Labels are the exception.
* **A new issue gets Jira's defaults for its empty fields.** Whalesync leaves empty fields out when it creates an issue, so Jira fills in the reporter, the priority, and any other default.
* **Deleting a record deletes the issue in Jira.** Jira refuses to delete an issue that has subtasks until they are deleted, and Whalesync doesn't delete them for you.
* **Attachments, comments, work logs, and issue links are not synced**, and neither are watchers and votes.
* **Whalesync reads about 15,000 issues an hour from each Jira connection**, so a large first sync takes a while: about 40 minutes for 10,000 issues.
* **Jira limits how many requests Whalesync can make each hour.** When the limit is reached, the sync pauses with *You have exceeded the service API quota*, then starts again by itself within the hour.