# Import from a tracker

The import moves a team onto Andon from Trello, Jira, Linear or Asana in one go, with everything it has there: issues, sub-tasks, comments, files, statuses, people, sprints, versions and custom fields. You see a dry run of
what it will make before anything changes, and you can run it again later: it updates what it made and never
duplicates it. An Asana import can also stay in sync afterwards.

To bring in a few issues, or keep pulling a Linear backlog in as it grows, use the board's **Import** button and
Linear's import rules instead: see [Integrations](https://andon-docs.pages.dev/guide/integrations.md).

Owners and admins run imports. The page is off Settings' menu: search Settings for **Import from a tracker**, or open
**Settings → Connections**, press **Add** beside **Add a connection**, and choose **Import from a tracker, once**.

## Before you start

| Source | Reads from | What you need |
|---|---|---|
| Trello | the API, or the board's JSON export | for the API, and to copy files, a [Trello connection](https://andon-docs.pages.dev/guide/integrations.md#trello). Export: the board's menu → **Print, export and share** → **Export as JSON** |
| Jira | the API, or an export file | for the API, a [Jira connection](https://andon-docs.pages.dev/guide/integrations.md#connect-linear-or-jira). Export: **CSV (all fields)**, or **XML** (Jira Server and Data Center) |
| Linear | the API | a [Linear connection](https://andon-docs.pages.dev/guide/integrations.md#connect-linear-or-jira) |
| Asana | the API | an [Asana connection](https://andon-docs.pages.dev/guide/integrations.md#asana) |

A Jira export names people by username, since it carries no email addresses. An XML export brings sprints with their
dates; a CSV export brings sprints as labels. Jira writes 1,000 issues per XML export by default, and the import warns
when the file is shorter than the search, so export the rest in more files.

## Run an import

1. Under **New import**, pick where it comes **From**: the source, and the board, project or team in it. For an export,
   choose the **Export file**.
2. Press **Read and plan**. Andon reads the source once: an upload at once, an API source in the background. Nothing is made
   yet.
3. Read the **dry run**: what the import will make and update, per kind (cards, sub-tasks, comments, files, links,
   statuses, projects, cycles, milestones, custom fields, templates, relations and former members). It changes as you
   change the choices below.
4. Map it:
   - **Team**: a new team named after the source, or one you have. A new team takes the source's key when it's free
     (`ENG` for Linear's ENG).
   - **Statuses**: each source status lands on one of the team's statuses, matched by name, or on a new status. Ready
     is never offered: an import starts no run.
   - **People**: each person is matched to a member by email, else by a unique name, or becomes a **former member**.
   - **Keys**: **The team's numbers** (`ENG-42` becomes `WEB-1`), or the tracker's numbers where they're free in the
     team (`ENG-42` becomes `WEB-42`). Either way the old key keeps working in links, ⌘K and the CLI.
   - **Epics** (Jira): **Projects** of the team, or **Parent cards**.
   - **Checklists** (Trello): **Sub-tasks**, or **In the notes**.
   - **Issue types** (Jira): **Labels**, or **Card templates**, where each type (Bug, Story …) maps to one of the
     team's [card templates](https://andon-docs.pages.dev/guide/templates-and-bulk-edit.md) or a new empty one named after it.
   - **Archived items** come archived, or not at all (the default). **Copy files** is on by default.
5. Press **Import N cards**, then **Import** to confirm. It runs on the server and the page shows progress; you can
   leave the page and it carries on.
   **Cancel** stops it after the card it is on.
6. Read the **report**: what was made and updated, what failed and why, and what the source couldn't give.

Run it again any time with **Import again**. It updates what it made only where nobody has changed it on the board since, and never moves
a card: the board's columns are the board's. A card someone deleted on the board isn't brought back.

## What becomes what

| Trello | Jira | Linear | Andon |
| --- | --- | --- | --- |
| board | project | team | a team (a Trello board is also a project of it) |
| list | status | workflow state | a team status, on a column |
| card | issue | issue | a card, linked to its issue |
| checklist item | sub-task | sub-issue | a sub-task |
| label | label, issue type | label | labels (issue types: labels or card templates) |
| member | assignee, reporter | assignee, creator | the card's owner, or its former assignee |
| comment | comment | comment, with threads | a comment, its date kept |
| attachment | attachment | upload, attachment | a file (copied) or a link |
| custom field | custom field | none | a custom field of the team |
| none | sprint | cycle | a cycle |
| none | fix version | project milestone | a milestone |
| none | story points | estimate | the estimate |
| none | epic | project | a project (Jira: or a parent card) |
| none | issue link | relation | *blocks* becomes a dependency; *duplicates* and *relates* become relations |

Priorities: Linear's urgent, high, medium and low, and Jira's highest to lowest, become urgent, high, low or none.
Jira's Medium, its default, is none.

With **Card templates** for issue types, each card is filled from its type's template once: the issue's own values
win, the template fills what the issue left empty, adds its labels and notes, and makes its sub-tasks.

## Asana

Asana reads through its API. **From** lists the teams the connection can see, by workspace (a workspace without teams
is read whole). A team is read whole, or press **Pick projects** to choose some (up to 200).

Asana has no bulk read, so a team takes a while: about half an hour for 2,000 tasks. What it maps to:

| Asana | Andon |
| --- | --- |
| team (or the workspace, when it has none) | a team; it has no key, so one is suggested from its name |
| project | a project, with its status and dates |
| section | a status, one per name across the team's projects, on a column guessed from its name ("In progress" → Working, "In review" → Review, "Done" → Done, "Backlog" → Backlog, else Next) |
| task | a card in its first project; a task in two projects comes once |
| subtask, at any depth | a sub-task |
| completed | Done |
| milestone task | a milestone of its project |
| approval task | a card of type *Approval* |
| tag | a label |
| *Priority* field | the priority |
| *Story points*, *Points* or *Estimate* field | the estimate |
| other custom fields | custom fields |
| comment | a comment; Asana's system stories (assigned, moved …) are dropped |
| attachment | Asana's own files are copied; Drive, Dropbox and Box links stay links |
| dependency | a dependency |

Not brought over: portfolios, goals, likes, time tracking, and an approval's approved or rejected state beyond being
completed.

### Keep an Asana import in sync

A finished Asana import has **Keep in sync with Asana**. Turn it on, and Asana's changes reach the board as they
happen: titles, notes, priority, estimate, due date, labels and fields where nobody changed them on the board, new
comments and files, sub-tasks and dependencies. A new task becomes a new card in the Backlog. A card never moves
column because of the sync.

- Asana must reach your board at a public https address.
- At most 50 of the import's projects are synced. A project Asana refused shows *Failed* with Asana's reason; turn
  sync off and on to try again.
- Not synced: a task deleted in Asana (its card stays), and renamed sections or projects.
- Turning it off removes the subscriptions at Asana.

The other direction, the board's changes going back to Asana, is the Asana connection's
[write-back](https://andon-docs.pages.dev/guide/integrations.md#write-back). With both on, a task and its card stay in step both ways. How the sync is
doing is under [Asana sync health](https://andon-docs.pages.dev/guide/integrations.md#asana-sync-health).

## People who aren't on the board yet

Anyone the tracker names who isn't a member becomes a **former member**: their name shows on the cards and comments
they had, and their email stays private.

Owners and admins can **Invite** a former member the tracker gave an email for (from the report, the People mapping,
or **Settings → Workspace → People → People from imports**), and link one to an existing member whose address
differs. See [People and roles](https://andon-docs.pages.dev/guide/people-and-roles.md#people-from-an-import).

## Limits and files

- Up to 10,000 issues, 500 comments and 50 files an issue; the report names what was left out.
- Files are copied up to 25 MB each, only from the tracker's own hosts. A bigger one, or one elsewhere (a Jira Server's
  files in an XML export), stays a link, and the dry run counts it as one. A failed download is named in the report and
  tried again on the next run.
- Without a Trello connection, a Trello export's files come as links.
- Imported cards never start a run, and recipe picking isn't asked for each one.
- Every import is in the audit log.

## See also

- [Integrations](https://andon-docs.pages.dev/guide/integrations.md): connections, write-back and importing a few issues at a time.
- [Integrations internals](https://andon-docs.pages.dev/contributing/integrations-internals.md): how the import job runs.
