Importar desde Jira Cloud

Trasladá un proyecto de Jira Cloud a Orkestra preservando issues, sprints, workflow states, comentarios y adjuntos (como external links). Orkestra mapea usuarios por email y te deja invitar a los que faltan en una sola pasada.

Qué formato espera Orkestra

Un archivo JSON con la siguiente estructura mínima, armado a partir de la REST API v3 de Jira Cloud: 

{
  "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", ... } }]
}

No es el output directo de un botón de exportación — Jira Cloud no ofrece un dump nativo en este shape. Tenés que construirlo a partir de la API.

Cómo generar el export

Dos caminos:

1) Script con la REST API (recomendado)

Desde un token de API de Jira Cloud (generalo en id.atlassian.com/manage-profile/security/api-tokens), combiná estas llamadas en un JSON único:

  • GET /rest/api/3/project/{projectKey} → projects[0]
  • GET /rest/api/3/status → statuses
  • GET /rest/api/3/users/search → users (filtrá por el proyecto si es posible)
  • GET /rest/agile/1.0/board/{boardId}/sprint → sprints
  • GET /rest/api/3/search?jql=project=KEY&fields=*all (paginado) → issues

Serializá todo en un único JSON con las claves de arriba. Mantenelo por debajo de 10 MB — si tu proyecto es más grande, dividí por JQL (ej. por componente o sprint) y hacé múltiples imports.

2) Plugin del marketplace

Si no querés escribir código, buscá "JSON Exporter" o "JIRA Cloud Issue Exporter" en el Atlassian Marketplace. Tené en cuenta que el shape de esos plugins puede no coincidir exactamente con el esperado por Orkestra — vas a necesitar un pequeño script de transformación.

Tenemos un script de ejemplo en Node.js para generar el JSON esperado. Escribinos a soporte@orkestra.team y te lo pasamos.

Qué se importa

  • Projects → el primer proyecto del array. Los demás se ignoran con un warning en la preview.
  • Issues → Tasks (título, descripción, prioridad, labels, due date, estado, sprint asignado).
  • Issue Types → custom field jira_issue_type. Los issues con type "Epic" reciben además el label epic.
  • Statuses → WorkflowStates. Los que tengan statusCategory.key === 'done' quedan marcados como completados.
  • Sprints → Sprints. Estado inferido: closed → COMPLETED, active → ACTIVE, cualquier otro → PLANNED.
  • Subtasks → registros Subtask de Orkestra (siempre completed=false, el estado real no viene en el export).
  • Parent Epic → custom field jira_parent_key (Orkestra no tiene jerarquía nativa task-parent).
  • Comments → Comments. Si el autor no está en la org, el contenido se prefija con [Imported from Jira — originally by X].
  • Attachments → ExternalLink con type JIRA. No descargamos binarios (requeriría autenticación contra Jira).
  • Key del issue (ej. ORK-123) → custom field jira_id, para trazabilidad.

Mapeo de usuarios

Los usuarios se matchean por emailAddress. Si el email existe en tu organización de Orkestra, el issue se asigna automáticamente. Si no existe, la preview te lista los "missing users" y podés:

  • Ignorarlos — el issue queda sin assignee y los comentarios agregan el prefijo de autor original.
  • Invitarlos (toggle invitar usuarios faltantes) — Orkestra crea una Invitación PENDING (scope ORGANIZATION, rol VIEWER) y envía el email después del commit. Los envíos son fire-and-forget: si el SMTP falla, el import no se revierte.

Qué queda fuera de scope

  • Múltiples proyectos en el mismo JSON — solo se importa el primero. Si querés migrar varios, hacelo en imports separados.
  • Custom fields de Jira — más allá de los 3 de trazabilidad (jira_id, jira_issue_type, jira_parent_key), el resto se ignora silenciosamente.
  • Issue links — relaciones como "blocks", "relates to", "is blocked by", "duplicates" no se importan.
  • Workflow transitions — las reglas de transición, campos requeridos y DoD checklists no se migran (tenés que reconfigurarlas en Orkestra).
  • Completion state de subtasks — siempre se importa como false; Jira no expone ese dato en el shape que consumimos.
  • Watchers — no se importan.
  • Time tracking (originalEstimate, timeSpent, worklogs) — no se importa. Si usás time tracking en Jira y querés preservarlo, pedilo en soporte.
  • Jira Service Desk (SLAs, request types, portal) — fuera de scope.
  • Jira Automation rules — fuera de scope.
  • Adjuntos binarios — solo se guarda el link. Para preservar el archivo, descargalo a mano y subilo a la tarea en Orkestra.
  • Jira Server / Data Center XML backup — no soportado. Solo Jira Cloud vía REST API v3.
  • Atlassian Document Format (ADF) en descripciones y comentarios — lo aplanamos a texto plano best-effort. Tablas, macros y embeds se pierden.

Warnings vs ignores silenciosos

En la preview vas a ver warnings explícitos por: múltiples proyectos detectados, usuarios faltantes en la org, archivos muy grandes. Todo lo demás listado en "fuera de scope" se ignora sin mensaje — si esperás ver algo y no aparece, chequeá la sección de arriba antes de abrir un ticket de soporte.

Pasos en Orkestra

  1. Ir a Ajustes → Importar → Jira.
  2. Subir el JSON. Esperá la preview (pocos segundos).
  3. Revisar: nombre del proyecto que se va a crear, cantidad de issues/sprints/states detectados, lista de usuarios faltantes, warnings.
  4. (Opcional) Mapeo manual de estados: renombrar o marcar cuáles cuentan como completado.
  5. (Opcional) Activar invitar usuarios faltantes.
  6. Clic en Ejecutar. El commit es atómico (máx 60s).
  7. Una vez creado, el proyecto aparece en tu lista de proyectos.

Recursos