Import from Jira

You can move a Jira Cloud project into an Orbit project together with its comments, work logs and history.

What you need

Permission to administer the Orbit project you import into. Only project administrators can start a Jira import.
A file to import: a Jira Cloud export file (up to 2,000 work items and at most 10 MB per file), or a plain CSV exported from Jira (see Smaller moves with CSV).

1. Prepare the file

A plain CSV exported from Jira you can prepare yourself. A Jira Cloud export file that carries every comment, work log and history entry is made with jira-export, an open-source Python script published at github.com/Orbit-Inortix/jira-export. It reads the project through the Jira Cloud REST API with your Atlassian API token, which is sent only to your Jira site. If you prefer, contact us for an assisted migration and we prepare the file with you.

export JIRA_API_TOKEN='<your Atlassian API token>'
python3 jira_export.py --site https://acme.atlassian.net --email you@acme.com --project ACME --attachments jira-ACME-files

Larger projects are split into several files, each under the limit, with parents first. Upload them in the order they were written.

2. Run the import wizard

Open Project settings → Import. The wizard has four steps.

File. Choose the file. A Jira Cloud export is up to 10 MB, and a plain CSV is up to 5 MB. Tick create missing components, versions, sprints if you want Orbit to create them. Without it they are left out. Open (active or future) sprints are created as planned.
Fields. Check how each column maps to an Orbit field. Summary is required, and each single-value field can be mapped once. Choose what happens with duplicates: skip, update or create, and what happens with failing rows: skip them or stop.
Check. Orbit runs every row and rolls it back, then shows the counts and the problem rows. Nothing is written yet. For a Jira file it also shows the compatibility report.
Import. The import runs in the background and you see its progress. You can pause, resume or cancel it. If it stops at a bad row, the page names the row and offers to skip failing rows and resume. When it ends, failed rows are listed and can be downloaded as a CSV with an Import error column.

An import can be reopened at its step, and the project lists its recent imports.

What is matched and what is not carried

The compatibility report lists what Orbit made of your file: how statuses, types and priorities were matched, which people did not match, which custom fields were mapped, what was created, what is missing, what was carried (comments, work logs, links, history, attachments listed) and what was not.

What	How Orbit handles it
Statuses	Matched by name or alias, otherwise to the first status of the same category. Not created.
Work types	Matched by name, otherwise by hierarchy level. Not created.
Priorities	Matched by name, otherwise the classic names.
People	Matched by e-mail, otherwise by a unique name. Unmatched people are listed with counts.
Custom fields	Mapped to the Orbit custom field of the same name when there is one.
Description	Converted to Markdown from Jira’s rich text. Unsupported rich text nodes are counted in the report.
Comments and work logs	Added at their Jira time, once per Jira id. When a site administrator runs the import, they are authored by the matched person, otherwise by the importer. Comments limited to a role or group in Jira are restricted to the importer and project administrators.
Links	Links between work in the import are made (blocks, duplicates, clones, otherwise relates).
History	Added as imported activity at its original time, named `Jira: <field>`. Reports and JQL history keep to Orbit’s own changes.
Keys	The Jira key is kept as an old key when the project keys differ.
Not carried	Workflows, screens, schemes, boards and filters.

Imported work items also record their origin, which you can read on the work item.

Attachments

Attachment files follow after the import has run. Orbit lists the attachments in each work item’s origin. jira_export.py --attachments downloads them, and jira_attachments_upload.py from the same repository sends them to Orbit with a personal API token with write scope of a project administrator. Each file goes through the rules of any upload: a safe file name, content check, 1 byte to 10 MiB, at most 100 attachments per work item, and no executables. Sending the same file again does not copy it twice.

Smaller moves with CSV

For smaller moves you can import a plain CSV. The wizard accepts a UTF-8 file of up to 5 MB with a header and 1 to 2,000 rows, suggests a column mapping, and recognises Jira column headers. A Summary column is required. The sprint column is never suggested because Jira CSV exports repeat closed sprints.