# Import from Jira

> Connect a Jira Cloud site to By Dawn through By Dawn's Atlassian app, pick a project or a JQL query, and check how its statuses, priorities and epics map.

This page helps you bring a Jira Cloud project into By Dawn. At the end its issues are By Dawn tickets, its epics are
By Dawn epics, and, if you chose to keep syncing, the two stay in step until your end date.
[Import and sync](https://docs.bydawn.com/import-and-sync/) explains the steps every tracker shares, so this page covers only
what's particular to Jira.

## Before you start

- You need to be a project admin in By Dawn, and an **org admin** has to approve By Dawn's app (see
  [Before you start](https://docs.bydawn.com/import-and-sync/#before-you-start)).
- **The grant acts as the person who approves it.** Atlassian has no separate identity for an app, so By Dawn works in
  Jira as that Atlassian account: it sees what the account sees, and its changes show under that account's name. Use
  a dedicated account, such as a `saw-bot` user, if you don't want By Dawn's changes under your own name. The account
  needs to browse every project you want, and to sync both ways it also needs to edit issues, add comments and move
  issues through their workflow.
- Only Jira Cloud is supported (`https://<your-site>.atlassian.net`). Jira Server and Data Center aren't.

## Connect

1. Sign in to Atlassian as the account By Dawn should act as.

2. In By Dawn, open **Settings › Import & sync › New import**, pick **Jira** and choose **Connect**.

3. Atlassian shows what By Dawn asks for: to read and write Jira work, read users and manage webhooks. Choose
   **Accept**.

4. Atlassian sends you back to By Dawn. If your account can reach exactly one Jira site, By Dawn connects to it. If it can
   reach several, By Dawn lists them, so pick the one to import from. You can't switch sites later on the same
   connection, so to use another site, start a new import.

By Dawn sets up a Jira webhook for the connection when a sync starts, and removes it when the sync ends. You don't
create one in Jira.

## Pick what to bring

- **Project**: every issue in one Jira project. Choose this if you might create tickets in By Dawn that should
  appear in Jira, because a new issue needs a project to go into.
- **JQL query**: any set of issues a Jira search can find, such as
  `project = PROJ AND updated >= -365d`. Leave out `ORDER BY`: By Dawn pulls in order of last update so that it can
  carry on where it left off.

## How Jira maps

- **Statuses.** By Dawn proposes a column from each status's category: *To Do* statuses go to a to-do column (or the
  backlog, if the status is called something like *Backlog*), *In Progress* statuses to a building column (or
  review, if the name mentions review or QA), and *Done* statuses to a completed column.
- **Priorities.** Highest → Urgent, High → High, Medium → Medium, Low and Lowest → Low. A custom priority has no
  default, so map it yourself.
- **Epics.** Jira epics (and any issue type above the standard level) become By Dawn epics, and the issues under them
  join the epic. An epic's own parent, such as an initiative, is kept in the import details.
- **Sub-tasks** become sub-tickets.
- **Sprints.** From the project's Scrum boards. An issue's active sprint, or else its next one, can become a cycle
  or a `sprint:` label.
- **People.** Jira hides many people's emails behind its privacy settings, so expect to pair some people by
  hand.
- **Descriptions** are converted from Jira's rich text to markdown. Panels and macros with no markdown equivalent
  become a quoted block labelled with what they were, so nothing is dropped.

## When you sync both ways

By Dawn writes back the title, description, status, priority, assignee and labels, plus new comments. Due dates come
from Jira but aren't written back.

- A status change goes through the issue's own workflow, the way a person would move it. If no transition leads
  from the issue's current status to the one you mapped, the change is listed as a problem on the connection
  rather than forced.
- Jira labels can't contain spaces, so By Dawn writes `needs review` as `needs-review`.

> **Note:** New tickets you create in By Dawn are created in Jira as **Task** issues, and only on a connection scoped to a
> project.

## Where to go next

- [Import and sync](https://docs.bydawn.com/import-and-sync/): conflicts, pausing and ending a sync.
- [Words we use](https://docs.bydawn.com/glossary/#import-and-sync).

Source: https://docs.bydawn.com/import-jira/