# Import and sync

> Bring your work into By Dawn from Jira, Linear, Azure DevOps, GitHub Issues, GitLab, Asana, Trello or a CSV/JSON export, once or kept in sync until a date you pick.

This page helps you move a team's existing work into a By Dawn project. By the end you'll know how an import
is set up, what each part of the mapping decides, and what happens when a sync ends.

You can bring work in from **Jira Cloud, Linear, Azure DevOps Boards, GitHub Issues, GitLab, Asana and
Trello**, or from a **CSV or JSON export** of any other tracker. Each tracker has its own page for the connect
and mapping steps (see [Your tracker's page](#your-trackers-page)). This page explains what they all share.

## Words on these pages

- **Connection**: one import from one tracker into one project. It holds the app grant, what to bring, the
  mapping and, for a sync, the end date.
- **App grant**: your approval, given on the tracker's own consent screen, for By Dawn's app to read and write there.
  By Dawn keeps it for that one connection and never shows it to anyone.
- **Scope**: what the connection brings in, such as a Jira project, a Linear team or a Trello board.
- **Mapping**: how the tracker's statuses, priorities, people and structure become By Dawn's. By Dawn proposes one and you
  correct it.
- **Sync window**: the period, up to 180 days, during which By Dawn and the tracker keep each other up to date.
- **Field owner**: the side whose value wins when a synced field was changed on both sides at once.

## Import once, or keep syncing

**Import once** copies everything over and stops. The tracker is left as it is, and each By Dawn ticket keeps a link
back to the item it came from.

**Keep syncing** does the same first import, then keeps both sides in step until the end date you pick, so the
team can move over gradually rather than all on one day. You choose:

- **Pull only**: changes in the tracker reach By Dawn; changes in By Dawn stay in By Dawn.
- **Both ways**: changes flow in both directions, including new comments and, for one connection per project,
  new tickets.

A sync ends on its date, at most 180 days ahead. You can move the date later, but you can't restart a sync that
has ended (see [Ending a sync](#ending-a-sync)), so pick a date with some slack. A file import is always import
once, because there's nothing on the other side to keep in step with.

## Before you start

- You need to be a **project admin** or an **org admin**. An import writes tickets for everyone on the project,
  so other members see existing imports but can't start one.
- **Jira, Linear, GitLab, Asana and Trello** connect through By Dawn's app on that tracker: you choose **Connect**,
  approve By Dawn on the tracker's consent screen, and come back connected. There's no token to paste. Approving the
  app needs an **org owner or admin**, because the grant is the organization's. If you're a project admin, ask an
  org admin to connect it on the page, then finish the setup yourself.
- **Azure DevOps** and **GitHub Issues** use the connection your organization already has with By Dawn. Your org needs
  to have connected Azure DevOps, or installed the By Dawn GitHub App, first.
- The project's board should already have the columns you want. An import never creates a column.

## Set up an import

The whole setup is one page, **Bring work in**, with a live preview of a real item on the right that updates as
you choose.

1. Open the project's **Settings › Import & sync** and choose **New import**.

2. **Pick the source.** Choose your tracker, then choose **Connect** (or **Use it** for Azure DevOps and
   GitHub). The tracker opens in a new tab and asks you to approve By Dawn. Once you do, it sends you back and the
   page shows the account By Dawn is connected to, such as a Linear workspace or a Jira site. Your tracker's page says
   what the tracker asks you to approve.

   If the page says a tracker "isn't set up on this deployment yet", By Dawn's app for that tracker hasn't been
   configured where you are, so there's no **Connect** button. Ask whoever runs your By Dawn deployment.

3. **Pick what to bring.** Choose a project, team, board or repository, or type a query where your tracker
   supports one. By Dawn counts the items it will bring.

4. **Check how things map.** By Dawn reads the scope and proposes a mapping. Each line is a chip, such as
   `In Review → Review`. Click any chip to change it. See [How mapping works](#how-mapping-works).

5. **Choose whether to keep syncing**, and if so, the direction and the day it stops.

6. Choose **Run dry run**. It writes nothing, and reports how many tickets, comments and attachments would
   come over, and anything left to fix.

7. Choose **Import**. It runs in the background, so you can leave the page. The settings section shows its
   progress.

You can choose **Save as draft** at any point and finish later with **Continue setup**.

## How mapping works

By Dawn proposes every line of the mapping from the tracker's own data, so most imports need only a check. A value
left unmapped **blocks the import** rather than landing somewhere by default, because a silent default is how
work goes missing. The dry run lists each one.

### Statuses become columns

Each status in the tracker lands in one of the project's existing columns. By Dawn proposes a column with the same
**role** (backlog, to do, building, review, completed), from the status's category where the tracker has one,
or from its name where it doesn't: "Done" or "Shipped" proposes a completed column, "QA" a review column, "Doing"
a building column, "Icebox" the backlog.

Items the tracker marks canceled, removed or "not planned" land in a completed column too, with a
`resolution:<value>` label so they stay findable and aren't counted as finished work.

### Priorities

Jira, Linear and Azure DevOps priorities map to Urgent, High, Medium and Low by default. GitHub, GitLab, Asana and
Trello have no priority of their own, so their tickets come in with no priority unless your tracker's page says
otherwise. Any priority By Dawn can't place, such as a custom Jira priority, needs you to map it.

### People

A person in the tracker becomes the ticket's assignee when their email matches a member of your By Dawn organization.
Where the tracker hides emails (Trello always, and Jira and GitHub depending on privacy settings), pair people by
hand in the mapping. Anyone left over keeps their name on the ticket, unassigned. **No one is invited or
created**, and unpaired people only warn, they never block. Pair them later and the next pass assigns their
tickets.

When an item has several assignees, the first becomes the By Dawn assignee and the rest are kept on the ticket.
Comments keep their original author's name ("Jane Doe · from Jira"), because that person didn't write them in
By Dawn.

### Structure

- **Epics.** Epic-like items become By Dawn epics: Jira epics, Azure DevOps epics and features, Linear projects and
  GitLab epics. The tickets under them join the epic.
- **Sub-tasks** become sub-tickets. By Dawn nests one level (epic, ticket, sub-ticket), so deeper trees are flattened,
  and the lost parent is kept as a related link.
- **Types** become labels such as `type:bug`. You can turn that off.
- **Links** become relations: blocks, duplicates or related. A link to an item outside the scope is kept on the
  ticket as a reference, and becomes a relation if a later pass brings that item in.
- **Sprints and iterations** can become cycles, labels such as `sprint:Sprint 14`, or nothing. Only active and
  future sprints join a cycle, and By Dawn never creates a cycle for them.
- **Milestones** (GitHub and GitLab) become milestones in one epic, or labels such as `milestone:v2`.
- **Labels** map to your org's labels by name. Ones you don't have yet are created as the import needs them,
  unless you turn that off. The dry run counts them first.

Anything By Dawn has no field for, such as custom fields, original dates and the reporter, is kept on the ticket in
its import details. It's never added to the description.

## What an imported ticket is

Each item becomes a new By Dawn ticket with its own identifier, such as `SAW-412`. The tracker's key isn't reused
as the identifier or added to the title. Instead the card shows where the ticket came from as a chip
("Jira · PROJ-123 ↗") that opens the original, and the ticket's timeline starts with "Imported from Jira
PROJ-123".

An import is bookkeeping, not new work, so imported tickets **don't start agents, don't notify anyone and don't
count in Insights or release notes**. That holds for every change a sync pulls in later too: a ticket that moves
into a building column because someone moved it in Jira doesn't start a worker. What your team does in By Dawn after
the import counts as usual.

## While a sync runs

By Dawn checks the tracker every few minutes, and sooner when the tracker tells it something changed. By Dawn sets up
those signals (webhooks) itself when a sync starts, so there's nothing to configure in the tracker. A change
usually reaches By Dawn within a minute. If a signal is missed, the next check still picks it up, within about five
minutes.

### When both sides change the same field

The synced fields are the title, description, status, priority, assignee, labels and due date, plus comments. When
only one side changed a field, that change wins, whichever side made it. When **both** sides changed it between
checks, the field's **owner** wins. While a sync runs, the tracker owns the status and By Dawn owns everything else,
so a ticket's column follows the tracker and its other fields follow By Dawn.

The value that lost isn't thrown away. The ticket shows "1 sync conflict", and its **Synced with** section shows
both values. Choose **Use Jira's value** (or By Dawn's) to apply the other one, or **Dismiss** to keep what won.

New comments flow both ways and never conflict.

### Pausing and fixing problems

From **Settings › Import & sync** you can **Pause** a sync and **Resume** it. While it's paused nothing moves in
either direction; on resume By Dawn compares both sides and catches up on what changed in the meantime. A paused sync
still ends on its date.

If By Dawn can't reach the tracker, for example because someone removed By Dawn's app from the tracker or the board was
deleted, the connection shows **Needs attention** with the reason. Fix it (for a removed app, choose **Connect**
again to give a new grant), then choose **Resume**. Problems with single items,
such as an attachment that's too large or a status with nowhere to go, are listed under the connection with
**Retry** and **Dismiss**, and never stop the rest.

To change the mapping, choose **Edit mapping**. A new mapping applies from the next pass, and tickets already
imported stay as they are.

## Ending a sync

A sync ends on its date. To keep it going, choose **Edit mapping**, move **Sync until** later (at most 180 days
from today) and choose **Save mapping**. To stop early, choose **End now**, then **End for good**.

When a sync ends:

- By Dawn makes one last check, and sends any By Dawn changes made before the end;
- the webhooks By Dawn set up come off the tracker, and By Dawn gives up the connection's app grant;
- every imported ticket stays, with its link back to the tracker and its import details. It just stops
  updating.

> **An ended sync can't be restarted:** A new connection to the same scope creates **new** tickets, because it doesn't take over the old ones. If you
> might need more time, move the end date before it passes.

Deleting or archiving a ticket on either side never deletes it on the other. Its link is detached and it stops
syncing.

## Your tracker's page

- [Jira](https://docs.bydawn.com/import-jira/)
- [Linear](https://docs.bydawn.com/import-linear/)
- [Azure DevOps Boards](https://docs.bydawn.com/import-azure-devops/)
- [GitHub Issues](https://docs.bydawn.com/import-github-issues/)
- [GitLab](https://docs.bydawn.com/import-gitlab/)
- [Asana](https://docs.bydawn.com/import-asana/)
- [Trello](https://docs.bydawn.com/import-trello/)
- [CSV or JSON file](https://docs.bydawn.com/import-file/)

Source: https://docs.bydawn.com/import-and-sync/