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

En pocas palabras, un flujo DAG encadena varios robots para que se ejecuten en cierto orden: unos esperan a que otros terminen antes de arrancar.

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.

Crear un flujo desde el editor visual

La forma habitual de armar un flujo, y la recomendada para operadores, es el editor visual de la consola. No necesitas escribir nada de API.

1. Entra en Flujos y pulsa Crear flujo (disponible para los roles admin y operator).
2. Añade nodos al lienzo y, desde el panel lateral, elige el proceso que ejecutará cada nodo.
3. Conecta los nodos arrastrando desde la salida de uno hasta la entrada de otro. La flecha significa que “el destino espera a que el origen termine”.
4. No te preocupes por las coordenadas: las posiciones x/y de cada nodo las guarda el editor solo según dónde los colocas en el lienzo.
5. Ponle nombre al flujo y guárdalo.
6. Para lanzarlo, pulsa Ejecutar y elige la máquina donde correrán los robots. Puedes seguir el progreso en el lienzo: el color de cada nodo indica su estado (pendiente, en ejecución, completado o fallido).

Más allá de los nodos de proceso

El editor también admite nodos de condición, retardo y bucle, no solo nodos de proceso, para construir flujos con lógica más rica.

Autenticación y URL base (equivalente por API, para integraciones)

Lo que sigue describe cómo hacer lo mismo desde la API, pensado para integraciones y automatizaciones; los operadores no lo necesitan. Ten en cuenta que el id de cada nodo y sus coordenadas x/y son detalles que en la consola gestiona el editor visual por ti.

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-api.valisoftconsulting.com
• Prefijo: /api/v1
• Recurso: /api/v1/dags

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

Definir un DAG (equivalente por API, para integraciones)

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 (equivalente por API, para integraciones)

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 (equivalente por API, para integraciones)

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.