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:
Para cambiar el estado de un workflow, usa los endpoints activar, desactivar y mover a draft.
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:
Los edges conectan nodes y definen el orden de ejecución. Un edge puede llevar una condición: el siguiente node solo se ejecuta si la condición es verdadera.
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:
Usa los endpoints de Configuraciones de executor para configurar y gestionar tus integraciones.
Configuraciones de provider
Flowker usa un modelo de tres capas para integraciones externas:
Una configuración de provider conecta Flowker a una instancia activa de un servicio externo. Proporcionas la URL base, las credenciales de autenticación y cualquier configuración específica del provider. La configuración se valida contra el JSON Schema del provider en el catálogo.
Las configuraciones de provider tienen dos estados:
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.