Guía de diseño de workflows

Diseña workflows de Flowker con confianza — tipos de node, edges, patrones reales, transiciones de estado y mejores prácticas de orquestación.

Diseña workflows en Flowker con claridad y control. Esta guía recorre los tipos de nodes, 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 nodes

---

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

​

trigger

Un node trigger es un punto de entrada de ejecución. Los workflows en draft pueden estar incompletos, pero la activación requiere al menos un node trigger. Cuando una ejecución comienza mediante un trigger, el motor entra por ese node y enruta desde él.

Los ejemplos de esta página muestran solo la topología de nodes. Un node trigger real también lleva un triggerType y la configuración de ese trigger en su data — consulta Configurar un trigger de webhook o Ejecutar un workflow con un schedule.

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

​

executor

Llama a un servicio externo a través de una configuración de provider. Este es el bloque de construcción principal para integrarse con motores de fraude, providers de pago, servicios de notificación y otros sistemas externos.

Los ejemplos de esta página muestran solo la topología de nodes. Un node executor real también lleva un providerConfigId y, si usa un executor del catálogo, un executorId en su data. Un node que llama a una operación de un documento OpenAPI cargado omite executorId y lleva operation_path y operation_method — consulta la Guía de integración.

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

​

conditional

Evalúa una condición contra el contexto de ejecución y enruta hacia diferentes ramas según el resultado. Usa nodes 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.

La condición vive en data.condition del node. Una expresión de texto libre se evalúa como booleana y produce el handle de salida true o false; cada edge de salida declara qué handle sigue mediante sourceHandle. Los nodes conditional creados en la Console usan una condición estructurada basada en casos, donde cada caso enruta hacia su propio handle de salida — consulta el Editor de canvas.

{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score",
  "data": { "condition": "node-fraud-check.riskScore < 70" }
}

​

action

Representa una operación interna síncrona set_output. Puede escribir un valor de salida interpolado y, opcionalmente, reemplazar el estado de respuesta HTTP síncrona. No proporciona una pausa integrada, emisión genérica de eventos ni una operación genérica de cambio de estado.

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

​

Edges

---

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

Campo	Descripción
id	Identificador único del edge.
source	ID del node de origen.
target	ID del node de destino.
sourceHandle	Handle de salida del node de origen que sigue este edge. Obligatorio para enrutar desde un node conditional: debe coincidir con el resultado de la rama (true o false para una condición de texto libre).
condition	Campo legado de texto libre mantenido por compatibilidad. No se evalúa para el enrutamiento — déjalo vacío en workflows nuevos.
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": "true",
  "label": "Approved"
}

El enrutamiento depende del tipo del node de origen. Un node conditional evalúa su data.condition y sigue el único edge de salida cuyo sourceHandle coincide con el resultado de la rama; si ningún edge coincide, esa rama termina. Todos los demás tipos de node siguen todos sus edges de salida cuando se completan 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.

• draft — El estado inicial. Todas las modificaciones (agregar nodes, 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 nodes 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 nodes 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 nodes 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 nodes 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 node conditional evalúa su condición y enruta la ejecución en consecuencia. El resultado de la rama selecciona qué edge de salida se sigue, según la coincidencia del sourceHandle.

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",
      "data": { "condition": "n2.fraudScore < 70" }
    },
    { "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": "true",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "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",
      "data": { "condition": "n2.fraudScore < 70" }
    },
    { "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": "true",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "High risk"
    }
  ]
}

​

Orquestación de pagos

Un flujo lineal que valida los datos de pago entrantes, los enruta al provider 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

Usa un workflow para enviar una revisión de documentos a un sistema de aprobación externo. Flowker no tiene una pausa integrada: para una revisión humana asíncrona, inicia una ejecución de workflow posterior y separada cuando tu sistema de aprobación publique su decisión.

​

Flujo de aprobación manual

Una solicitud se envía para revisión. Un executor consulta la decisión de la revisión en el sistema externo. Un node conditional luego enruta hacia el camino de aprobación o rechazo. Las ejecuciones de Flowker corren de principio a fin — no existe un paso de pausa integrado, así que una decisión humana debe venir de un sistema externo que el workflow consulta.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "executor",    "name": "Get Approval Decision" },
    {
      "id": "n4",
      "type": "conditional",
      "name": "Decision Received",
      "data": { "condition": "n3.decision == 'approved'" }
    },
    { "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": "true",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}

​

Mejores prácticas

---

​

Convenciones de nomenclatura de nodes

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

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

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

​

Expresiones de condición

Las condiciones de texto libre en los nodes conditional se evalúan contra el contexto de ejecución en tiempo 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
• Combínalas con AND / OR cuando sea necesario: <nodeId>.score < 70 AND <nodeId>.verified == true

Evita expresiones complejas que sean difíciles de leer o depurar. Si la lógica no es trivial, dale al node conditional un nombre claro que encapsule la decisión.

Una condición ausente o que falla al evaluarse en tiempo de ejecución hace fallar la ejecución (FLK-0105 identifica una expresión condicional inválida). Siempre prueba las condiciones 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 nodes conditional para cada punto de decisión que pueda fallar.
• Usa nodes executor separados para lógica de reintentos o providers de respaldo.
• Nombra las rutas de error de forma clara (por ejemplo, Reject and Notify, Fallback to Manual Review) para que los registros de ejecución 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 node 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:

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

2. Realiza tus cambios en el borrador.

3. Valida o previsualiza el borrador. Actívalo antes de ejecutar pruebas de ejecución.

4. Activa la nueva versión.

5. 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.

​

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 nodes — 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