Conceptos fundamentales

Comprende los componentes de Flowker: workflows, nodes, edges, catálogo, configuraciones de provider, templates, ejecuciones y dashboard.

Flowker se construye sobre un conjunto de conceptos interconectados. Comprender cómo se relacionan entre sí te ayudará a diseñar, configurar y ejecutar workflows de manera efectiva. La última sección de esta página muestra cómo todo encaja.

​

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.

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:

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 a través de una configuración de provider	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; el tipo disponible es set_output, que define el output final de la ejecución	Para definir el output final del workflow sin una llamada externa.

Los edges conectan nodes y definen el orden de ejecución. La bifurcación vive en el node conditional, no en el edge: el node conditional evalúa su condición y produce un handle de resultado, y Flowker sigue el único edge saliente cuyo sourceHandle coincide con ese handle. Todos los demás tipos de node siguen todos sus edges salientes.

​

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 del catálogo son los componentes integrados que un node invoca — el conector HTTP genérico y las operaciones de providers nativos como el ledger de Midaz y Tracer. Los descubres; nunca los creas.
• Los triggers definen los tipos de eventos que pueden iniciar un workflow (p. ej., webhooks).

Usa estos endpoints para explorar lo que está disponible:

• 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 de provider

---

Una configuración de provider es tu conexión a una instancia activa de un servicio externo. Es el objeto al que apunta un node y el objeto que Flowker lee cuando ese node se ejecuta.

Flowker separa el tipo de servicio de tu conexión a él:

Concepto	Qué es	Naturaleza
Provider	Un tipo de servicio externo (p. ej., Midaz, Tracer, un endpoint HTTP genérico).	Estático — publicado en el catálogo.
Configuración de provider	Tu conexión a una instancia de ese provider.	Dinámica — tú la creas y gestionas.

Cada configuración de provider contiene:

• config — los detalles de conexión de esa instancia, como la URL base y las credenciales de autenticación. Para el kind predeterminado catalog, Flowker valida este mapa contra el JSON Schema del provider del catálogo. Para external_openapi, usa un validador de configuración de OpenAPI externa. Los campos sensibles reconocidos se escriben en el backend de secretos y se reemplazan por secretRef; las configuraciones heredadas sin secretRef pueden contener valores en línea.
• allowedHosts — los hosts públicos que esta configuración puede llamar.
• allowedPrivateHosts — hosts privados nombrados que tu equipo de operaciones permite alcanzar a esta configuración. Solo levanta la restricción de Flowker para direcciones privadas o loopback: si allowedHosts no está vacío, también debe incluir el host. Las direcciones de metadatos de nube y link-local siguen bloqueadas.
• schemaBindings — los esquemas XSD u OpenAPI vinculados a esta configuración, cada uno con una restricción opcional a operaciones OpenAPI específicas.

Una configuración también lleva un kind. Los valores admitidos son catalog (el valor por defecto), que conecta a un provider del catálogo, y external_openapi, que conecta a un documento OpenAPI que subiste tú para que un node de workflow llame a las operaciones de tu propia API — consulta Conectar tu propia API.

Las configuraciones de provider tienen dos estados: active (en uso) y disabled (temporalmente offline). Usa Deshabilitar configuración de provider para sacar una conexión de servicio y Habilitar configuración de provider para devolverla.

​

Cómo un workflow la alcanza

Cada node executor puede llevar un providerConfigId — el identificador de la configuración de provider 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 provider más el path del node, y el node falla si la configuración de provider no está active.

Usa los endpoints de Configuraciones de provider para crear, leer, actualizar, deshabilitar, habilitar y eliminar tus conexiones.

​

Registro de configuraciones de executor

---

Flowker mantiene un registro de configuraciones de executor. El registro expone cuatro operaciones:

Operación	Endpoint
Listar	GET /v1/executors
Obtener	GET /v1/executors/{id}
Actualizar	PATCH /v1/executors/{id}
Eliminar	DELETE /v1/executors/{id}

Cada registro lleva un status, que la API informa en cada respuesta:

Estado	Descripción
unconfigured	El registro aún no tiene detalles de conexión.
configured	El registro lleva detalles de conexión.
tested	El registro fue verificado.
active	El registro está en servicio.
disabled	El registro está fuera de servicio.

El cuerpo de actualización no incluye status, pero la operación de listado lo acepta como filtro de consulta. La actualización aplica a registros en estado unconfigured o configured; la eliminación aplica a registros en estado unconfigured, configured o disabled. Ninguna operación en esta versión mueve un registro a tested, active o disabled; la tabla lista esos valores porque las respuestas los informan y el filtro de listado los acepta.

​

Templates

---

Los templates de workflow son patrones pre-construidos publicados en el catálogo. Cada template describe un patrón de integración conocido y los parámetros que ese patrón espera.

El catálogo trae el template tracer-midaz-validation (“Tracer Validation + Midaz Transaction”): recibe una solicitud de webhook, valida la transacción con Tracer y crea la transacción en Midaz cuando Tracer la aprueba.

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 Flowker puede recuperar configuraciones de provider activas, enriquece los campos de parámetros referenciados con opciones seleccionables. Si la consulta no está disponible o falla, devuelve el schema original.

Para inspeccionar un template:

1. Lista los templates del catálogo.
2. Consulta el detalle del template para ver su schema de parámetros.
3. Valida un conjunto de parámetros contra ese schema.

​

Ejecuciones

---

Una ejecución es una instancia en tiempo de ejecución de un workflow. Una activación 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 node executor, condicional o de acción ejecutado, en orden. Los nodes trigger inician el recorrido del grafo y no crean registros de pasos de ejecución.
• finalOutput — El valor final persistido para la ejecución. Cuando una acción set_output produce un objeto, Flowker usa ese objeto; de lo contrario, devuelve el contexto acumulado del workflow.

Usa Consultar estado de la ejecución para monitorear el progreso y Consultar resultados de la ejecución para obtener la salida completa.

El endpoint de estado devuelve el registro de la ejecución, incluido su estado actual. El endpoint de resultados dedicado (GET /v1/executions/{id}/results) devuelve status, stepResults y finalOutput cuando está presente. Un paso fallido puede incluir errorMessage; esta respuesta no tiene un campo de detalles de error de nivel superior.

​

Idempotencia

---

Las solicitudes directas de ejecución requieren una cadena Idempotency-Key no vacía; Flowker no exige formato UUID. El header de 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.

Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b

Usa una clave nueva cuando quieras crear una ejecución nueva de forma intencional. Reutiliza la misma clave solo al reintentar exactamente la misma solicitud.

​

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.

Ejemplo de respuesta de GET /v1/dashboards/executions:

{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}

Casos de uso comunes:

• 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 / 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 una secuencia clara:

1. Explora el catálogo para descubrir providers, executors del catálogo, triggers y templates disponibles.
2. Crea configuraciones de provider para conectar Flowker a instancias activas de servicios externos.
3. Define workflows — cada node executor nombra un executor del catálogo y la configuración de provider a través de la cual llama.
4. Ejecuta workflows para correr tu proceso de negocio y obtener resultados.
5. Monitorea — usa el dashboard para resúmenes operacionales y la API de ejecuciones para el detalle por paso.

¿Listo para verlo en práctica? Sigue la guía de primeros pasos para ejecutar tu primer workflow de principio a fin.