Migración desde Jira

Zentto Pulse incluye un importador total de Jira: trae proyectos completos de Jira Cloud a Pulse para que la ficha de cada tarea viva en Pulse sin necesidad de abrir Jira. La migración es idempotente y re-ejecutable — puedes correrla las veces que quieras y solo se actualiza lo que cambió.

Para usuarios

¿Qué se migra?

Todo lo que tu equipo construyó en Jira pasa a Pulse:

De Jira	En Pulse
Épicas	Épicas operativas
Tareas, historias y bugs	Tareas del tablero
Subtareas	Subtareas (conservan su tarea padre)
Sprints	Sprints
Comentarios	Comentarios (con su autor)
Historial de cambios	Actividad del item
Adjuntos	Adjuntos
Tiempo trabajado (worklogs)	Tiempo trabajado
Personas (asignados, reportadores, autores)	Directorio de personas
Enlaces entre tareas (bloquea, duplica, se relaciona…)	Enlaces entre items
Estructura del proyecto (estados, prioridades, componentes, versiones, boards, campos custom)	Estructura del proyecto

También se conservan estado, prioridad, etiquetas, story points, fechas y estimaciones de cada tarea.

¿Puedo repetir la migración?

Sí. La migración es idempotente: si la vuelves a ejecutar, Pulse reconoce lo que ya importó y solo actualiza los cambios — no se duplican tareas, comentarios ni adjuntos. Esto permite migrar por etapas (por ejemplo, un proyecto hoy y el resto la próxima semana) o refrescar los datos mientras el equipo termina de mudarse.

¿Cómo la ejecuto?

Hoy la migración la ejecuta el equipo técnico o tu partner de implantación (ver la sección para desarrolladores). El asistente visual de migración — donde podrás conectar tu Jira y elegir proyectos desde la propia app — llega pronto.

Para desarrolladores

Endpoint

POST /v1/admin/import/jira — protegido con la API key maestra del servicio (header x-api-key, solo server-to-server; nunca desde navegador). Definido en src/routes/admin.ts del repo zentto-pulse y documentado en su contrato OpenAPI (contracts/openapi.yaml).

Las credenciales de Jira (baseUrl, email, apiToken) viajan solo en el request y no se persisten. Nunca las incluyas en repos, tickets ni documentación.

{
  "tenantId": "mi-tenant",
  "baseUrl": "https://mi-sitio.atlassian.net",
  "email": "[email protected]",
  "apiToken": "<token de API de Jira — nunca versionarlo>",
  "allProjects": true,
  "includeAttachments": true,
  "updatedSince": "2026-01-01"
}

Flags principales

Flag	Default	Efecto
`projectKey` / `projectKeys[]`	—	Un proyecto o lista de proyectos (máx. 50)
`allProjects`	`false`	Descubre e importa todos los proyectos del sitio
`includeAttachments`	`true`	Descarga adjuntos (límite por archivo con `maxAttachmentMb`)
`updatedSince`	—	Import incremental: solo issues actualizados desde `YYYY-MM-DD`
`dryRun`	`false`	Simula sin escribir en BD
`includeComments` / `includeWorklogs` / `includeChangelog` / `includeLinks` / `includeSubtasks` / `includeStructure` / `includeRemoteLinks` / `includeWatchers`	`true`	Apagan partes del import
`maxIssues`	—	Tope de issues por proyecto (1–10000)

La respuesta devuelve totales por proyecto y agregados (epics, items, subtasks, comments, worklogs, changelog, attachments, sprints, persons, links, structures, skipped, errors).

Mapeo de entidades

Epic (Jira) → pulse."OperationalEpic" — con StatusName, Priority, Labels (JSONB), ProjectKey y JiraUpdatedAt.
Issue / Story / Bug / Sub-task (Jira) → pulse."EpicItem" — con IssueType, StatusName, Priority, Labels, StoryPoints, StartDate, ReporterRef, Resolution, ResolvedAt, OriginalEstimateSec, TimeSpentSec y ParentItemId (autorreferencia para subtareas).
Changelog (Jira) → pulse."ActivityLog" — una fila por history, deduplicada por JiraId.

Tablas de soporte

Tabla	Contenido
`pulse."Person"`	Directorio de personas vistas en el import (assignee/reporter/autores), única por `(TenantId, ExternalId)`
`pulse."ItemLink"`	Enlaces entre items (`Blocks`, `Duplicate`, `Relates`, `Cloners`…), dirección src→dst
`pulse."Attachment"`	Adjuntos: contenido en BD (`BYTEA`) o solo metadata + URL externa
`pulse."Worklog"`	Tiempo trabajado por item (base de facturación/costos)
`pulse."ProjectMeta"`	Estructura del proyecto/sitio: estados por tipo de issue, componentes, versiones, boards, prioridades, tipos de link y campos custom (`ProjectKey = '_site'` para catálogos globales)

Idempotencia

Cada entidad importada guarda su identificador de origen — JiraKey (épicas e items) y JiraId (comentarios, worklogs, adjuntos, links, changelog) — con índices únicos parciales por (TenantId, JiraId). Re-ejecutar el import hace upsert: actualiza lo existente y agrega lo nuevo, sin duplicados.

Migraciones de BD

El esquema vive en el repo zentto-pulse como migraciones Goose:

migrations/postgres/00010_jira_full_migration.sql — columnas Jira en EpicItem/OperationalEpic/ActivityLog y tablas Person, ItemLink, Attachment, Worklog.
migrations/postgres/00011_jira_project_structure.sql — tabla ProjectMeta y funciones pulse.usp_pulse_projectmeta_* (estructura del sitio/proyecto, semilla para workflows configurables).