Triggers - Starting Workflows

1. What is a Trigger

A trigger is the entry point that initiates the execution of a workflow. Every workflow must begin with a trigger-type node, which defines how and when the flow is activated, and what initial data is injected into the execution.

The trigger determines:

• How the workflow is started (manual, scheduled, by external event, by message, etc.)
• The initial data that the first node of the flow receives
• The metadata associated with the execution (origin, timestamp, parameters)

---

2. Available Trigger Types

a. Start (Manual Start)

Category: init

Starts the workflow manually or through a schedule. It is the most basic and versatile trigger.

Characteristics:

• Allows defining initial data in JSON format that is injected as input for the first node.
• It is the default trigger for workflows scheduled using cron expressions (schedule).
• When executed by schedule, the initial data defined in the configuration is used as input.
• When executed manually, the initial data can be overridden.

Configuration:

Field	Description
initialData	JSON object with the workflow’s initial data
schedule	Cron expression for scheduled execution (optional)
active_schedule	Enable or disable scheduling (true/false)

Initial data example:

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

---

b. Webhook

Category: init

Starts the workflow when it receives an external HTTP request. Ideal for integrations with third-party systems that send notifications or data via HTTP.

Characteristics:

• A unique URL is automatically generated for each webhook with the format: /webhooks/{hash}
• Supports GET requests (query params become the payload) and POST requests (the request body is used as the payload).
• Includes request metadata in the _request field.
• Has a development URL for testing: /webhooks-dev/{hash}

Metadata included in _request:

Field	Description
method	HTTP method used (GET, POST)
timestamp	Date and time the request was received
headers	HTTP headers of the request
ip	IP address of the client that made the request

Example of data received by the 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

Category: init

Similar to the Webhook but specialized for receiving form submissions. Includes additional form-specific metadata.

Characteristics:

• Receives data when a form is submitted.
• Includes additional metadata in the _form field with form information.
• Supports OTP (One-Time Password) flow for identity verification before processing the submission.

Metadata included in _form:

Field	Description
form_id	Unique form identifier
form_name	Form name
form_fields	Definition of form fields

Example of data received by the 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

Category: init

Activates automatically when changes occur in DataStore records (the platform’s internal database).

Characteristics:

• Fires on data modification events.
• Includes the previous record (previousRecord) in update operations, allowing comparison of the state before and after the change.
• Allows filtering by group and specific conditions so the trigger only fires for certain changes.

Supported Events:

Event	Description
insert	A new record was inserted
update	An existing record was updated
bulk_insert	Multiple records were inserted
bulk_update	Multiple records were updated

Example of data received by the workflow (update event):

{
  "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

Category: init

Listens for messages on an MQTT broker (lightweight messaging protocol used in IoT and distributed systems).

Characteristics:

• Stays connected to the MQTT broker listening on the configured topic.
• Auto-parses received JSON messages, automatically converting them into objects.
• Requires broker connection credentials.

Credential Configuration:

Field	Description
host	MQTT broker address
port	Connection port (typically 1883 or 8883 for TLS)
username	Username for authentication
password	Authentication password

Example of data received by the 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

Category: init

Listens for messages on Redis channels through the Pub/Sub (publish and subscribe) system.

Characteristics:

• Supports two subscription modes:
  • subscribe: Listens on an exact channel (for example, notifications).
  • psubscribe: Listens using a pattern (for example, notifications:* for all subchannels).
• Requires Redis connection credentials.

Credential Configuration:

Field	Description
host	Redis server address
port	Connection port (typically 6379)
password	Authentication password

Example of data received by the workflow:

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

---

g. Telegram Receive

Category: init

Receives messages sent to a Telegram bot. Allows building workflows that react to user interactions on Telegram.

Characteristics:

• Automatically detects the type of received message.
• Extracts relevant information based on the content type.

Detected Message Types:

Type	Description
text	Plain text message
photo	Image sent by the user
voice	Voice message
document	Attached file or document
callback_query	Response to an inline button
command	Bot command (e.g.: /start, /help)

Extracted Data:

Field	Description
chatId	Chat identifier
from	Information about the user who sent the message
content	Message content (text, file_id, etc.)
metadata	Additional information (message_id, date, etc.)

Example of data received by the 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. Data Received by the Workflow

Summary of the initial data each trigger type injects into the workflow:

Trigger	Main Data	Additional Metadata
Start	JSON defined by the user in initialData	None
Webhook	Body (POST) or query params (GET)	_request: method, timestamp, headers, ip
Form Trigger	Submitted form fields	_form: form_id, form_name, form_fields; _request
DataStore	Affected record, event, previousRecord	datastore, group
MQTT	Topic message (auto-parsed if JSON)	topic, qos, retain
Redis	Channel message (parsed)	channel, pattern
Telegram	Message content, detected type	chatId, from, metadata

---

4. Example: Workflow with Webhook

Flow Description

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

An external system sends data to the webhook URL. The workflow queries an API with that data, evaluates the result, and sends an email if the condition is met.

Webhook URL

POST https://my-platform.com/webhooks/a1b2c3d4e5f6

POST Request Body

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

Step-by-Step Data Flow

Step 1 - Webhook: Receives the request and passes the data to the next node.

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

Step 2 - HTTP (query API): Uses the cliente_id to query the customer API.

GET https://api.internal.com/clients/1234
Output: { nombre: "Ana Garcia", email: "ana@ejemplo.com", nivel: "premium" }

Step 3 - Decision: Evaluates whether the customer level is “premium”.

Condition: data.nivel == "premium" -> true
Follows: truePath -> SendMail

Step 4 - SendMail: Sends a thank-you email to the premium customer.

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

Step 5 - End: Finishes the workflow execution.

---

5. Example: Workflow with Schedule + Start

Flow Description

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

A scheduled workflow that runs every weekday at 9:00 AM. It queries a database, iterates over the results, and sends an email for each record found.

Cron Expression

0 9 * * 1-5

Meaning: At 09:00, Monday through Friday.

Step-by-Step Data Flow

Step 1 - Start: Activates automatically at 9:00 AM. Injects the configured initial data.

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

Step 2 - SQL Query: Executes a query to get pending tasks.

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

Output: [
  { 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" }
]

Step 3 - Iterator: Takes the results array and iterates over each element, executing the internal nodes (SendMail) once per record.

Step 4 - SendMail (for each iteration): Sends a reminder email to each responsible person.

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

Step 5 - Merge: Consolidates the results from all iterations into a single array.

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

Step 6 - End: Finishes the workflow execution. The results are recorded in the workflowstates table for later review.