Pipelines

Un Pipeline encadena las funciones que ya configuraste (Splitters, Colecciones, Flows, Agentes, Matchers, Inspectores, Fillers y Buckets) en un solo proceso de punta a punta que dibujas en un lienzo. Envías un documento; el Pipeline lo lleva por cada paso y entrega el resultado donde tú quieras.

Cada nodo del lienzo apunta a una función que ya existe. El Pipeline no copia su configuración: cuando mejoras los campos de un Flow o las verificaciones de un Inspector, todos los Pipelines que lo usan toman el cambio. Lo que el Pipeline agrega es el orden: qué paso recibe el documento, qué ejecuciones siguen y a dónde va el resultado.

• Hay que dividir un paquete, extraer cada documento con su propio Flow y revisar los resultados en conjunto
• Los datos extraídos deben pasar a un Agente, a una comparación de un Matcher o al checklist de un Inspector sin que nadie haga clic
• Quieres una sola dirección de correo o una sola llamada a la API que ejecute todo el proceso, no una por función
• El resultado debe llegar a Slack, Teams, Google Chat, una plataforma de automatización o un buzón como paso final

Si un solo Flow con su propio webhook, correo o exportación a Bucket ya resuelve el trabajo, no necesitas un Pipeline. Las funciones siguen funcionando por su cuenta.

Todo lienzo empieza con un nodo de Entrada. Los demás se agregan desde “Agregar nodo”, que los agrupa según la etapa que cumplen: “Recibir y enrutar”, “Extraer”, “Procesar y verificar” y “Entregar”.

Cuando hay un nodo seleccionado, “Agregar nodo” atenúa los tipos que no pueden ir después de él y conecta el nuevo nodo automáticamente. Al elegir un Flow también se sugieren los Matchers, Inspectores y Fillers cuyas entradas ya esperan runs de ese Flow (“Conectados a este flow”), que se agregan ya conectados. Los nodos de Agente requieren los Agentes, que se activan por organización a solicitud.

1. 1Abre “Pipelines” en la barra lateral y haz clic en “Nuevo Pipeline”. Ponle un nombre y, si quieres, una descripción.
2. 2El lienzo se abre con su nodo de Entrada. Selecciónalo y elige cómo llegan los documentos (ver Fuentes más abajo).
3. 3Haz clic en “Agregar nodo”, elige un paso y luego cuál de tus funciones usar. O arrastra desde el punto a la derecha de un nodo hasta otro nodo para conectarlos.
4. 4Selecciona un nodo para abrir su panel: su función vinculada, de qué recibe y a qué envía, y sus ajustes (el mapeo de campos de la Escritura a bucket, el destino de la Salida, la entrada de referencia del Matcher).
5. 5Corrige lo que aparezca en “Corrige esto antes de ejecutar” hasta que el indicador diga “Listo para ejecutar”, y haz clic en “Guardar”.
6. 6Haz clic en “Ejecutar pipeline” y sube un documento para probarlo.

El lienzo tiene “Ordenar” (acomodo automático), deshacer y “Rehacer”, “Duplicar”, selección múltiple con Mayús + clic y Mayús + arrastre, y un minimapa “Vista general” en grafos grandes. Haz scroll para desplazarte, ⌘ + scroll para hacer zoom, y Supr elimina la selección. Los cambios sin guardar se conservan en tu navegador y se recuperan si vuelves.

En lugar de colocar nodos a mano, haz clic en “Diseñar con IA” en el lienzo y describe el proceso en una frase, por ejemplo: “Cuando lleguen facturas: extráelas con el flow de Facturas, corre el checklist de control y guarda las filas en el bucket Facturas DB.”

• El asistente lee las funciones que ya tiene tu organización, diseña el grafo y valida las conexiones, y luego coloca el borrador en el lienzo.
• Si un paso necesita una función que aún no tienes (un Flow, Splitter, Inspector o Bucket), el nodo se marca como “Nuevo” y su panel muestra qué se creará. “Crear esta función” (o “Crear N funciones”) las crea de verdad; revísalas y guarda.
• “Conservar” acepta el borrador; “Descartar” deja el lienzo como estaba antes. Un borrador reemplaza todos los nodos y conexiones del lienzo, así que se te pregunta primero si ya hay uno.

Diseñar con IA no ejecuta nada.

Selecciona el nodo de Entrada para ver sus tres fuentes.

El disparador por correo, el “ID del pipeline” y el interruptor “Activo” también están en la pestaña “Configuración”. Los pipelines inactivos rechazan nuevas ejecuciones desde cualquier fuente.

Un nodo de Salida envía todo lo que produjeron los pasos anteriores. Elige un destino en el panel del nodo:

{
  "pipeline_id": "…",
  "execution_id": "…",
  "pipeline_name": "Entrada de facturas",
  "original_filename": "document.pdf",
  "outputs": [
    {
      "node": "Facturas",
      "node_type": "flow",
      "output": { "invoice_number": "…", "total": 1250.5 }
    }
  ]
}

El panel muestra un “Payload de ejemplo” construido con los campos del Flow anterior; el real lleva los valores extraídos. Los archivos del resultado llegan como enlaces temporales. Los destinos de chat muestran hasta ocho campos clave del primer resultado anterior.

Una función conserva su propio comportamiento dentro de un Pipeline: un Flow sigue enviando su propio webhook, correo, exportación a Bucket, Cleaner, revisión humana y Agente vinculado. El lienzo te señala dónde eso se cruza con lo que dibujaste.

• Una Escritura a bucket en el mismo Bucket al que ya exporta el Flow anterior guardaría las filas dos veces.
• Una Salida por webhook después de un Flow que ya envía un webhook enviaría el resultado dos veces.
• Una Salida por correo después de un Flow que ya envía sus resultados por correo mandaría un segundo correo.

Estos aparecen como avisos en “Vale la pena revisar — igual se ejecuta”. Nunca bloquean una ejecución. Las tarjetas también llevan pequeñas marcas de lo que la función entrega por su cuenta (“Webhook”, correos, “Revisión humana”, entrega de un Agente), que el panel del nodo lista en “También entrega a”.

El panel de un nodo de Flow también muestra “Usado también en”: las Colecciones, Splitters y otros Pipelines que dependen del mismo Flow, para que sepas qué más afecta un cambio en él.

“Ejecutar pipeline” y la API rechazan un grafo que rompa alguna de estas reglas; el lienzo marca el nodo con el problema.

• Exactamente un nodo de Entrada, sin conexiones entrantes. Sin ciclos y sin nodos conectados a sí mismos.
• Todos los demás nodos necesitan una conexión entrante y una función vinculada (una Salida necesita un destinatario o una URL de webhook).
• Flows, Splitters y Colecciones reciben un documento de una sola fuente: la Entrada, un Splitter o (en el caso de los Flows) una Colección.
• Cada conexión hacia un Inspector o Filler necesita una ranura de entrada; un Filler no puede recibir dos conexiones en la misma ranura.
• Máximo 50 nodos por Pipeline.

Los Matchers, Inspectores y Fillers (y cualquier nodo alimentado por más de una fuente) esperan a que termine todo lo anterior y se ejecutan una sola vez. Después de un Splitter, cada documento encontrado se vuelve su propia rama, y los pasos siguientes se ejecutan una vez por rama.

Cada documento que entra a un Pipeline crea una ejecución. La pestaña “Ejecuciones” las lista con el documento, la hora, el origen, el remitente, la duración y el estado.

Abre una ejecución para ver el lienzo tal como corrió, coloreado por el estado de cada nodo, con el progreso (“X de Y nodos listos”) y actualizaciones en vivo. Cada nodo muestra Pendiente, En espera, En cola, En ejecución, Completado, Fallido, Omitido o Cancelado, con un indicador por rama después de un Splitter. Selecciona un nodo y usa “Ver resultado” para abrir el run, la división, el match, la inspección o el llenado que produjo.

“Cancelar ejecución” detiene el resto del grafo: los nodos que no han empezado se cancelan, y las ejecuciones de funciones que ya estaban en curso terminan por su cuenta.

Copia el ID desde “ID del pipeline” en la pestaña Configuración. Inicia una ejecución enviando el documento como multipart file (o como JSON con file_base64 y filename):

curl -X POST https://run.tavnit.io/api/pipelines/PIPELINE_ID/execute \
  -H "X-API-Key: $TAVNIT_API_KEY" \
  -F "file=@document.pdf"

{
  "success": true,
  "execution_id": "…",
  "pipeline_id": "…",
  "org_id": "…",
  "status": "running"
}

Una definición que no se puede ejecutar devuelve 400 con validation_errors; un 402 significa que tu organización no puede iniciar trabajo nuevo en este momento (contacta al equipo de Tavnit); un Pipeline inactivo devuelve 400. Sigue el progreso en la pestaña Ejecuciones. Para detener una ejecución:

curl -X POST https://run.tavnit.io/api/pipelines/executions/EXECUTION_ID/cancel \
  -H "X-API-Key: $TAVNIT_API_KEY"

Cancelar una ejecución que ya terminó devuelve 409. La autenticación y el manejo de errores son los mismos que en el resto de la API REST.

Eliminar un Pipeline borra el pipeline y su lienzo; las ejecuciones pasadas conservan sus registros. Consulta Roles de usuario.