Saltar al contenido principal
Esta página describe cada concepto de Flowker. La última sección muestra cómo se conectan.

​
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 ocurre en el nodo condicional, no en la arista. El nodo condicional evalúa su condición y produce un handle de resultado. Luego Flowker sigue la única arista saliente cuyo sourceHandle coincide con ese handle. Todos los demás tipos de nodo siguen todas sus aristas salientes.
El catálogo es el registro de los proveedores, ejecutores y disparadores integrados disponibles en Flowker. 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).
Usa estos endpoints para explorar lo que hay disponible:

​
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 clase catalog predeterminada, Flowker valida este mapa contra el JSON Schema del proveedor del catálogo. Para external_openapi, usa un validador de configuración de OpenAPI externo. Una lectura nunca devuelve la credencial que declara el tipo de autenticación.
  • 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. Quita solo la restricción de Flowker sobre direcciones privadas o de loopback: si allowedHosts no 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.
Una configuración también lleva un 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 un providerConfigId, 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.

​
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. 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. Para inspeccionar una plantilla:
  1. Lista las plantillas del catálogo.
  2. Obtén el detalle de la plantilla para ver su esquema de parámetros.
  3. 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, completed o failed).
  • 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ón set_output produce un objeto, Flowker usa ese objeto. De lo contrario, Flowker devuelve el contexto acumulado del workflow.
Usa Get execution status para monitorear el progreso y Get execution results para recuperar la salida completa.
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 incluye idempotencyReplayed: true en la respuesta.
Usa una clave nueva cuando quieras intencionalmente una nueva ejecución. Reutiliza la misma clave solo cuando reintentes exactamente la misma solicitud.

​
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.
Respuesta de ejemplo de GET /v1/dashboards/executions:
Casos de uso comunes:
  • 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 / total contra 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 este orden:
  1. Explora el catálogo para descubrir los proveedores, ejecutores del catálogo, disparadores y plantillas disponibles.
  2. Crea configuraciones de proveedor para conectar Flowker con instancias activas de servicios externos.
  3. Define workflows: cada nodo ejecutor nombra un ejecutor del catálogo y la configuración de proveedor a través de la cual llama.
  4. Ejecuta workflows para correr tu proceso de negocio y recuperar los resultados.
  5. Monitorea: usa el dashboard para los resúmenes operativos y la API de ejecuciones para el detalle por paso.
Sigue la guía de primeros pasos para ejecutar tu primer workflow de extremo a extremo.