n8n-nodes-orbital-actions

Nodo de n8n para reportar progreso, steps y callbacks a Orbital desde workflows ejecutados como Actions.

v3.0.2 — Refactor interno modular + doble selector categoría→plantilla + 8 plantillas genéricas universales + URL hardcoded (zero-config).

Instalación

npm install n8n-nodes-orbital-actions

O desde la UI de n8n: Settings → Community Nodes → Install → n8n-nodes-orbital-actions.

Concepto

Cuando Orbital lanza un flujo n8n como Action, envía un payload con JWT del job (trae jobId, userId, projectId, agentId embebidos). Este nodo se usa dentro del flujo para reportar:

• Pipeline de fases al inicio (esqueleto del job)
• Progreso y steps durante la ejecución (hidratación)
• Callback de éxito/error al final
• Documentos, notificaciones, aprobaciones HITL según convenga

El dashboard de Orbital muestra todo en tiempo real (polling cada 8s).

Zero-config (v3.0.2)

El nodo no requiere configurar URLs. Apunta a producción de Orbital internamente (api.orbital.fractaliacyber.com/public/wh/*). El técnico solo configura:

1. Autenticación — JWT directo (default, con expresión al Webhook Trigger) o Credential guardado (Header Auth de n8n).
2. Campos específicos de la operación (plantilla de pipeline, título del step, etc.).

Modelo de datos

Job                                   ← workflow_jobs (1 por ejecución)
 └── Fase                             ← pipelineUi (declarada al inicio)
      └── Step (flat, sin jerarquía)  ← job_steps filtrado por phase_ref
           └── ai.tools[] (inline)    ← metadata del step AI, no substeps

3 niveles fijos, no árbol recursivo. Alineado con NIST, GitHub Actions, Airflow, Temporal.

Doble selector categoría → plantilla (v3.0.2)

El campo "Declarar Pipeline" ahora tiene 2 dropdowns:

1. Categoría del Pipeline (11 categorías):

   • Generic / Universal
   • Cybersecurity / SOC
   • Offensive Security
   • Research / Análisis
   • IT Service Management
   • DevOps / Engineering
   • Data / Analytics
   • Business Operations
   • Compliance / Legal
   • Content
   • Custom (manual)

2. Plantilla (filtrada dinámicamente por la categoría elegida).

Si la categoría es Custom, se oculta el selector de plantilla y aparece el campo para definir fases manualmente.

Plantillas disponibles

🔄 Generic / Universal (8 — NUEVAS en v3.0.2)

| ID | Nombre | Fases | |---|---|---| | generic_basic | Proceso básico | received → processing → completed | | generic_with_notify | Proceso con notificación | received → processing → completed → notified | | async_job | Job async | queued → running → completed | | request_approval | Solicitud / Aprobación | submit → review → decide → notify | | ticket_simple | Ticket / Caso simple | open → in_progress → resolved → closed | | pdca | PDCA (Deming) | plan → do → check → act | | kanban_basic | Kanban | backlog → todo → doing → done | | document_process | Procesar documento | receive → parse → extract → validate → store |

🛡️ Cybersecurity / SOC (5)

• CyberSOC NIST (Operativo L1/L2/L3)
• NIST CSF 2.0 (Estratégico)
• SOC Incident Response (Clásico)
• ISO 27001 Audit
• MITRE ATT&CK Response

⚔️ Offensive Security (2)

• Penetration Test
• Red Team Operation

🔬 Research (4)

• Deep Research, Threat Intelligence, Market Research, User Research (UX)

🎫 ITSM (2)

• ITIL Change Management, ITIL Incident Management

⚙️ DevOps (2)

• CI/CD Deploy, Bug Triage & Fix

📊 Data (2)

• ETL Pipeline, ML Model Lifecycle

💼 Business (2)

• Customer Onboarding, Sales Pipeline

📋 Compliance (2)

• GDPR DPIA, Contract Review

✍️ Content (1)

• Content Production

🛠️ Custom

• Definir manualmente

Total: 31 plantillas (8 genéricas + 22 industria + 1 custom).

Uso típico

1. Declarar Pipeline (PRIMER nodo del flujo)

[Webhook Trigger]
    ↓
[Orbital Actions]
  Operación: Declarar Pipeline
  Categoría: Generic / Universal  ▾
  Plantilla: Proceso básico        ▾
    → Envía POST /public/wh/pipeline
    → Dashboard muestra 3 fases vacías:
       - Recibido
       - Procesando
       - Completado

2. Reportar progreso y steps

[Orbital Actions]
  Operación: Reportar Progreso
  Fase: processing          ← marca como activa
  Progreso: 20

[HTTP Request: procesar datos]

[Orbital Actions]
  Operación: Reportar Step
  Fase: processing           ← dropdown autocompletado tras 1ª ejecución
  Título: "Datos validados"
  Tipo: process
  Estado: success

3. Saltar fase (opcional, early-exit)

[IF es falso positivo?]
  -> SI: [Orbital Actions] Saltar Fase: processing, Motivo: "Falso positivo"

4. Finalizar

[Orbital Actions]
  Operación: Finalizar - Éxito
  Título del Resultado: "Procesamiento completado"
  Contenido: markdown del resumen

Operaciones disponibles

Pipeline

| Operación | Uso | |---|---| | Declarar Pipeline | PRIMER nodo. Envía fases al backend desde una plantilla o custom. | | Saltar Fase | Marca una fase como saltada con motivo (early-exit, fases ya hechas, N/A). |

Progreso y Steps

| Operación | Uso | |---|---| | Reportar Progreso | Actualiza status/progress/phase del job. | | Reportar Step | Crea un step en la fase actual — 90% de casos. | | Construir Step (sin enviar) | Devuelve JSON del step para manipular con Code/Merge. | | Batch › Añadir Step al Buffer | Acumula step localmente (sin HTTP). | | Batch › Enviar Buffer | Envía todos los steps acumulados en un POST atómico. | | Actualizar Step Abierto (async) | Solo para async/loops largos — cierra un step con status=started. |

Callbacks

| Operación | Uso | |---|---| | Finalizar - Éxito | Marca job como complete. Puede crear documento. | | Finalizar - Error | Marca job como errored con categoría. | | Crear Documento | Añade un documento al centro de documentos del usuario. | | Notificar Usuario | Envía notificación visible al usuario. | | Solicitar Aprobación (HITL) | Pausa el job esperando acción del usuario. |

Autenticación

2 modos:

Autenticación: [JWT directo ▾]
  JWT: ={{ $("Webhook").item.json.body.auth.token }}   ← default, edítalo si tu Webhook se llama diferente

Autenticación: [Credential guardado ▾]
  → usa un Header Auth configurado en n8n (reutilizable entre nodos)

La URL del endpoint es constante interna del nodo — el técnico no la configura. Apunta a producción (api.orbital.fractaliacyber.com/public/wh/*). Si en el futuro se añaden entornos dev/lab se expondrán como dropdown interno.

Dropdown dinámico de fases

Tras ejecutar Declarar Pipeline al menos una vez, el campo "Fase del Pipeline" de steps y skip se autocompleta con las fases declaradas. Se guarda en workflowStaticData.orbitalPipelinePhases y persiste entre ediciones del workflow.

En la 1ª ejecución el dropdown está vacío — el técnico escribe el ref de la fase manualmente, o deja "(auto)" para que el backend lo asigne a la fase activa (currentPhaseRef).

Arquitectura del paquete (v3.0.2)

Refactor modular — cada responsabilidad en su archivo:

src/nodes/Orbital/
├── OrbitalActions.node.ts       (slim — clase + execute orquestador)
├── templates/                    (doble selector + catálogo + helpers)
├── descriptions/                 (INodeProperties por grupo funcional)
├── loadOptions/                  (dropdowns dinámicos)
├── operations/                   (13 handlers, 1 por operación)
└── shared/                       (step-builder, auth, errores, buffer)

Añadir una plantilla nueva = 1 entrada en templates/catalog.ts + 1 ID en PIPELINE_TEMPLATE_ORDER. Añadir una operación nueva = 1 handler en operations/ + 1 línea en el map.

Migración desde v3.0.x anterior

Ningún cambio breaking funcional. Workflows guardados siguen funcionando:

• Los IDs de plantillas no cambiaron (cybersoc_nist, nist_csf_2_0, …).
• Los campos internos (stepKind, stepTitle, phaseRef, etc.) no cambiaron.
• Lo único nuevo es el campo pipelineCategory — los workflows antiguos lo reciben con default generic y la plantilla guardada sigue cargando normalmente (aunque el dropdown de plantillas mostrará las de generic hasta que el usuario ajuste la categoría — edición de 1 click).

Recomendado: al abrir un workflow v3.0.x, ajustar el dropdown de categoría a la familia correcta para que el 2º dropdown muestre las plantillas esperadas.

Build local

pnpm install
pnpm run build

Para testing local:

npm link
cd ~/.n8n/custom
npm link n8n-nodes-orbital-actions
# reiniciar n8n

Licencia

MIT