Triggers - Iniciar Workflows

1. Que es un Trigger

Un trigger es el punto de entrada que inicia la ejecución de un workflow. Todo workflow comienza obligatoriamente con un nodo de tipo trigger, que define como y cuando se activa el flujo, y que datos iniciales se inyectan en la ejecución.

El trigger determina:

• La forma en que se inicia el workflow (manual, programado, por evento externo, por mensaje, etc.)
• Los datos iniciales que recibe el primer nodo del flujo
• Los metadatos asociados a la ejecución (origen, timestamp, parámetros)

---

2. Tipos de Triggers disponibles

a. Start (Inicio manual)

Categoría: init

Inicia el workflow de forma manual o mediante una programación (schedule). Es el trigger mas básico y versatil.

Caracteristicas:

• Permite definir datos iniciales en formato JSON que se inyectan como entrada del primer nodo.
• Es el trigger por defecto para workflows programados mediante expresiones cron (schedule).
• Cuando se ejecuta por schedule, los datos iniciales definidos en la configuración se usan como entrada.
• Cuando se ejecuta manualmente, se pueden sobrescribir los datos iniciales.

Configuración:

Campo	Descripción
initialData	Objeto JSON con los datos iniciales del workflow
schedule	Expresion cron para ejecución programada (opcional)
active_schedule	Activar o desactivar la programación (true/false)

Ejemplo de datos iniciales:

{
  "empresa": "MiEmpresa",
  "fecha": "2026-03-23",
  "parametros": {
    "limite": 100,
    "offset": 0
  }
}

---

b. Webhook

Categoría: init

Inicia el workflow cuando recibe una petición HTTP externa. Ideal para integraciones con sistemas de terceros que envian notificaciones o datos mediante HTTP.

Caracteristicas:

• Se genera automáticamente una URL única para cada webhook con el formato: /webhooks/{hash}
• Soporta peticiones GET (los query params se convierten en el payload) y POST (el body de la petición se usa como payload).
• Incluye metadata de la petición en el campo _request.
• Dispone de una URL de desarrollo para pruebas: /webhooks-dev/{hash}

Metadata incluida en _request:

Campo	Descripción
method	Método HTTP utilizado (GET, POST)
timestamp	Fecha y hora de recepción de la petición
headers	Cabeceras HTTP de la petición
ip	Dirección IP del cliente que realizo la petición

Ejemplo de datos que recibe el workflow:

{
  "nombre": "Juan",
  "email": "juan@ejemplo.com",
  "evento": "registro",
  "_request": {
    "method": "POST",
    "timestamp": "2026-03-23T10:30:00.000Z",
    "headers": {
      "content-type": "application/json",
      "user-agent": "MiApp/1.0"
    },
    "ip": "192.168.1.100"
  }
}

---

c. Form Trigger (Formulario)

Categoría: init

Similar al Webhook pero especializado para recibir envíos de formularios. Incluye metadata adicional especifica del formulario.

Caracteristicas:

• Recibe datos cuando un formulario es enviado.
• Incluye metadata adicional en el campo _form con información del formulario.
• Soporta flujo OTP (One-Time Password) para verificación de identidad antes de procesar el envío.

Metadata incluida en _form:

Campo	Descripción
form_id	Identificador único del formulario
form_name	Nombre del formulario
form_fields	Definición de los campos del formulario

Ejemplo de datos que recibe el workflow:

{
  "nombre": "Maria",
  "telefono": "+34600000000",
  "mensaje": "Solicitud de informacion",
  "_form": {
    "form_id": "form_abc123",
    "form_name": "Formulario de contacto",
    "form_fields": ["nombre", "telefono", "mensaje"]
  },
  "_request": {
    "method": "POST",
    "timestamp": "2026-03-23T11:00:00.000Z",
    "ip": "10.0.0.50"
  }
}

---

d. DataStore Trigger

Categoría: init

Se activa automáticamente cuando se producen cambios en los registros del DataStore (base de datos interna de la plataforma).

Caracteristicas:

• Se dispara ante eventos de modificación de datos.
• Incluye el registro anterior (previousRecord) en operaciones de actualización, permitiendo comparar el estado antes y después del cambio.
• Permite filtrar por grupo y condiciones especificas para que el trigger solo se active ante ciertos cambios.

Eventos soportados:

Evento	Descripción
insert	Se inserto un nuevo registro
update	Se actualizo un registro existente
bulk_insert	Se insertaron múltiples registros
bulk_update	Se actualizaron múltiples registros

Ejemplo de datos que recibe el workflow (evento update):

{
  "event": "update",
  "record": {
    "id": 42,
    "nombre": "Producto actualizado",
    "precio": 29.99,
    "stock": 150
  },
  "previousRecord": {
    "id": 42,
    "nombre": "Producto original",
    "precio": 24.99,
    "stock": 200
  },
  "datastore": "productos",
  "group": "inventario"
}

---

e. MQTT Trigger

Categoría: init

Escucha mensajes en un broker MQTT (protocolo de mensajeria ligero usado en IoT y sistemas distribuidos).

Caracteristicas:

• Se mantiene conectado al broker MQTT escuchando en el topic configurado.
• Auto-parsea los mensajes JSON recibidos, convirtiendolos automáticamente en objetos.
• Requiere credenciales de conexión al broker.

Configuración de credenciales:

Campo	Descripción
host	Dirección del broker MQTT
port	Puerto de conexión (típicamente 1883 o 8883 para TLS)
username	Nombre de usuario para autenticación
password	Contrasena de autenticación

Ejemplo de datos que recibe el workflow:

{
  "topic": "sensores/temperatura/sala1",
  "message": {
    "temperatura": 23.5,
    "humedad": 45,
    "timestamp": "2026-03-23T12:00:00.000Z"
  },
  "qos": 1,
  "retain": false
}

---

f. Redis Trigger

Categoría: init

Escucha mensajes en canales de Redis mediante el sistema Pub/Sub (publicación y suscripción).

Caracteristicas:

• Soporta dos modos de suscripción:
  • subscribe: Escucha en un canal exacto (por ejemplo, notificaciones).
  • psubscribe: Escucha usando un patron (por ejemplo, notificaciones:* para todos los subcanales).
• Requiere credenciales de conexión a Redis.

Configuración de credenciales:

Campo	Descripción
host	Dirección del servidor Redis
port	Puerto de conexión (típicamente 6379)
password	Contrasena de autenticación

Ejemplo de datos que recibe el workflow:

{
  "channel": "notificaciones:ventas",
  "pattern": "notificaciones:*",
  "message": {
    "tipo": "nueva_venta",
    "monto": 150.00,
    "cliente_id": 789
  }
}

---

g. Telegram Receive

Categoría: init

Recibe mensajes enviados a un bot de Telegram. Permite construir workflows que reaccionan a interacciones de usuarios en Telegram.

Caracteristicas:

• Detecta automáticamente el tipo de mensaje recibido.
• Extrae la información relevante según el tipo de contenido.

Tipos de mensaje detectados:

Tipo	Descripción
text	Mensaje de texto plano
photo	Imagen enviada por el usuario
voice	Mensaje de voz
document	Archivo o documento adjunto
callback_query	Respuesta a un botón inline
command	Comando de bot (ej: /start, /help)

Datos extraidos:

Campo	Descripción
chatId	Identificador del chat
from	Información del usuario que envío el mensaje
content	Contenido del mensaje (texto, file_id, etc.)
metadata	Información adicional (message_id, date, etc.)

Ejemplo de datos que recibe el workflow:

{
  "chatId": 123456789,
  "from": {
    "id": 987654321,
    "first_name": "Carlos",
    "username": "carlos_bot"
  },
  "type": "text",
  "content": "Quiero consultar mi pedido #1234",
  "metadata": {
    "message_id": 555,
    "date": 1742731200
  }
}

---

3. Datos que recibe el workflow

Resumen de los datos iniciales que cada tipo de trigger inyecta en el workflow:

Trigger	Datos principales	Metadata adicional
Start	JSON definido por el usuario en initialData	Ninguna
Webhook	Body (POST) o query params (GET)	_request: method, timestamp, headers, ip
Form Trigger	Campos del formulario enviado	_form: form_id, form_name, form_fields; _request
DataStore	Registro afectado, evento, previousRecord	datastore, group
MQTT	Mensaje del topic (auto-parseado si es JSON)	topic, qos, retain
Redis	Mensaje del canal (parseado)	channel, pattern
Telegram	Contenido del mensaje, tipo detectado	chatId, from, metadata

---

4. Ejemplo: Workflow con Webhook

Descripción del flujo

Webhook -> HTTP (consultar API) -> Decision -> SendMail -> End

Un sistema externo envia datos a la URL del webhook. El workflow consulta una API con esos datos, evalua el resultado y envia un correo si se cumple la condición.

URL del webhook

POST https://mi-plataforma.com/webhooks/a1b2c3d4e5f6

Body de la petición POST

{
  "cliente_id": 1234,
  "tipo_evento": "compra",
  "monto": 250.00
}

Flujo de datos paso a paso

Paso 1 - Webhook: Recibe la petición y pasa los datos al siguiente nodo.

Salida: { cliente_id: 1234, tipo_evento: "compra", monto: 250.00, _request: { ... } }

Paso 2 - HTTP (consultar API): Usa el cliente_id para consultar la API de clientes.

GET https://api.interna.com/clientes/1234
Salida: { nombre: "Ana Garcia", email: "ana@ejemplo.com", nivel: "premium" }

Paso 3 - Decision: Evalua si el nivel del cliente es “premium”.

Condicion: data.nivel == "premium" -> true
Sigue por: truePath -> SendMail

Paso 4 - SendMail: Envia correo de agradecimiento al cliente premium.

To: ana@ejemplo.com
Subject: Gracias por tu compra

Paso 5 - End: Finaliza la ejecución del workflow.

---

5. Ejemplo: Workflow con Schedule + Start

Descripción del flujo

Start (schedule: "0 9 * * 1-5") -> SQL Query -> Iterator -> SendMail -> Merge -> End

Un workflow programado que se ejecuta todos los dias laborables a las 9:00 AM. Consulta una base de datos, itera sobre los resultados y envia un correo por cada registro encontrado.

Expresion cron

0 9 * * 1-5

Significado: A las 09:00, de lunes a viernes.

Flujo de datos paso a paso

Paso 1 - Start: Se activa automáticamente a las 9:00 AM. Inyecta los datos iniciales configurados.

Salida: { reporte: "pendientes", limite: 50 }

Paso 2 - SQL Query: Ejecuta una consulta para obtener tareas pendientes.

SELECT id, responsable, email, tarea, fecha_limite
FROM tareas
WHERE estado = 'pendiente' AND fecha_limite <= CURDATE()
LIMIT 50

Salida: [
  { id: 1, responsable: "Luis", email: "luis@ejemplo.com", tarea: "Revisar informe", fecha_limite: "2026-03-23" },
  { id: 2, responsable: "Marta", email: "marta@ejemplo.com", tarea: "Aprobar presupuesto", fecha_limite: "2026-03-22" }
]

Paso 3 - Iterator: Toma el array de resultados e itera sobre cada elemento, ejecutando los nodos internos (SendMail) una vez por cada registro.

Paso 4 - SendMail (por cada iteración): Envia un correo de recordatorio a cada responsable.

Iteracion 0: To: luis@ejemplo.com, Subject: Recordatorio: Revisar informe
Iteracion 1: To: marta@ejemplo.com, Subject: Recordatorio: Aprobar presupuesto

Paso 5 - Merge: Consolida los resultados de todas las iteraciones en un único array.

Salida: { resultados: [ { enviado: true, email: "luis@ejemplo.com" }, { enviado: true, email: "marta@ejemplo.com" } ] }

Paso 6 - End: Finaliza la ejecución del workflow. Los resultados quedan registrados en la tabla workflowstates para consulta posterior.