Triggers - Iniciar Workflows

1. Que es un Trigger

Un trigger es el punto de entrada que inicia la ejecucion 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 ejecucion.

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 ejecucion (origen, timestamp, parametros)

---

2. Tipos de Triggers disponibles

a. Start (Inicio manual)

Categoria: init

Inicia el workflow de forma manual o mediante una programacion (schedule). Es el trigger mas basico 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 configuracion se usan como entrada.
• Cuando se ejecuta manualmente, se pueden sobrescribir los datos iniciales.

Configuracion:

Campo	Descripcion
initialData	Objeto JSON con los datos iniciales del workflow
schedule	Expresion cron para ejecucion programada (opcional)
active_schedule	Activar o desactivar la programacion (true/false)

Ejemplo de datos iniciales:

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

---

b. Webhook

Categoria: init

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

Caracteristicas:

• Se genera automaticamente una URL unica 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 peticion se usa como payload).
• Incluye metadata de la peticion en el campo _request.
• Dispone de una URL de desarrollo para pruebas: /webhooks-dev/{hash}

Metadata incluida en _request:

Campo	Descripcion
method	Metodo HTTP utilizado (GET, POST)
timestamp	Fecha y hora de recepcion de la peticion
headers	Cabeceras HTTP de la peticion
ip	Direccion IP del cliente que realizo la peticion

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)

Categoria: init

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

Caracteristicas:

• Recibe datos cuando un formulario es enviado.
• Incluye metadata adicional en el campo _form con informacion del formulario.
• Soporta flujo OTP (One-Time Password) para verificacion de identidad antes de procesar el envio.

Metadata incluida en _form:

Campo	Descripcion
form_id	Identificador unico del formulario
form_name	Nombre del formulario
form_fields	Definicion 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

Categoria: init

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

Caracteristicas:

• Se dispara ante eventos de modificacion de datos.
• Incluye el registro anterior (previousRecord) en operaciones de actualizacion, permitiendo comparar el estado antes y despues del cambio.
• Permite filtrar por grupo y condiciones especificas para que el trigger solo se active ante ciertos cambios.

Eventos soportados:

Evento	Descripcion
insert	Se inserto un nuevo registro
update	Se actualizo un registro existente
bulk_insert	Se insertaron multiples registros
bulk_update	Se actualizaron multiples 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

Categoria: 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 automaticamente en objetos.
• Requiere credenciales de conexion al broker.

Configuracion de credenciales:

Campo	Descripcion
host	Direccion del broker MQTT
port	Puerto de conexion (tipicamente 1883 o 8883 para TLS)
username	Nombre de usuario para autenticacion
password	Contrasena de autenticacion

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

Categoria: init

Escucha mensajes en canales de Redis mediante el sistema Pub/Sub (publicacion y suscripcion).

Caracteristicas:

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

Configuracion de credenciales:

Campo	Descripcion
host	Direccion del servidor Redis
port	Puerto de conexion (tipicamente 6379)
password	Contrasena de autenticacion

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

Categoria: init

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

Caracteristicas:

• Detecta automaticamente el tipo de mensaje recibido.
• Extrae la informacion relevante segun el tipo de contenido.

Tipos de mensaje detectados:

Tipo	Descripcion
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 boton inline
command	Comando de bot (ej: /start, /help)

Datos extraidos:

Campo	Descripcion
chatId	Identificador del chat
from	Informacion del usuario que envio el mensaje
content	Contenido del mensaje (texto, file_id, etc.)
metadata	Informacion 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

Descripcion 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 condicion.

URL del webhook

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

Body de la peticion POST

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

Flujo de datos paso a paso

Paso 1 - Webhook: Recibe la peticion 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 ejecucion del workflow.

---

5. Ejemplo: Workflow con Schedule + Start

Descripcion 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 automaticamente 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 iteracion): 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 unico array.

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

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