Primeros Pasos

Bienvenido a Floogos. Aquí aprenderás a diseñar y crear workflows desde cero, desde el análisis del problema hasta la activación en producción.

Requisitos previos

• Tener acceso a la plataforma
• Estar autenticado con tu cuenta
• Acceso a credenciales si necesitas APIs externas o envíos de correo

1. Antes de abrir el editor: analizar el problema

El error más común es empezar a arrastrar nodos sin haber pensado el flujo. Antes de tocar el editor, responde estas preguntas:

Preguntas clave

a) ¿Qué evento inicia el proceso?

• ¿Alguien envía un formulario? → FormTrigger
• ¿Un sistema externo notifica algo? → Webhook
• ¿Debe ejecutarse a una hora fija? → Start + Schedule
• ¿Un dato cambia en mi sistema? → DataStore Trigger
• ¿Llega un mensaje de Telegram/MQTT/Redis? → Trigger correspondiente

b) ¿Qué datos necesito y de dónde vienen?

• ¿De una API externa? → HTTP
• ¿De una base de datos? → SQL Query
• ¿De un archivo? → ReadExcel, CSV, PDF
• ¿Ya los tengo en el DataStore? → DataStore (filter)
• ¿Los ingresa un usuario? → FormTrigger / Webhook

c) ¿Qué decisiones hay que tomar?

• ¿Hay condiciones tipo sí/no? → Decision
• ¿Hay múltiples caminos según un valor? → Switch / Router
• ¿Hay validaciones que pueden fallar? → Decision + rama de error

d) ¿Qué acciones debo ejecutar?

• ¿Enviar email? → SendMail
• ¿Llamar una API? → HTTP
• ¿Guardar datos? → DataStore / SQL Query
• ¿Notificar a alguien? → Slack / Telegram / SendNotification
• ¿Generar un archivo? → GeneratePDF / SaveToExcel / CSVCreate

e) ¿Hay repetición?

• ¿Debo procesar una lista de elementos? → Iterator + Merge
• ¿Debo hacer lo mismo para N registros? → Iterator

f) ¿Qué pasa si algo falla?

• ¿Debo notificar a alguien?
• ¿Debo reintentar?
• ¿Puedo continuar sin ese paso?

---

2. Dibujar el flujo en papel

Antes de construir, dibuja el camino de los datos. No necesitas precisión, solo la secuencia lógica.

Ejemplo - “Cuando un cliente hace un pedido en mi tienda, verificar stock y enviar confirmación”:

1. Llega el pedido (Webhook de Shopify)
2. Consultar stock del producto (HTTP a mi API de inventario)
3. ¿Hay stock?
   → Sí: Confirmar pedido, enviar email al cliente
   → No: Notificar al equipo por Slack, marcar pedido como pendiente
4. Guardar resultado en DataStore

Esto se traduce directamente a:

Webhook → HTTP (stock) → Decision (¿hay stock?)
  → true:  HTTP (confirmar) → SendMail (cliente) → DataStore (guardar)
  → false: Slack (equipo) → DataStore (guardar pendiente)
→ Merge → End

Cada línea de tu boceto es un nodo. Cada pregunta es una Decision.

---

3. Regla de oro: un workflow, un propósito

Un workflow debe hacer UNA cosa bien. Si al describir tu workflow necesitas usar la palabra “y” más de dos veces, probablemente debas dividirlo.

Mal ejemplo: un workflow que hace todo

Recibir pedido Y verificar stock Y procesar pago Y generar factura
Y enviar al almacén Y notificar al cliente Y actualizar el CRM
Y sincronizar con contabilidad

Esto es frágil: si falla la factura, se detiene todo. Si cambias el CRM, tocas un workflow enorme.

Buen ejemplo: workflows separados y conectados

Workflow 1: "Recibir pedido"
  Webhook → Validar → DataStore (guardar pedido) → SubWorkflow (verificar stock)

Workflow 2: "Verificar stock"
  Start → HTTP (inventario) → Decision → DataStore (actualizar estado)
  → SubWorkflow (procesar pago)

Workflow 3: "Procesar pago"
  Start → Stripe (cobrar) → Decision (¿exitoso?)
  → true: SubWorkflow (generar factura)
  → false: SendMail (error de pago)

Workflow 4: "Generar factura"
  Start → Bill.pt (crear documento) → SendMail (enviar factura) → End

Workflow 5: "Notificaciones"
  DataStore Trigger (nuevo pedido confirmado)
  → Slack (equipo) → SendMail (cliente) → End

Cada workflow es testeable por separado, reutilizable y fácil de mantener.

---

4. Cuándo usar SubWorkflow

El nodo SubWorkflow ejecuta otro workflow como si fuera una función. Úsalo cuando:

Situación	Ejemplo
Reutilización: La misma lógica se usa en varios flujos	”Enviar factura” se llama desde pedidos, suscripciones y devoluciones
Complejidad: Un flujo tiene más de 10-12 nodos	Dividir en bloques lógicos de 5-8 nodos cada uno
Responsabilidad: Equipos distintos gestionan partes del proceso	El equipo de pagos mantiene su workflow, el de logística el suyo
Testing: Necesitas probar una parte del proceso aislada	Probar solo la facturación sin ejecutar todo el pedido
Mantenimiento: Un cambio en una parte no debe afectar al resto	Cambiar proveedor de envío sin tocar el flujo de pagos

Modos de SubWorkflow

• Síncrono: Espera a que el sub-workflow termine y continúa con sus datos de salida
• Asíncrono: Lanza el sub-workflow y continúa inmediatamente sin esperar
• Paralelo: Lanza múltiples instancias en paralelo

No uses SubWorkflow cuando

• El flujo es lineal y sencillo (menos de 8 nodos)
• Solo se usa en un lugar y no hay previsión de reutilizarlo
• La división artificial complica más que simplifica

---

5. Proceso paso a paso para crear un workflow

Paso 1: Definir entrada y salida

Escribe en una línea:

• Entrada: “Recibo un JSON con order_id, product_id, quantity desde Shopify”
• Salida: “El cliente recibe un email de confirmación y el pedido queda guardado en DataStore”

Paso 2: Listar las acciones intermedias

Escribe cada acción como un paso numerado:

1. Recibir datos del webhook
2. Consultar el producto en mi API
3. Verificar si hay stock suficiente
4. Si hay stock: confirmar el pedido
5. Si no hay stock: notificar al equipo
6. Guardar resultado
7. Enviar email al cliente

Paso 3: Identificar los tipos de nodo

Para cada paso, asigna el tipo de nodo:

Paso	Nodo	Config principal
1. Recibir datos	Webhook	-
2. Consultar producto	HTTP	URL: {{var.api_url}}/products/{{product_id}}
3. Verificar stock	Decision	data.stock >= {{#2.quantity}}
4. Confirmar pedido	HTTP	POST a API de pedidos
5. Notificar equipo	Slack	Mensaje con detalles
6. Guardar resultado	DataStore	group: “pedidos”, key: {{@Webhook.order_id}}
7. Enviar email	SendMail	to: {{@Webhook.customer_email}}

Paso 4: Dibujar las conexiones

Webhook
  → HTTP (consultar producto)
  → Decision (¿hay stock?)
    → true: HTTP (confirmar) → DataStore (guardar confirmado)
    → false: Slack (notificar) → DataStore (guardar pendiente)
  → Merge
  → SendMail (cliente)
  → End

Paso 5: Construir en el editor

Ahora sí, abre el editor y:

1. Arrastra el trigger (Webhook)
2. Agrega los nodos en orden
3. Conecta las flechas
4. Configura cada nodo con los parámetros
5. Usa nombres descriptivos en los labels (se usan en {{@Label.campo}})

Paso 6: Probar con datos reales

1. Usa la URL de desarrollo (/webhooks-dev/{hash}) para ver trazas detalladas
2. Envía un request de prueba con curl o Postman
3. Revisa las trazas: cada nodo muestra entrada, salida y tiempo de ejecución
4. Verifica que las variables dinámicas resuelven correctamente
5. Prueba los caminos alternativos (rama true Y rama false)

---

6. Simplicidad: la regla más importante

Señales de que un workflow es demasiado complejo

• Tiene más de 15 nodos → dividir con SubWorkflow
• No puedes explicar lo que hace en una frase → dividir en partes
• Tiene más de 3 niveles de Decision anidadas → usar Switch o Router
• Un cambio en un nodo rompe nodos lejanos → las dependencias están acopladas
• Tarda más de 30 segundos en ejecutarse → optimizar o paralelizar

Cómo simplificar

Antes (complejo):

Webhook → HTTP → Decision → HTTP → Decision → HTTP → Decision
  → SendMail → DataStore → HTTP → Slack → End

Después (simple):

Workflow "Recibir pedido":
  Webhook → Decision (¿válido?) → DataStore → SubWorkflow("Procesar")

Workflow "Procesar pedido":
  Start → HTTP (stock) → Decision → SubWorkflow("Notificar")

Workflow "Notificar resultado":
  Start → SendMail → Slack → End

Principios de simplicidad

1. Nombre descriptivo: Si no puedes nombrar el workflow en 3-4 palabras, es demasiado amplio
2. Un trigger, un propósito: Cada workflow responde a UN evento y produce UN resultado
3. Profundidad máxima: No más de 2 niveles de Decision anidadas. Si necesitas más, usa Switch
4. Reutilizar antes que duplicar: Si copias nodos entre workflows, crea un SubWorkflow
5. Datos limpios: Usa DataTransform o MapFunction al principio para normalizar los datos

---

7. Errores comunes de principiantes

Error	Problema	Solución
No validar datos de entrada	El workflow falla con datos inesperados	Agregar Decision o Validate después del trigger
Ignorar la rama false	El workflow se detiene si la condición falla	Siempre conectar ambas ramas de Decision
No usar Merge después de Decision	Ramas paralelas nunca se unen	Agregar Merge para reunir los caminos
Poner credenciales en campos de texto	Las credenciales quedan expuestas en logs	Siempre usar el campo credentials_id
Workflow gigante sin SubWorkflows	Imposible de mantener y depurar	Dividir en workflows de 5-10 nodos
No nombrar los nodos	Las variables {{@Nodo.campo}} no funcionan bien	Usar labels descriptivos: “Consultar Stock”, “Enviar Email”
No probar la rama de error	Falla en producción sin aviso	Probar cada camino posible en desarrollo
Iterator sin Merge	Los datos se pierden después de iterar	Siempre cerrar Iterator con Merge o MergeIterator
Variables {{campo}} ambiguas	Confunde datos de distintos nodos	Usar {{@NombreNodo.campo}} para ser explícito
Schedule cada minuto innecesariamente	Sobrecarga del sistema y APIs	Usar el intervalo mínimo que realmente se necesita

---

8. Checklist antes de activar un workflow

Antes de poner un workflow en producción, verifica:

• El workflow tiene un nombre descriptivo
• Todos los nodos tienen labels claros
• Las credenciales están configuradas (no hardcodeadas)
• La rama false de cada Decision está conectada
• Cada Iterator tiene su Merge correspondiente
• Se probó con datos reales usando la URL de desarrollo
• Se probaron todos los caminos posibles (true, false, errores)
• Los nodos críticos tienen manejo de error (continueOnError o rama de error)
• Existe alguna notificación si el workflow falla (email, Slack, etc.)
• El schedule (si existe) tiene un intervalo razonable
• Las variables dinámicas resuelven correctamente
• El workflow no supera los 15 nodos (si lo hace, considerar SubWorkflow)

---

Resumen

1. Analizar: ¿Qué entra? ¿Qué sale? ¿Qué decisiones hay?
2. Dibujar: Boceto en papel con la secuencia lógica
3. Dividir: Un workflow = un propósito. Usar SubWorkflow para lo demás
4. Construir: Nodos en orden, nombres descriptivos, credenciales seguras
5. Probar: URL de desarrollo, ambas ramas, datos reales
6. Simplificar: Si es complejo, dividir. Si se repite, reutilizar.