Flujos DAG

Un flujo DAG (grafo acíclico dirigido, Directed Acyclic Graph) permite encadenar varios procesos de NORA en un único flujo orquestado, donde unos nodos dependen de que otros terminen antes de arrancar. Es la herramienta indicada cuando un resultado de negocio no se logra con un solo robot, sino con varios que deben ejecutarse en cierto orden.

Plan requerido

Los flujos DAG son una función de los planes Pro y Enterprise. En planes inferiores los endpoints responden 403 indicando el plan necesario.

Qué es un DAG en NORA

Un DAG se compone de dos listas:

• Nodos (nodes): cada nodo apunta a un proceso (process_id) y representa un paso del flujo.
• Aristas (edges): cada arista declara una dependencia dirigida source → target, es decir, “el nodo target no arranca hasta que source haya terminado”.

Al ejecutar el DAG, NORA:

1. Detecta los nodos raíz (los que no aparecen como target de ninguna arista) y crea un job para cada uno en la máquina indicada.
2. A medida que cada job termina, avanza el DAG: cuando todos los predecesores de un nodo están completed, dispara ese nodo.
3. Marca la ejecución como completed cuando todos los nodos terminan correctamente, o como failed si alguno falla.

flowchart TD
    A["Extraer facturas (proceso A)"] --> B["Validar datos (proceso B)"]
    A --> C["Generar reporte (proceso C)"]
    B --> D["Cargar al ERP (proceso D)"]
    C --> D
    D --> E["Enviar notificacion (proceso E)"]

En este ejemplo, D (cargar al ERP) espera a que terminen B y C; y E solo arranca cuando D finaliza. Los nodos B y C pueden ejecutarse en paralelo porque ambos solo dependen de A.

Estados de ejecución

Cada ejecución (DAGExecution) tiene un status global y un mapa node_states por nodo:

Campo	Valores
status (ejecución)	running, completed, failed
node_states[node_id]	pending, running, completed, failed

Si cualquier nodo termina con failed, la ejecución completa pasa a failed y no se disparan más nodos.

Se requiere al menos un nodo raíz

Si todas las aristas forman un ciclo (no hay nodo sin predecesores), la ejecución se rechaza con un error de validación (“DAG no tiene nodos raíz (ciclo detectado)”). Un DAG, por definición, no puede contener ciclos.

Autenticación y URL base

Los endpoints de DAG forman parte de la API interna del panel y se autentican con la sesión de usuario (JWT), no con la cabecera X-API-Key de la API pública. Las operaciones de creación, edición y ejecución requieren rol admin u operator; la lectura admite además viewer; el borrado exige admin.

• URL base: https://nora.valisoftconsulting.com
• Prefijo: /api/v1
• Recurso: /api/v1/dags

Todas las respuestas van envueltas en {"success": true, "data": ...}.

Definir un DAG

POST /api/v1/dags

{
  "name": "Cierre contable diario",
  "description": "Extrae, valida y carga facturas al ERP",
  "nodes": [
    { "id": "a", "process_id": "1f1c…-uuid-del-proceso-A", "label": "Extraer facturas", "x": 0, "y": 0 },
    { "id": "b", "process_id": "2a2d…-uuid-del-proceso-B", "label": "Validar datos", "x": 200, "y": -80 },
    { "id": "c", "process_id": "3b3e…-uuid-del-proceso-C", "label": "Generar reporte", "x": 200, "y": 80 },
    { "id": "d", "process_id": "4c4f…-uuid-del-proceso-D", "label": "Cargar al ERP", "x": 400, "y": 0 }
  ],
  "edges": [
    { "source": "a", "target": "b" },
    { "source": "a", "target": "c" },
    { "source": "b", "target": "d" },
    { "source": "c", "target": "d" }
  ]
}

Campos de cada nodo: id (string único dentro del DAG), process_id (UUID del proceso), label (texto visible) y coordenadas x/y para el lienzo del editor visual. Cada arista define source y target con los id de los nodos.

Aislamiento por organización

NORA valida que todos los process_id referenciados existan, estén activos y pertenezcan a tu organización antes de guardar o ejecutar el DAG. Un process_id de otra organización (o inactivo) provoca un error de validación.

Operaciones disponibles

Método y ruta	Descripción	Rol mínimo
POST /api/v1/dags	Crea un DAG	operator
GET /api/v1/dags	Lista los DAG de la organización	viewer
GET /api/v1/dags/{dag_id}	Obtiene un DAG	viewer
PUT /api/v1/dags/{dag_id}	Actualiza nombre, descripción, nodos o aristas	operator
DELETE /api/v1/dags/{dag_id}	Elimina un DAG	admin
POST /api/v1/dags/{dag_id}/execute	Inicia una ejecución	operator
GET /api/v1/dags/executions/{execution_id}	Consulta el estado de una ejecución	viewer

Ejecutar un DAG

POST /api/v1/dags/{dag_id}/execute

La ejecución necesita la máquina donde correrán los jobs. La máquina también se valida contra tu organización.

curl -X POST \
  https://nora-api.valisoftconsulting.com/api/v1/dags/{dag_id}/execute \
  -H "Authorization: Bearer <token-de-sesion>" \
  -H "Content-Type: application/json" \
  -d '{ "machine_id": "9f9a…-uuid-de-la-maquina" }'

Respuesta (envuelta):

{
  "success": true,
  "data": {
    "id": "…",
    "dag_id": "…",
    "status": "running",
    "node_states": { "a": "running", "b": "pending", "c": "pending", "d": "pending" },
    "trigger_machine_id": "9f9a…",
    "created_at": "2026-06-19T12:00:00Z",
    "updated_at": "2026-06-19T12:00:00Z"
  }
}

NORA arranca los nodos raíz (aquí a) y, conforme sus jobs finalizan, avanza automáticamente los nodos cuyos predecesores ya están completed. Consulta el progreso con GET /api/v1/dags/executions/{execution_id} revisando status y node_states.

Cuándo usar un flujo DAG

Usa un DAG cuando:

• Un resultado depende de varios procesos que deben ejecutarse en un orden concreto (p. ej. extraer → validar → cargar).
• Hay pasos que pueden correr en paralelo y otros que deben converger (varios nodos apuntando al mismo target).
• Quieres una sola unidad de orquestación con estado y trazabilidad por nodo, en lugar de lanzar jobs sueltos manualmente.

Para una tarea de un solo proceso, basta con lanzar un job directamente; para ejecuciones recurrentes por calendario, combina el DAG con programaciones si tu plan las incluye.

Los flujos DAG están disponibles en los planes Pro y Enterprise. Consulta la referencia de la API para los endpoints relacionados.