Import from Jira Cloud

Move a Jira Cloud project into Orkestra while preserving issues, sprints, workflow states, comments and attachments (as external links). Orkestra maps users by email and lets you invite the missing ones in a single pass.

What format Orkestra expects

A JSON file with the following minimal structure, built from the Jira Cloud REST API v3: 

{
  "projects": [{ "id", "key", "name", "description" }],
  "statuses": [{ "id", "name", "statusCategory": { "key" } }],
  "users":    [{ "accountId", "emailAddress", "displayName" }],
  "sprints":  [{ "id", "name", "state", "startDate", "endDate" }],
  "issues":   [{ "key", "fields": { "summary", "status", "assignee", ... } }]
}

This isn't the direct output of an export button — Jira Cloud doesn't ship a native dump in this shape. You have to build it from the API.

How to generate the export

Two paths:

1) REST API script (recommended)

With a Jira Cloud API token (generate one at id.atlassian.com/manage-profile/security/api-tokens), combine these calls into a single JSON:

  • GET /rest/api/3/project/{projectKey} → projects[0]
  • GET /rest/api/3/status → statuses
  • GET /rest/api/3/users/search → users (filter by project if possible)
  • GET /rest/agile/1.0/board/{boardId}/sprint → sprints
  • GET /rest/api/3/search?jql=project=KEY&fields=*all (paginated) → issues

Serialize everything into a single JSON with the keys above. Keep it under 10 MB — if your project is bigger, split by JQL (by component, by sprint) and do multiple imports.

2) Marketplace plugin

If you don't want to write code, look for "JSON Exporter" or "JIRA Cloud Issue Exporter" on the Atlassian Marketplace. Note that plugin output may not exactly match what Orkestra expects — you'll likely need a small transformation script.

We have a Node.js sample script that produces the expected JSON. Email soporte@orkestra.team and we'll share it.

What gets imported

  • Projects → the first project in the array. Others are ignored with a preview warning.
  • Issues → Tasks (title, description, priority, labels, due date, state, assigned sprint).
  • Issue Types → custom field jira_issue_type. Issues with type "Epic" also get the epic label.
  • Statuses → WorkflowStates. Those with statusCategory.key === 'done' are marked as completed.
  • Sprints → Sprints. State inferred: closed → COMPLETED, active → ACTIVE, anything else → PLANNED.
  • Subtasks → Orkestra Subtask records (always completed=false, since the export doesn't carry subtask completion).
  • Parent Epic → custom field jira_parent_key (Orkestra has no native parent-task hierarchy).
  • Comments → Comments. If the author isn't in the org, content is prefixed with [Imported from Jira — originally by X].
  • Attachments → ExternalLink with type JIRA. Binaries are not downloaded (that would require Jira auth).
  • Issue key (e.g. ORK-123) → custom field jira_id, for traceability.

User mapping

Users are matched by emailAddress. If the email exists in your Orkestra org, the issue is auto-assigned. If not, the preview lists the missing users and you can:

  • Skip them — the issue ends up with no assignee and comments get the original-author prefix.
  • Invite them (toggle invite missing users) — Orkestra creates a PENDING Invitation (ORGANIZATION scope, VIEWER role) and sends the email after the commit. Email sends are fire-and-forget: an SMTP failure won't roll back the import.

Out of scope

  • Multiple projects in the same JSON — only the first is imported. Do separate imports for more.
  • Jira custom fields — beyond the 3 traceability ones (jira_id, jira_issue_type, jira_parent_key), the rest are silently ignored.
  • Issue links — "blocks", "relates to", "is blocked by", "duplicates" are not imported.
  • Workflow transitions — transition rules, required fields and DoD checklists don't migrate (reconfigure them in Orkestra).
  • Subtask completion state — always imported as false; Jira doesn't expose it in the shape we consume.
  • Watchers — not imported.
  • Time tracking (originalEstimate, timeSpent, worklogs) — not imported. If you use it heavily and want to preserve it, ask support.
  • Jira Service Desk (SLAs, request types, portal) — out of scope.
  • Jira Automation rules — out of scope.
  • Binary attachments — only the link is kept. To preserve the file, download and upload it manually to the Orkestra task.
  • Jira Server / Data Center XML backup — not supported. Only Jira Cloud via REST API v3.
  • Atlassian Document Format (ADF) in descriptions and comments — we best-effort flatten to plain text. Tables, macros and embeds are lost.

Warnings vs silent ignores

The preview surfaces explicit warnings for: multiple projects detected, missing users, large files. Everything else in the "out of scope" list is ignored silently — if you expect to see something and don't, check the list above before opening a support ticket.

Steps in Orkestra

  1. Go to Settings → Import → Jira.
  2. Upload the JSON. Wait for the preview (a few seconds).
  3. Review: name of the project to create, counts of issues/sprints/states, missing users list, warnings.
  4. (Optional) Manual state mapping: rename or mark which count as completed.
  5. (Optional) Toggle invite missing users.
  6. Click Execute. Atomic commit (max 60s).
  7. The new project appears in your project list.

Resources