Workflows
Un workflow es la definición de un proceso de negocio, la secuencia de pasos que Flowker sigue para completar una operación. Los workflows pasan por un ciclo de vida:
Para mover un workflow entre estados, usa los endpoints activate, deactivate y move to draft.
Nodos y aristas
Los nodos son los pasos individuales de un workflow, o tareas en términos de negocio. Cada nodo es una unidad de trabajo: recibir un evento, llamar a un servicio, evaluar una condición o hacer una acción. Flowker admite cuatro tipos de nodo:
Las aristas conectan los nodos y definen el orden de ejecución. La ramificación vive en el nodo condicional, no en la arista: el nodo condicional evalúa su condición y produce un handle de resultado, y Flowker sigue la única arista saliente cuyo
sourceHandle coincide con ese handle. Todos los demás tipos de nodo siguen todas sus aristas salientes.
Catálogo
El catálogo es el registro de solo lectura de todos los proveedores, ejecutores y disparadores integrados disponibles en Flowker. No puedes crear ni modificar entradas del catálogo. Las descubres. Antes de configurar cualquier integración, explora el catálogo para ver qué hay disponible:
- Los ejecutores del catálogo son los componentes integrados que invoca un nodo de workflow. Incluyen el conector HTTP genérico y las operaciones de proveedores nativos como el ledger de Midaz y Tracer.
- Los disparadores definen los tipos de evento que pueden iniciar un workflow (por ejemplo, webhooks).
- List catalog executors y List catalog triggers para descubrir los tipos de ejecutor y de disparador.
- List catalog providers (
GET /v1/catalog/providers) para listar todos los proveedores disponibles. - Get catalog provider (
GET /v1/catalog/providers/{id}) para obtener los detalles de un proveedor específico. - List executors by provider (
GET /v1/catalog/providers/{id}/executors) para listar los ejecutores disponibles de un proveedor específico.
Configuraciones de proveedor
Una configuración de proveedor es tu conexión a una instancia activa de un servicio externo. Es el objeto al que apunta un nodo de workflow, y el objeto que Flowker lee cuando ese nodo corre. Flowker separa el tipo de servicio de tu conexión a él:
Cada configuración de proveedor contiene:
config: los detalles de conexión de esa instancia, como la URL base y las credenciales de autenticación. Para la clasecatalogpredeterminada, Flowker valida este mapa contra el JSON Schema del proveedor del catálogo. Paraexternal_openapi, usa un validador de configuración de OpenAPI externo. Las hojas sensibles reconocidas se escriben en el backend de secretos y se reemplazan porsecretRef. Las configuraciones heredadas sinsecretRefpueden contener valores en línea.allowedHosts: los hosts públicos a los que esta configuración puede llamar.allowedPrivateHosts: hosts privados con nombre que tu equipo de operaciones permite alcanzar a esta configuración. Levanta solo la restricción de Flowker sobre direcciones privadas o de loopback: siallowedHostsno está vacío, también debe incluir el host. Los metadatos de nube y las direcciones link-local siguen bloqueados.schemaBindings: los esquemas XSD u OpenAPI vinculados a esta configuración, cada uno con una restricción opcional a operaciones específicas de OpenAPI.
kind. Los valores admitidos son catalog (el predeterminado), que conecta con un proveedor del catálogo, y external_openapi, que conecta con un documento OpenAPI que subiste tú mismo para que un nodo de workflow llame a las operaciones de tu propia API. Consulta Conectar tu propia API.
Las configuraciones de proveedor tienen dos estados: active (en uso) y disabled (fuera de línea de forma temporal). Usa Disable provider configuration para sacar una conexión de servicio y Enable provider configuration para devolverla.
Cómo un workflow llega a ella
Cada nodo ejecutor puede llevar unproviderConfigId, el identificador de la configuración de proveedor a través de la cual llama. En tiempo de ejecución, Flowker construye cada solicitud saliente con la URL base de esa configuración de proveedor más la ruta del nodo, y el nodo falla si la configuración de proveedor no está en active.
Usa los endpoints de Provider configurations para crear, leer, actualizar, deshabilitar, habilitar y eliminar tus conexiones.
Registro de configuraciones de ejecutor
Flowker mantiene un registro de entradas de configuración de ejecutor. El registro expone cuatro operaciones:
Cada entrada lleva un
status, que la API reporta en cada respuesta:
El cuerpo de la actualización no incluye
status, pero la operación de listado lo acepta como filtro de consulta. La actualización aplica a las entradas con estado unconfigured o configured. La eliminación aplica a las entradas con estado unconfigured, configured o disabled. Ninguna operación de esta versión mueve una entrada a tested, active o disabled. La tabla lista esos valores porque las respuestas los reportan y el filtro de listado los acepta.
Plantillas
Las plantillas de workflow son patrones de workflow prediseñados publicados en el catálogo. Cada plantilla describe un patrón de integración conocido y los parámetros que ese patrón espera. El catálogo incluye la plantilla
tracer-midaz-validation (“Tracer Validation + Midaz Transaction”): recibe una solicitud de webhook, valida la transacción a través de Tracer y crea la transacción en Midaz cuando Tracer la aprueba.
Cada plantilla tiene un esquema de parámetros que define qué entradas espera (por ejemplo, qué configuración de proveedor usar, valores de umbral). Cuando Flowker puede recuperar configuraciones de proveedor activas, enriquece los campos de parámetro referenciados con opciones seleccionables. Si la búsqueda no está disponible o falla, devuelve el esquema original.
Para inspeccionar una plantilla:
- Lista las plantillas del catálogo.
- Obtén el detalle de la plantilla para ver su esquema de parámetros.
- Valida un conjunto de parámetros contra ese esquema.
Ejecuciones
Una ejecución es una instancia en tiempo de ejecución de un workflow. Un disparador normalmente inicia una nueva ejecución. Un reintento que reutiliza una clave de idempotencia existente devuelve la ejecución preexistente en lugar de crear otra. Cada ejecución registra:
executionId: identificador único de esta ejecución.status: estado actual (pending,running,completedofailed).stepResults: la salida de cada nodo ejecutor, condicional o de acción ejecutado, en orden. Los nodos disparadores inician el recorrido del grafo y no crean registros de paso de ejecución.finalOutput: el valor final que se persiste para la ejecución. Cuando una acciónset_outputproduce un objeto, Flowker usa ese objeto. De lo contrario, Flowker devuelve el contexto acumulado del workflow.
El endpoint de estado devuelve el registro de la ejecución, incluido su estado actual. El endpoint dedicado de resultados (
GET /v1/executions/{id}/results) devuelve status, stepResults y finalOutput cuando están presentes. Un paso fallido puede incluir errorMessage. Esta respuesta no tiene un campo de detalles de error en el nivel superior.Idempotencia
Las solicitudes de ejecución directa requieren una cadena
Idempotency-Key no vacía. Flowker no exige el formato UUID. El header del webhook es opcional.
Si Flowker recibe una segunda solicitud con el mismo Idempotency-Key, devuelve la ejecución preexistente en lugar de crear otra. Una repetición directa devuelve HTTP 200 e incluye idempotencyReplayed en la respuesta.
Dashboard
La API del Dashboard provee resúmenes agregados de tus workflows y ejecuciones. Úsala cuando necesites una vista de alto nivel de la salud del sistema sin consultar ejecuciones individuales.
- Workflow summary devuelve totales y desgloses por estado (draft, active, inactive).
- Execution summary devuelve totales y desgloses por estado, con filtros opcionales de rango de tiempo y de estado.
GET /v1/dashboards/executions:
- Monitorear la salud de las ejecuciones: rastrea las tasas de finalización y de fallo a lo largo del tiempo para detectar la degradación temprano.
- Construir páginas de estado: muestra el throughput de los workflows y las métricas de éxito en dashboards internos o de cara 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.
Cómo encaja todo
Los conceptos de Flowker se construyen unos sobre otros en una secuencia clara:
- Explora el catálogo para descubrir los proveedores, ejecutores del catálogo, disparadores y plantillas disponibles.
- Crea configuraciones de proveedor para conectar Flowker con instancias activas de servicios externos.
- Define workflows: cada nodo ejecutor nombra un ejecutor del catálogo y la configuración de proveedor a través de la cual llama.
- Ejecuta workflows para correr tu proceso de negocio y recuperar los resultados.
- Monitorea: usa el dashboard para los resúmenes operativos y la API de ejecuciones para el detalle por paso.