Conceptos centrales

Entiende los bloques de construcción de Flowker: workflows, nodos, aristas, catálogo, configuraciones de proveedor, plantillas, ejecuciones y dashboard.

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:

Estado	Descripción
draft	Creado y editable. Todavía no ejecutable.
active	Listo para ejecutar. La estructura está bloqueada.
inactive	Desactivado. No se aceptan nuevas ejecuciones.

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 cinco tipos de nodo:

Tipo	Propósito	Cuándo usarlo
trigger	Punto de entrada del workflow	Inicia la ejecución cuando ocurre un evento.
executor	Llama a un servicio externo a través de una configuración de proveedor	Cuando necesitas llamar a una API o integración externa.
conditional	Ramifica la ejecución según condiciones	Cuando el paso siguiente depende del resultado de uno anterior.
action	Hace una acción integrada; el tipo disponible es set_output, que define la salida final de la ejecución	Para definir la salida final del workflow sin una llamada externa.
wait	Pausa la ejecución por un tiempo definido, de 1 segundo a 12 horas	Cuando un paso posterior debe correr después de una demora. Consulta nodo wait.

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 todas las aristas salientes cuyo sourceHandle coincide con ese handle. Todos los demás tipos de nodo siguen todas sus aristas salientes. Flowker rechaza guardar un workflow en el que dos ramas paralelas de una misma ejecución llegan al mismo nodo (FLK-0187). Las ramas de salidas distintas de un condicional pueden volver a unirse.

​

Catálogo

---

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:

• 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:

Concepto	Qué es	Naturaleza
Proveedor	Un tipo de servicio externo (por ejemplo, Midaz, Tracer, un endpoint HTTP genérico).	Estático (publicado en el catálogo).
Configuración de proveedor	Tu conexión a una instancia de ese proveedor.	Dinámico (las creas y las gestionas).

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 el tipo catalog predeterminado, Flowker valida este mapa contra el JSON Schema del proveedor del catálogo. Para los proveedores Midaz ledger, CRM, Fees, Identity y Pix JD, config guarda solo los IDs de la organización y del ledger y un bloque auth de tipo lerian_token_endpoint con el client ID y el secret de una aplicación que tú creas. Para external_openapi, usa un validador de configuración de OpenAPI externo. Una lectura nunca devuelve la credencial que el tipo de autenticación declara.
• allowedHosts: los hosts públicos a los que esta configuración puede llamar.
• allowedPrivateHosts: hosts privados con nombre que Lerian permite que esta configuración alcance. No puedes definirla: una solicitud de tu tenant que define una lista no vacía responde FLK-0317. Levanta solo la restricción de IP privada o de loopback de Flowker: si allowedHosts no está vacía, también debe incluir el host. Las direcciones de metadatos de nube y de link-local siguen bloqueadas.
• protected: se define solo al crear. Solo una persona cambia, habilita, deshabilita o elimina una configuración protegida, y un workflow que la usa también queda protegido. Consulta Quién puede ejecutar y cambiar un workflow.
• 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 de un workflow en tiempo de ejecución. Un trigger normalmente inicia una ejecución nueva, en el nodo de trigger que se disparó. Un reintento que reutiliza una clave de idempotencia existente devuelve la ejecución ya existente en lugar de crear otra.

Cada ejecución registra:

• executionId: identificador único de esta ejecución.
• status: estado actual (pending, running, waiting, completed o failed). Una ejecución queda waiting mientras está detenida en un nodo de espera, y sus lecturas muestran entonces wait con el nodo y su plazo.
• startedBy: la aplicación o la persona que Access Manager verificó como quien llama. Flowker escribe este campo una sola vez, así que un replay o una espera reanudada lo conserva. Una ocurrencia programada retenida y forzada registra al operador que la forzó. Un inicio por programación o por Streaming Hub no trae ninguno.
• 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.
• failedStep: en una ejecución fallida, en una lista, el nodeId y el stepName del paso en el que falló. Está ausente cuando ningún paso falló.
• 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.

List workflows muestra el lastExecution de cada workflow: la ejecución más reciente por hora de inicio, ausente cuando el workflow nunca corrió. Usa Get execution status para monitorear el progreso y Get execution results para recuperar la salida completa.

Flowker puede borrar una ejecución finalizada que no envió ninguna solicitud aparte de GET, HEAD u OPTIONS después de una ventana de retención. La ventana predeterminada es de 365 días, y puedes definirla de 7 a 3650 días. Lee y define la ventana con Obtener la retención de ejecuciones y Definir la retención de ejecuciones. Una ejecución que envió cualquier otra solicitud se conserva.

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 la misma Idempotency-Key, devuelve la primera ejecución del mismo workflow en lugar de crear otra, mientras esa ejecución exista. Un replay directo incluye idempotencyReplayed: true en la respuesta. Una clave que ya usaste para ejecutar un workflow distinto responde 409 con FLK-0511. Después de que una ejecución de solo lectura se borra por la ventana de retención, la misma clave inicia una ejecución nueva.

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

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 (incluido waiting), con filtros opcionales de intervalo de tiempo y de estado.

Respuesta de ejemplo de GET /v1/dashboards/executions:

{
  "total": 12851,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102,
  "waiting": 4
}

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.