Importing from a CSV file

Bringing tickets in from a spreadsheet or from any tracker that exports one: Trello, Asana, Linear, GitHub, Zendesk, or a Jira issue export.

Most trackers can export their work as a CSV file, and every spreadsheet can save one. Alba Ticket reads such a file into one project: one row becomes one ticket, with its status, type, priority, people, labels, dates and comments where the file has them. Use it to import from any system that Alba Ticket has no dedicated importer for, and the way to load a list of tickets somebody kept in a spreadsheet.

This page describes the import itself. There is a page for each tracker people most often leave, saying how to export from it and what its file holds: Trello, Asana, Linear and Zendesk. Jira has its own importer that reads a full backup, and so do GitHub and GitLab; a Jira issue export as CSV works here too. Time entries from another tracker are a different file and a different page: importing time from a CSV file.

A CSV file holds less than a backup does. There is no workflow, no history of changes and no attachments, and a person is only a name or an email address. What the file does hold is kept whole: the entire row is stored with the ticket as its original record, and any column you leave unmapped can be kept as a field of the project.

What you need

  • A CSV file whose first row holds the column names. Commas, semicolons and tabs all work; the separator is read from the first line.
  • The file, uploaded from this page. It is kept in the workspace's storage for a day, so the import can be run again from the same analysis; the workspace needs a storage location for it.
  • The project it goes into, or a key and a name for a new one.

Step 1: read the file

Under Administration, CSV import, upload the file. It is read once, and its page shows the first rows, how many there are, and a suggested mapping of its columns onto ticket fields. Nothing is written.

Step 2: map the columns

Say which column feeds which field. The suggestion recognises the names Jira, Trello, Asana, Linear, GitHub and Zendesk write, so it is usually right; change what is not. Only the summary needs a column.

  • Key or number: a key like PROJ-12 or a bare number keeps its number when the project has not used it, so tickets keep the numbers people know. Anything else is kept as the ticket's original id.
  • Type, status, priority, resolution: matched to what the workspace already has by name, and created when missing. A new status gets the category its name suggests (Done is done, In Review is in progress, anything else is to do), and every status in the file is added to the project's workflow, reachable from any other, so no ticket lands where its workflow cannot see it. The page shows the values a column holds, so you can see what will be made before it is.
  • Reporter and assignee: an email address matches a person by email; a name matches by username or display name; anyone unknown becomes a placeholder, so tickets stay attributed. Tick activate people with an email address to make them members who can log in straight away. A row without a reporter belongs to whoever ran the import.
  • Labels: several in one cell (design, marketing) or one per column, as Jira writes them.
  • Comments: one per column. A Jira export's date;author;body cells keep their date and author; anything else is a comment by the reporter at the ticket's creation.
  • Created, updated, resolved, due: ISO 8601 dates, 2024-03-01 09:00, Jira's 01/Mar/24 9:00 AM and Mar 1, 2024 are all read. A date made only of digits with slashes is not, because 1/3/2024 means a different day in different countries; those are left empty and counted in the report.

Choose what the descriptions and comments are written in: Markdown, plain text, HTML or Jira wiki markup. A Jira issue export holds wiki markup. Tick keep unmapped columns as fields to turn every column the mapping does not use into a text field of the project, named after the column.

Step 3: import

Dry run first, if you like: the whole import runs inside a transaction that is rolled back, and the report shows what it would have done. Then import. The import goes in stages: project, vocabulary, people, tickets, verification. Each records what it created, matched, left unchanged or skipped, and the verification stage compares the rows in the file with the tickets made from them.

The import is idempotent. Running the same file again changes nothing, and a run that stops continues where it left off, because every row is remembered by its key or its row number.

After the import

  • Tickets carry the file's original row as their imported record, and the import run's report lists anything that needs attention: dates that could not be read, rows that could not be imported, and workflows that gained statuses.
  • Placeholder people are claimed on their first login or invitation, like people imported from Jira.
  • Fields made from unmapped columns are ordinary custom fields and can be renamed or archived.