Workflows
Un workflow es la definición de un proceso de negocio — la secuencia de pasos que Flowker sigue para completar una operación. Cada workflow tiene un ciclo de vida con tres estados posibles:
| Estado | Descripción |
|---|---|
draft | Creado y editable. Aún no se puede ejecutar. |
active | Listo para ejecutar. La estructura está bloqueada. |
inactive | Desactivado. No se aceptan nuevas ejecuciones. |
Nodes y edges
Los nodes son los pasos individuales de un workflow — lo que en términos de negocio llamarías tareas. Cada node es una unidad de trabajo: recibir un evento, llamar a un servicio, evaluar una condición o realizar una acción. Flowker admite cuatro tipos de node:
| Tipo | Propósito | Cuándo usarlo |
|---|---|---|
trigger | Punto de entrada del workflow | Siempre el primer node. Inicia la ejecución cuando ocurre un evento. |
executor | Llama a un servicio externo mediante un executor configurado | Cuando necesitas llamar a una API o integración externa. |
conditional | Bifurca la ejecución según condiciones | Cuando el siguiente paso depende del resultado del anterior. |
action | Ejecuta una acción integrada (log, transform, etc.) | Para operaciones nativas que no requieren llamadas externas. |
Catálogo
El catálogo es el registro de solo lectura de todos los providers, executors y triggers integrados disponibles en Flowker. No puedes crear ni modificar entradas del catálogo — solo descubrirlas. Antes de configurar cualquier integración, explora el catálogo para ver qué está disponible:
- Los executors son las capacidades específicas que puedes invocar en un node (p. ej., solicitudes HTTP, transformaciones de datos).
- Los triggers definen los tipos de eventos que pueden iniciar un workflow (p. ej., webhooks).
- Listar executors del catálogo y Listar triggers del catálogo para descubrir tipos de executor y trigger.
- Listar providers del catálogo (
GET /v1/catalog/providers) para listar todos los providers disponibles. - Obtener provider del catálogo (
GET /v1/catalog/providers/{id}) para obtener los detalles de un provider específico. - Listar executors por provider (
GET /v1/catalog/providers/{id}/executors) para listar los executors disponibles para un provider específico.
Configuraciones
Antes de usar un executor en un workflow, debes configurarlo. Una configuración de executor define cómo Flowker se conecta a un servicio externo — incluyendo la URL base, las credenciales de autenticación y los endpoints HTTP específicos a llamar. Las configuraciones de executor pasan por un ciclo de vida:
| Estado | Descripción |
|---|---|
unconfigured | Creada pero aún no configurada con detalles de conexión. |
configured | Detalles de conexión proporcionados, lista para probar. |
tested | Prueba de conectividad exitosa. |
active | Lista para ser usada en ejecuciones de workflows. |
disabled | Temporalmente fuera de servicio. |
Configuraciones de provider
Flowker usa un modelo de tres capas para integraciones externas:
| Capa | Qué es | Naturaleza |
|---|---|---|
| Provider | Un tipo de servicio externo (p. ej., Midaz, Tracer). | Estático — definido en el catálogo. |
| Configuración de Provider | Una instancia configurada de un provider con credenciales y URL base. | Dinámica — tú la creas y gestionas. |
| Configuración de Executor | Una operación específica en un provider, con endpoints y mapeos de campos. | Dinámica — referencia una configuración de provider. |
active (en uso) y disabled (temporalmente offline). Puedes probar la conectividad en cualquier momento para verificar que la conexión funcione.
Usa los endpoints de Configuraciones de provider para crear, gestionar y probar tus conexiones con providers.
Templates
Los templates de workflow son patrones pre-construidos disponibles en el catálogo. En lugar de definir un workflow desde cero, puedes seleccionar un template, completar sus parámetros y crear un workflow listo para usar en segundos. Cada template tiene un schema de parámetros que define qué entradas espera (p. ej., qué configuración de provider usar, valores de umbral). Cuando consultas un template, el schema se enriquece dinámicamente — los campos que referencian configuraciones de provider se completan con tus configuraciones activas, para que puedas elegir de una lista en lugar de ingresar UUIDs manualmente. Para usar un template:
- Explora los templates disponibles en el catálogo.
- Consulta el detalle del template para ver su schema de parámetros.
- Opcionalmente valida tus parámetros antes de crear.
- Crea un workflow a partir del template.
draft, para que puedas revisarlo y ajustarlo antes de activar.
Ejecuciones
Una ejecución es una instancia en tiempo de ejecución de un workflow. Cada vez que activas un workflow, Flowker crea una nueva ejecución y procesa sus nodes en orden. Cada ejecución registra:
executionId— Identificador único de esta ejecución.status— Estado actual:pending,running,completedofailed.stepResults— La salida de cada node ejecutado, en orden.finalOutput— El resultado agregado de toda la ejecución.
El endpoint principal de estado (
GET /v1/executions/{id}) devuelve executionId, workflowId, status, currentStepNumber, totalSteps, startedAt, completedAt y errorMessage. Los campos stepResults y finalOutput solo están disponibles a través del endpoint de resultados dedicado (GET /v1/executions/{id}/results).Idempotencia
Cada solicitud de ejecución requiere un header
Idempotency-Key. Es un UUID que generas y envías con cada solicitud para identificarla de forma única.
Si Flowker recibe una segunda solicitud con el mismo Idempotency-Key, devuelve la respuesta original en lugar de crear una nueva ejecución. Esto hace que los reintentos sean seguros — las fallas de red y los timeouts no generarán ejecuciones duplicadas.
Dashboard
La API de Dashboard proporciona resúmenes agregados de tus workflows y ejecuciones — útil para construir dashboards operacionales y herramientas de monitoreo. Úsala siempre que necesites una visión de alto nivel de la salud del sistema sin consultar ejecuciones individuales.
- Resumen de workflows devuelve totales y desgloses por estado (draft, active, inactive).
- Resumen de ejecuciones devuelve totales y desgloses por estado, con filtros opcionales de rango de tiempo y estado.
GET /v1/dashboards/executions:
- Monitorear la salud de las ejecuciones — rastrea las tasas de completación y fallo a lo largo del tiempo para detectar degradaciones tempranamente.
- Construir páginas de estado — muestra métricas de throughput y éxito de los workflows en dashboards internos o dirigidos al cliente.
- Alertar sobre picos en la tasa de fallos — compara
failed / totalcontra un umbral para disparar alertas antes de que los problemas se propaguen.
Auditoría y cumplimiento
Flowker registra automáticamente una pista de auditoría inmutable para cada acción significativa — creación de workflows, cambios de estado, inicios y finalizaciones de ejecuciones, llamadas a executors y cambios de configuración. No necesitas habilitar ni configurar nada; el registro de auditoría ocurre internamente. Propiedades clave del sistema de auditoría:
- Inmutable — los registros de auditoría son de solo adición y no pueden ser modificados ni eliminados.
- Integridad mediante cadena de hashes — cada entrada incluye un hash criptográfico que la vincula a la entrada anterior, haciendo detectable cualquier manipulación.
- Búsqueda flexible — usa Buscar eventos de auditoría para consultar eventos por tipo, acción, resultado, recurso o rango de fechas.
- Verificación de la cadena — usa Verificar cadena de hashes para confirmar que la pista de auditoría no ha sido manipulada.
Cómo encaja todo
Los conceptos de Flowker se construyen unos sobre otros en una secuencia clara:
- Explora el catálogo para descubrir providers, executors, triggers y templates disponibles.
- Configura providers para conectar Flowker a instancias activas de servicios externos.
- Configura executors para definir las operaciones y endpoints específicos que tu workflow necesita.
- Define workflows — desde cero o a partir de un template — referenciando tus configuraciones de executor.
- Ejecuta workflows para correr tu proceso de negocio y obtener resultados.
- Monitorea y audita — usa el dashboard para resúmenes operacionales y la API de auditoría para cumplimiento.