# Import from a CSV or JSON file

> Import any tracker's CSV or JSON export into By Dawn, and get its columns recognised so titles, statuses, people and parents land in the right place.

This page helps you bring work into By Dawn from a tracker that has no connector of its own, or from a spreadsheet.
At the end each row of your file is a By Dawn ticket. [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 a file.

A file is always imported once. There's nothing on the other side to keep in step with, so there's no sync.

## Before you start

- You need to be a project admin in By Dawn. No token is needed.
- Export from your tracker as **CSV** or **JSON**, up to **64 MB**.

## Upload

1. In By Dawn, open **Settings › Import & sync › New import** and pick **CSV / JSON**.

2. Choose **Choose file** and pick your export. By Dawn reads its headers and proposes which column feeds which
   field. Choose **Replace file** to use a different one.

3. Map the statuses and priorities the file uses, run the dry run, and choose **Import**.

## What By Dawn reads

**CSV** files may use a comma, semicolon or tab between values; By Dawn uses whichever the header line has most of.
Quoted values may contain that separator and line breaks. A column header that repeats, such as Jira's several
`Labels` columns, is read as one column with several values.

**JSON** files hold an array of objects, or an object holding exactly one such array, such as
`{"issues": [ … ]}`. Nested objects are read as dotted names, such as `fields.summary`.

If a row can't be read, the import stops and names the line or item, so you can fix the file and try again.

## How columns are recognised

By Dawn matches headers by name, ignoring case, spaces and punctuation, so `Issue key`, `issue_key` and `IssueKey`
are the same. The exports of Jira, Linear, Azure DevOps, GitHub, Asana and Trello are recognised as they come. For
any other file, rename the headers to one of the names below before you upload.

| Field | Headers By Dawn recognises |
| --- | --- |
| Title (required) | Summary, Title, Name, Card name, Task name, Subject |
| ID | Issue ID, ID, Work item ID, Task ID, Card ID, External ID, GID, UUID, Number |
| Key | Issue key, Key, Identifier |
| Description | Description, Body, Notes, Card description, Details, Content |
| Type | Issue type, Work item type, Type, Task type, Kind |
| Status | Status, State, Section/Column, Section, Column, List name, List, Stage |
| Priority | Priority |
| Assignees | Assignee, Assignees, Assigned to, Members, Owner |
| Reporter | Reporter, Creator, Created by, Author, Opened by |
| Labels | Labels, Label, Tags, Tag |
| Parent | Parent, Parent ID, Parent issue, Parent task, Parent key |
| Epic | Epic link, Epic, Epic key |
| Estimate | Story points, Estimate, Points, Effort |
| Due date | Due date, Due, Due on, Deadline |
| Created, Updated | Created, Created at, Created date; Updated, Updated at, Changed date, Last modified |
| Link | URL, Card URL, HTML URL, Web URL, Link, Permalink |
| Resolution | Resolution |

Each column feeds at most one field. A file with no title column can't be imported.

**Nothing is dropped.** Every column that doesn't feed a field, and any value that doesn't read (a date By Dawn can't
parse, for example), is kept on the ticket as an import detail.

## How a file maps

- **Statuses** are matched to columns by name, the same way as Trello lists (see [Import from
  Trello](https://docs.bydawn.com/import-trello/#how-trello-maps)). Rows with an empty status are grouped as **No status**, which
  you map like any other value.
- **Priorities** are mapped value by value.
- **Parents and epics.** A parent or epic cell may hold the other row's ID or its key. A row pointing at a row
  that's in the file becomes its sub-ticket or joins its epic.
- **Dates** can be ISO 8601 (`2026-10-12` or `2026-10-12T15:45:00Z`), Jira's `12/Oct/26 3:45 PM` or Azure DevOps's
  `10/12/2026 3:45:00 PM`. A time with no time zone is read as UTC.
- **People, labels and types** map as for any tracker (see [How mapping
  works](https://docs.bydawn.com/import-and-sync/#how-mapping-works)).

A file has no attachments, comments or sprints, so none come over.

## Check before you import

A file import finishes once every row is in, and the connection ends. Importing the same file again makes a new
connection, which creates a second set of tickets. So use the dry run and the live preview to check the
statuses, people and parents before you choose **Import**.

> **Note:** If your file has an ID column, every ID must be unique: two rows with the same ID stop the import rather than
> being merged into one ticket. Without an ID or key column, rows are numbered in file order.

## Where to go next

- [Import and sync](https://docs.bydawn.com/import-and-sync/): the setup steps, the dry run and what imported tickets do.

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