CSV import and export

CSV is the plain way to move work into Orbit and out of it. Import suits a project administrator or a member who creates work and has a spreadsheet to load. Export suits anyone who needs a list of work items in a spreadsheet. To move a whole project from Jira, see Import from Jira.

Import a CSV

The import wizard works on one project. Orbit checks every row before it writes anything.

File. Choose a UTF-8 CSV of up to 5 MB, with a header row and 1 to 2,000 rows of at most 200 columns. A byte order mark is ignored.
Fields. Orbit suggests a field for each column and recognises the column headers of a Jira CSV export. Check the mapping and change it. Choose what happens with duplicate rows and with failing rows.
Check. Orbit runs every row through the same rules as the real import, then rolls back. It shows counts to create, update, skip and fail, and lists up to 200 problem rows with the column and the message. Nothing is written.
Import. Orbit imports in committed batches in the background. You can pause, resume and cancel. A restart does not make anything twice.

Fields you can map

Field	Notes
Summary	Required
Description, type, status, priority	Status names resolve inside the project and must belong to the work type’s workflow. An empty status cell uses the workflow’s initial status.
Assignee, reporter
Labels, components, fix versions	Several columns can map to the same one of these three fields
Due date, start date, story points
Parent, epic	Parents and epics named in the file are imported before their children
Sprint	The name of an open sprint of the project. It is never suggested, because Jira CSV exports repeat closed sprints.
External id	Used to recognise rows that an earlier import of the same source already created
Custom fields	Any custom field of the project

Duplicates and failing rows

Duplicates. A row whose external id an earlier import made is skipped, updates that work item, or creates a new one.
Failing rows. The import can skip a failing row or stop at it. A stop names the row and offers to skip failing rows and resume.

After an import, the failed rows are listed with the reason and can be downloaded as a CSV with an added Import error column. Fix that file and import it again. Row numbers count rows after the header.

Who can import

People who can create work in the project can import a CSV. A project administrator sees all imports of the project, the latest 20. Other people see their own.

Export work items

You can export from the list or from a search result.

Visible columns gives the key, the summary and the columns you use in the list.
All fields gives every built-in field and the applicable custom fields, named by their field names.

An export holds up to 5,000 work items that you may read. If it was cut, the response says so. The file is a UTF-8 CSV with a byte order mark. Its name holds the project key, the date and time, and part of the export id.

Spreadsheet formulas are neutralised

A cell that a spreadsheet could run as a formula gets a leading apostrophe. That covers cells starting, after spaces, with =, +, - or @, their full-width forms, a tab or a carriage return.

Every export is recorded

Orbit records each export before it sends the file. The record holds who made it, the query or selection, the columns, the number of rows, whether it was cut and a digest of the file. You can list your own exports. Site administrators see everyone’s. Given a file, Orbit can find the export that produced it by its digest.

Use the API

The import and export are also available through the API at https://acme.orbit.inortix.com/api/v1. A simple one-request import exists too. It is atomic and holds up to 1,000 work items. It requires a Summary column and accepts Description, Type, Status, Priority, Story Points and Labels.

Task	Request
Export a selection	`POST /exports/issues` with `columns` set to `visible` or `all`, and either `jql` or `issueIds`
List your exports	`GET /exports`
Create an import from a file	`POST /imports`
Check, run, pause or cancel	`POST /imports/{id}/check`, `/run`, `/pause`, `/cancel`
Failed rows	`GET /imports/{id}/failed.csv`

Import conflicts answer 409 with a code such as import_not_checked, and a bad mapping answers 400 invalid_mapping. See Error codes.