Guía de diseño de workflows

Diseña workflows en Flowker con claridad y control. Esta guía recorre los tipos de nodos, edges, patrones del mundo real, transiciones de estado, límites técnicos y mejores prácticas para ayudarte a construir orquestaciones confiables y mantenibles.

Tipos de nodos

Todo workflow se construye a partir de nodos. Cada nodo tiene un type que define cómo Flowker lo procesa en tiempo de ejecución.

trigger

El punto de entrada de un workflow. Todo workflow debe comenzar con un nodo trigger. Cuando la ejecución comienza, el motor ingresa por este nodo y empieza a enrutar desde él.

{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}

executor

Llama a un executor externo: un servicio HTTP, API o proveedor registrado en Flowker. Este es el bloque de construcción principal para integrarse con motores de fraude, proveedores de pago, servicios de notificación y otros sistemas externos.

{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}

conditional

Evalúa una expresión contra el contexto de ejecución y enruta hacia diferentes ramas según el resultado. Usa nodos conditional para implementar lógica de ramificación, por ejemplo, dirigir hacia un flujo de aprobación cuando el riesgo es alto, o continuar directamente cuando es bajo.

{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score"
}

action

Representa operaciones internas del workflow que no involucran llamadas externas, como transformar datos, emitir eventos o registrar cambios de estado.

{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}

Edges

Los edges conectan nodos y definen las rutas de ejecución. Cada edge incluye los siguientes campos:

Campo	Descripción
`id`	Identificador único del edge.
`source`	ID del nodo de origen.
`target`	ID del nodo de destino.
`sourceHandle`	Puerto de salida del nodo de origen donde se origina el edge.
`condition`	Expresión que debe evaluarse como verdadera para que el edge se siga.
`label`	Etiqueta legible utilizada para visualización y depuración.

Ejemplo de edge

{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "approved",
  "condition": "node-risk-decision.riskScore < 70",
  "label": "Approved"
}

El campo condition se evalúa contra el contexto de ejecución. Si se omite, el edge siempre se sigue cuando el nodo de origen se completa exitosamente.

Transiciones de estado

Los workflows siguen un ciclo de vida bien definido. Comprender estas transiciones es clave para desplegar y evolucionar workflows de manera segura.

Diagrama de transición de estados del workflow mostrando tres estados: draft, active e inactive. Una flecha etiquetada 'activate' apunta de draft a active. Una flecha etiquetada 'deactivate' apunta de active a inactive. Una flecha etiquetada 'draft' apunta de inactive de vuelta a draft.

draft — El estado inicial. Todas las modificaciones (agregar nodos, editar edges, cambiar configuración) solo están permitidas en estado draft.
active — Un workflow que ha sido activado. Puede ser ejecutado. No se permiten modificaciones mientras está activo.
inactive — Un workflow que ha sido desactivado. Ya no puede ser ejecutado, pero puede moverse de vuelta a draft para edición.

Reglas

Solo un workflow en draft puede ser activado (transición: draft → active).
Solo un workflow en active puede ser desactivado (transición: active → inactive).
Solo un workflow en inactive puede moverse de vuelta a draft (transición: inactive → draft).
Intentar una transición inválida devuelve el error FLK-0102.
Intentar modificar un workflow que no está en draft devuelve el error FLK-0103.

Mover un workflow inactivo de vuelta a draft

Si desactivaste un workflow y quieres editarlo de nuevo, muévelo de vuelta a draft llamando a POST /v1/workflows/{id}/draft. Esto hace que el workflow sea editable sin necesidad de clonarlo. Esto es útil cuando desactivaste un workflow por error o cuando quieres iterar sobre un workflow existente en lugar de crear una copia.

Solo los workflows inactivos pueden moverse a draft. Si necesitas modificar un workflow activo sin sacarlo de línea, usa el enfoque de clone descrito a continuación.

Iterar de forma segura con clone

Para modificar un workflow activo, primero clónalo. La clonación crea un nuevo draft desde cualquier estado, copiando todos los nodos y edges. Luego puedes actualizar, probar y activar sin impactar la versión actual. Este es el enfoque recomendado para el versionado en producción.

Límites técnicos

Límite	Valor	Código de error
Máximo de nodos por workflow	100	`FLK-0113`
Máximo de edges por workflow	200	`FLK-0114`
Máximo del payload de entrada de ejecución	1 MB	`FLK-0506`

Ten en cuenta estos límites al diseñar flujos complejos. Los workflows con más de ~50 nodos generalmente indican que el flujo debería dividirse en workflows más pequeños y componibles.

Patrones comunes

Secuencial

El patrón más simple. Los nodos se ejecutan en una secuencia lineal. Úsalo cuando cada paso depende del anterior y no se requiere ramificación.

Ejemplo: Orquestación de pagos

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
  ]
}

Ramificación condicional

Un nodo conditional evalúa una expresión y enruta la ejecución en consecuencia. Cada edge de salida lleva su propia condition.

Ejemplo: Verificación antifraude

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    { "id": "n3", "type": "conditional", "name": "Evaluate Score" },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject Transaction" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "approved",
      "condition": "n2.fraudScore < 70",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "rejected",
      "condition": "n2.fraudScore >= 70",
      "label": "Rejected"
    }
  ]
}

Ejemplos del mundo real

Verificación antifraude

Una transacción llega, se obtiene una puntuación de fraude y la ejecución se enruta hacia aprobación o rechazo.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    { "id": "n3", "type": "conditional", "name": "Evaluate Fraud Score" },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject and Notify" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "approved",
      "condition": "n2.fraudScore < 70",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "rejected",
      "condition": "n2.fraudScore >= 70",
      "label": "High risk"
    }
  ]
}

Orquestación de pagos

Un flujo lineal que valida los datos de pago entrantes, los enruta al proveedor adecuado y envía una confirmación.

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
  ]
}

Onboarding KYC

Los documentos de un cliente son verificados por un servicio externo. Un nodo conditional evalúa si se requiere revisión manual. Si es así, se activa una acción de aprobación manual antes de activar la cuenta.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Onboarding Started" },
    { "id": "n2", "type": "executor",    "name": "Run Document Check" },
    { "id": "n3", "type": "conditional", "name": "Manual Review Required?" },
    { "id": "n4", "type": "action",      "name": "Request Manual Approval" },
    { "id": "n5", "type": "executor",    "name": "Activate Account" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Check complete" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "review",
      "condition": "n2.reviewRequired == true",
      "label": "Needs review"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "clear",
      "condition": "n2.reviewRequired == false",
      "label": "Auto-approved"
    },
    { "id": "e5", "source": "n4", "target": "n5", "label": "Approved" }
  ]
}

Flujo de aprobación manual

Una solicitud se envía para revisión. Una acción de aprobación espera una decisión. Un nodo conditional luego enruta hacia el camino de aprobación o rechazo.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "action",      "name": "Await Approval Decision" },
    { "id": "n4", "type": "conditional", "name": "Decision Received" },
    { "id": "n5", "type": "executor",    "name": "Process Approved Request" },
    { "id": "n6", "type": "executor",    "name": "Notify Rejection" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
    {
      "id": "e4",
      "source": "n4",
      "target": "n5",
      "sourceHandle": "approved",
      "condition": "n3.decision == 'approved'",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "rejected",
      "condition": "n3.decision == 'rejected'",
      "label": "Rejected"
    }
  ]
}

Mejores prácticas

Convenciones de nomenclatura de nodos

Usa nombres descriptivos y orientados a la acción que comuniquen lo que hace el nodo, no de qué tipo es.

correcto: Validate Payment Data, Get Fraud Score, Notify Customer, Await Approval
incorrecto: executor1, conditional node, node3

Los buenos nombres hacen que los workflows sean legibles sin necesidad de abrir la configuración del nodo. También aparecen en los registros de auditoría y las trazas de ejecución, lo que hace que la depuración sea significativamente más rápida.

Expresiones de condición en edges

Las condiciones en los edges se evalúan contra el contexto de ejecución. Mantenlas simples y explícitas:

Usa comparaciones directas de campos: <nodeId>.status == 'approved'
Usa comparaciones numéricas: <nodeId>.riskScore < 70
Usa campos booleanos: <nodeId>.reviewRequired == true

Evita expresiones complejas que sean difíciles de leer o depurar. Si la lógica no es trivial, considera enrutar a través de un nodo conditional que encapsule la decisión con un nombre claro. Una expresión inválida devuelve FLK-0105. Siempre valida las expresiones antes de activar un workflow.

Estrategias de manejo de errores

Diseña los workflows para manejar los fallos de forma explícita:

Agrega rutas de rechazo desde nodos conditional para cada punto de decisión que pueda fallar.
Usa nodos executor separados para lógica de reintentos o proveedores de respaldo.
Nombra las rutas de error de forma clara (por ejemplo, Reject and Notify, Fallback to Manual Review) para que los registros de auditoría sean autoexplicativos.

Evitar ciclos

Flowker utiliza una protección contra ciclos basada en DFS en tiempo de ejecución. Si se detecta un ciclo durante la ejecución, el workflow falla con FLK-0508. Los ciclos no se detectan en tiempo de diseño, por lo que debes validar la estructura de edges antes de activar. Reglas para prevenir ciclos:

Los edges siempre deben apuntar hacia adelante en el flujo, nunca de vuelta a un nodo previamente ejecutado.
Revisa el grafo visualmente antes de activar cualquier workflow con rutas de ramificación o convergencia.
Si se necesita un reintento o bucle, modélalo como una invocación de workflow separada, no como un edge de retorno en el grafo actual.

Versionado mediante clone

Nunca edites un workflow activo directamente. En su lugar:

Clona el workflow (crea un nuevo draft con todos los nodos y edges copiados).

Realiza tus cambios en el borrador.

Prueba el borrador con ejecuciones de prueba.

Activa la nueva versión.

Desactiva la versión anterior si ya no es necesaria.

Esto preserva el historial de ejecución de la versión activa y te proporciona una ruta de reversión limpia si la nueva versión tiene problemas.

Crear workflows a partir de templates

En lugar de construir un workflow desde cero, puedes crearlo a partir de un template pre-construido en el catálogo. Los templates proporcionan estructuras listas de nodos y edges para patrones comunes — validación de pagos, verificaciones de fraude, flujos de onboarding y más. Llama a POST /v1/workflows/from-template con el ID del template, un nombre para el nuevo workflow y cualquier parámetro que el template requiera. El resultado es un nuevo workflow con estado draft que puedes revisar, personalizar y activar.

Ejemplo de solicitud

POST /v1/workflows/from-template

{
  "templateId": "payment-validation",
  "params": {
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "currency": "USD"
  },
  "name": "Payment Validation - USD",
  "description": "Valida pagos USD antes de la escritura en el ledger"
}

Para descubrir templates disponibles y sus parámetros obligatorios, usa los endpoints Listar templates del catálogo y Consultar template del catálogo. El endpoint de detalle del template devuelve un JSON Schema que describe los parámetros esperados, incluyendo opciones dinámicas para campos que referencian configuraciones de provider.

Referencia de errores

Los siguientes códigos de error son relevantes para el diseño y la ejecución de workflows:

Código	Descripción
`FLK-0102`	Transición de estado inválida
`FLK-0103`	El workflow no puede ser modificado — no está en estado draft
`FLK-0105`	Expresión condicional inválida
`FLK-0113`	Demasiados nodos — el máximo es 100
`FLK-0114`	Demasiados edges — el máximo es 200
`FLK-0506`	Payload de entrada de ejecución demasiado grande — el máximo es 1 MB
`FLK-0508`	Ciclo detectado durante la ejecución del workflow

Documentation Index

​Tipos de nodos

​trigger

​executor

​conditional

​action

​Edges

​Ejemplo de edge

​Transiciones de estado

​Reglas

​Mover un workflow inactivo de vuelta a draft

​Iterar de forma segura con clone

​Límites técnicos

​Patrones comunes

​Secuencial

​Ramificación condicional

​Ejemplos del mundo real

​Verificación antifraude

​Orquestación de pagos

​Onboarding KYC

​Flujo de aprobación manual

​Mejores prácticas

​Convenciones de nomenclatura de nodos

​Expresiones de condición en edges

​Estrategias de manejo de errores

​Evitar ciclos

​Versionado mediante clone

​Crear workflows a partir de templates

​Referencia de errores

Tipos de nodos

trigger

executor

conditional

action

Edges

Ejemplo de edge

Transiciones de estado

Reglas

Mover un workflow inactivo de vuelta a draft

Iterar de forma segura con clone

Límites técnicos

Patrones comunes

Secuencial

Ramificación condicional

Ejemplos del mundo real

Verificación antifraude

Orquestación de pagos

Onboarding KYC

Flujo de aprobación manual

Mejores prácticas

Convenciones de nomenclatura de nodos

Expresiones de condición en edges

Estrategias de manejo de errores

Evitar ciclos

Versionado mediante clone

Crear workflows a partir de templates

Referencia de errores