Buenas Prácticas

Esta guía reúne las mejores prácticas para diseñar, implementar y mantener workflows de forma eficiente, segura y escalable.

1. Diseño de workflows

Nombrar los nodos descriptivamente

El label de cada nodo se utiliza en las variables dinámicas con la sintaxis @. Un nodo llamado “Obtener Cliente” permite referenciar sus datos como {{@Obtener Cliente.email}}, lo cual es mucho más legible que {{#3.email}}.

Mal ejemplo:

Nodo 1: “HTTP”
Nodo 2: “Decision”
Nodo 3: “HTTP”

Buen ejemplo:

Nodo 1: “Obtener Pedido”
Nodo 2: “Validar Stock Disponible”
Nodo 3: “Actualizar Inventario”

Mantener workflows pequeños y enfocados

Aplicar el principio de responsabilidad única: cada workflow debe hacer una cosa y hacerla bien. Un workflow que gestiona pedidos no debería también encargarse de la facturación y el envío de correos de marketing.

Usar subWorkflow para dividir workflows complejos

Cuando un proceso de negocio requiere muchos pasos, dividirlo en varios workflows conectados mediante el nodo subWorkflow. Esto permite:

Reutilizar partes comunes en diferentes procesos.
Probar cada parte de forma independiente.
Reducir la complejidad visual del editor.
Facilitar el trabajo en equipo.

Documentar el propósito del workflow

Cada workflow tiene un campo de descripción. Usarlo para explicar:

Qué hace el workflow y por qué existe.
Qué sistema o proceso de negocio soporta.
Qué triggers lo activan.
Cualquier dependencia externa o prerequisito.

2. Manejo de datos

Usar variables dinámicas con referencia al nodo

Preferir {{@NombreNodo.campo}} en lugar de {{campo}}. La sintaxis con @ indica explícitamente de qué nodo provienen los datos.

# Recomendado
{{@Obtener Cliente.email}}
{{@Buscar Pedido.total}}

# No recomendado
{{email}}
{{total}}

Usar variables de memoria para datos compartidos

Los nodos setVariable y getVariable permiten almacenar datos en memoria durante la ejecución del workflow. Son útiles para:

Almacenar un token de autenticación obtenido al inicio para usarlo en múltiples llamadas HTTP.
Guardar un contador o acumulador que se actualiza en un iterador.
Compartir configuración entre ramas paralelas.

Validar datos de entrada antes de procesarlos

Antes de operar con datos externos (webhooks, APIs, formularios), validarlos con un nodo Decision o Validate. Verificar que:

Los campos obligatorios existen y no están vacíos.
Los tipos de datos son correctos (números, fechas, emails).
Los valores están dentro de rangos esperados.

Usar DataStore para persistir datos entre ejecuciones

Cuando se necesita que los datos sobrevivan entre diferentes ejecuciones del workflow, usar DataStore. Las variables de memoria solo existen durante una ejecución; DataStore persiste los datos de forma permanente.

3. Manejo de errores

Considerar siempre la rama “false” en decisiones

Cada nodo Decision tiene dos salidas: verdadero y falso. Nunca dejar la rama falsa sin conectar. Un nodo Decision sin rama falsa conectada provoca que la ejecución se detenga silenciosamente.

Usar continueOnError en nodos no críticos

Algunos nodos pueden fallar sin que eso invalide todo el flujo. Por ejemplo, un nodo que envía una notificación por Slack no debería detener el procesamiento de un pedido si Slack está temporalmente caído.

Reservar esta opción para nodos verdaderamente no críticos. Nunca activarla en nodos cuyo resultado sea necesario para pasos posteriores.

Implementar notificaciones de error

Usar nodos de notificación (SendMail, Slack, Telegram) para alertar al equipo cuando ocurren errores críticos. Incluir:

Nombre del workflow y nodo que falló.
Mensaje de error.
Datos relevantes para diagnosticar el problema.
Timestamp de la ejecución.

Monitorizar las trazas

Revisar periódicamente la tabla de trazas para:

Detectar workflows que fallan de forma recurrente.
Identificar cuellos de botella en el rendimiento.
Verificar que los workflows programados se ejecutan según lo esperado.
Auditar el procesamiento de datos sensibles.

4. Rendimiento

Limitar la concurrencia en iteradores

Al usar el nodo Iterator con la opción maxConcurrent, controlar cuántas iteraciones se ejecutan en paralelo. Un valor entre 3 y 10 suele ser adecuado para la mayoría de APIs externas.

Usar operaciones en lote (bulk) con DataStore

Cuando se necesita guardar o actualizar muchos registros, usar las operaciones bulk de DataStore en lugar de guardar registro por registro dentro de un iterador. Las operaciones bulk son significativamente más rápidas para grandes volúmenes.

Evitar loops infinitos

Cuando se implementan bucles, asegurar siempre que exista una condición de salida clara y un límite máximo de iteraciones como salvaguarda.

Usar delay para rate limiting

Cuando un workflow llama a APIs externas con límites de peticiones, insertar nodos Delay entre las llamadas para respetar esos límites.

5. Seguridad

Nunca poner credenciales directamente en la configuración

Usar siempre el sistema de credenciales de la plataforma, que:

Almacena las credenciales de forma cifrada.
Permite reutilizarlas en múltiples nodos y workflows.
Facilita la rotación sin modificar los workflows.
Evita que las credenciales aparezcan en las trazas o logs.

Validar datos de webhooks

Los webhooks son puntos de entrada públicos. Antes de procesar los datos recibidos:

Verificar la autenticidad del origen (tokens, firmas, headers).
Validar la estructura y el contenido de los datos.
Sanitizar los datos para prevenir inyecciones.
Rechazar peticiones que no cumplan con el formato esperado.

Separar entornos de desarrollo y producción

Usar el webhook de desarrollo para pruebas y el de producción para el tráfico real. Nunca probar con datos de producción sin anonimizarlos.

Limitar permisos de credenciales

Aplicar el principio de mínimo privilegio: las credenciales deben tener únicamente los permisos necesarios para la tarea que realizan.

6. Webhooks

Responder rápido

Si el workflow necesita realizar operaciones largas, usar el nodo Web Response lo antes posible para confirmar la recepción:

Webhook → Web Response (202 Accepted) → [procesamiento largo] → End

Validar el origen de la petición

Verificar tokens o claves secretas en headers.
Validar firmas HMAC cuando el sistema emisor las proporciona.
Rechazar peticiones con Web Response de error (400, 401, 403).

Filtrar eventos no deseados

Usar un nodo Decision inmediatamente después del webhook para filtrar y procesar solo los eventos relevantes.

Implementar idempotencia

Los sistemas emisores pueden reenviar el mismo evento. El workflow debe detectar y manejar duplicados:

Almacenar en DataStore los IDs de eventos ya procesados.
Antes de procesar, verificar si el evento ya fue tratado.
Si ya fue procesado, responder con éxito sin repetir la operación.

7. Schedule

Elegir intervalos razonables

No programar un workflow para que se ejecute cada minuto si la tarea no lo requiere. Evaluar la necesidad real.

Considerar zonas horarias del servidor

Los schedules se ejecutan según la zona horaria configurada en el servidor. Documentar la zona horaria esperada en la descripción del workflow.

Verificar que la ejecución anterior terminó

Usar un registro en DataStore que indique si el workflow está en ejecución. Al inicio, verificar si la ejecución anterior terminó.

Usar logs para auditar ejecuciones programadas

Los workflows programados se ejecutan sin intervención humana. Implementar registro de auditorías con inicio, fin, cantidad de registros y errores.

8. Variables dinámicas

Usar `{{@NombreNodo.campo}}` para referenciar nodos específicos

{{@Obtener Cliente.nombre}}      → Claro: el nombre viene del nodo "Obtener Cliente"
{{@Calcular Precio.total}}       → Claro: el total viene del nodo "Calcular Precio"

Si se reorganizan los nodos, las referencias por nombre siguen funcionando.

Usar `{{var.nombre}}` para datos compartidos entre workflows

Permiten pasar configuración, parámetros o resultados entre niveles de ejecución sin necesidad de mapear cada campo individualmente.

Usar `{{#1.campo}}` solo cuando la posición relativa es relevante

Útil dentro de iteradores donde siempre se quiere referenciar al nodo inmediatamente anterior. En la mayoría de los casos, la referencia por nombre es preferible.

Probar variables en modo desarrollo

Verificar que todas las variables dinámicas resuelven correctamente antes de activar en producción.

9. DataStore

Diseñar grupos lógicos

Organizar los datos usando grupos que reflejen la estructura del negocio:

clientes - datos de clientes y contactos.
pedidos - pedidos y sus estados.
configuracion - parámetros y opciones del sistema.
cache - datos temporales de APIs externas.

Usar claves significativas

Las claves deben ser identificadores con significado de negocio: email para clientes, order_id para pedidos, sku para productos.

Aprovechar tags para categorizar y filtrar

Los tags permiten añadir metadatos para facilitar búsquedas: marcar estado de procesamiento, categorizar registros, agrupar por lote o ejecución.

Usar DataStore Trigger para reaccionar a cambios en tiempo real

Es más eficiente que un workflow programado que consulta periódicamente si hay cambios.

Limpiar datos obsoletos periódicamente

Crear un workflow programado que elimine registros antiguos, archive datos históricos y limpie registros de caché expirados.

10. Patrones comunes de workflow

a. Webhook → Procesar → Responder

+----------+     +----------+     +----------+     +--------------+
| Webhook  | --> | Decision | --> |   HTTP   | --> | Web Response |
| (recibir)|     | (validar)|     |(procesar)|     |  (200 OK)    |
+----------+     +----------+     +----------+     +--------------+
                      |
                      | false
                      v
                +--------------+
                | Web Response |
                |  (400 Error) |
                +--------------+

Cuándo usarlo: Cuando un sistema externo necesita enviar datos y esperar una respuesta síncrona.

b. ETL (Extract-Transform-Load)

+---------+     +---------+     +---------------+     +-----------+     +-----+
|  Start  | --> |  HTTP   | --> | DataTransform | --> | DataStore | --> | End |
|(schedule)|    |(extract)|     |  (transform)  |     |  (load)   |     |     |
+---------+     +---------+     +---------------+     +-----------+     +-----+

Cuándo usarlo: Para sincronizaciones periódicas, importaciones, migraciones, reportes agregados.

c. Fan-out / Fan-in (Iterator + Merge)

+---------+     +---------+     +----------+     +-----------+     +-----------+
|  Start  | --> |  HTTP   | --> | Iterator | --> |   HTTP    | --> | DataStore |
|         |     | (lista) |     |          |     | (detalle) |     | (guardar) |
+---------+     +---------+     +----------+     +-----------+     +-----------+
                                                                         |
                                                                         v
                                +-----+     +----------+           +-----------+
                                | End | <-- | SendMail | <-------- |   Merge   |
                                |     |     | (resumen)|           | (reunir)  |
                                +-----+     +----------+           +-----------+

Cuándo usarlo: Para procesar listas donde cada elemento requiere una operación individual.

d. Aprobación humana

+-------------+     +-----------+     +----------+     +------------+
| FormTrigger | --> | DataStore | --> | SendMail | --> | FormRender |
| (solicitud) |     | (guardar) |     |(notificar)|    | (aprobacion)|
+-------------+     +-----------+     +----------+     +------------+

Cuándo usarlo: Para procesos de aprobación de gastos, solicitudes de vacaciones, aprobación de publicaciones.

e. Sincronización bidireccional

+---------+     +---------+     +----------+     +------------+
|  Start  | --> |  HTTP   | --> | Iterator | --> |  Decision  |
|(schedule)|    |(sistema A)|    |          |     |(existe en B?)|
+---------+     +---------+     +----------+     +------------+
                                                   |         |
                                                   | true    | false
                                                   v         v
                                              +----------+ +----------+
                                              | HTTP PUT | | HTTP POST|
                                              |(actualizar)| |(crear)  |
                                              +----------+ +----------+
                                                   |         |
                                                   v         v
                                              +-----------+
                                              |   Merge   |
                                              +-----------+

Cuándo usarlo: Para mantener sincronizados dos sistemas (CRM y ERP, tienda online y almacén).

f. Notificación multi-canal

+---------+     +----------+
| Webhook | --> | Decision |
| (evento)|     |  (tipo)  |
+---------+     +----------+
                  |    |    |
          crítico |    |    | info
                  v    |    v
            +-------+  |  +-------+
            | Slack |  |  | Slack |
            +-------+  |  +-------+
                |       |
                v       | normal
           +----------+ |
           | Telegram | |
           +----------+ v
                |  +----------+
                v  | SendMail |
           +----------+------+
           | SendMail |
           +----------+
                |
                v
           +---------+
           |  Merge  |
           +---------+
                |
                v
           +-------+
           |  End  |
           +-------+

Cuándo usarlo: Para sistemas de alertas donde la urgencia determina los canales utilizados.

Resumen

Claridad: Nombrar bien los nodos, documentar los workflows, usar variables con referencia explícita.
Robustez: Validar datos de entrada, manejar la rama falsa, implementar notificaciones de error.
Eficiencia: Controlar la concurrencia, usar operaciones bulk, elegir intervalos de schedule razonables.
Seguridad: Usar el sistema de credenciales, validar webhooks, aplicar mínimo privilegio.
Mantenibilidad: Dividir workflows complejos, limpiar datos obsoletos, monitorizar las trazas.