Triggers
Triggers enable automated execution of workflows based on time schedules or incoming events. They define when a workflow should run and what data is passed during execution.
Each trigger has three main components:
| Component | Role |
|---|---|
| Trigger Metadata | Defines the trigger identity and input message |
| Trigger Activation | Defines when the trigger runs |
| Trigger Action | Defines what runs when the trigger activates |
1. Trigger Metadata
Trigger Metadata defines the identity and input payload for the trigger.
| Field | Description |
|---|---|
| Trigger Name | Unique name for the trigger |
| Trigger Description | What the trigger does |
| Trigger Message Type | Format of the input message: Text or JSON |
| Message (Text) | Plain text input passed to the action |
| JSON Dict (JSON) | Structured JSON payload passed to the action |
The trigger message is forwarded to the configured action and is used as input during execution.
2. Trigger Activation
Trigger Activation defines when the trigger runs. Two activation modes are available: scheduled and event-based.
2.1 Scheduled trigger
Scheduled triggers run workflows at defined time intervals.
| Field | Description |
|---|---|
| Schedule Cron Expression | Defines the execution schedule |
| Schedule AI Description | Natural language used to generate or refine cron expressions (for example: “every 1 hour”) |
The cron expression can be entered manually or produced with AI assistance from the description.
Note
Schedule AI (cron generation) — AI-assisted scheduling generates or refines the cron expression from natural language using an LLM. The default model is gpt-4o.
To use another model, change the configurable llm parameter in the trigger definition JSON on the dashboard. Update the value to the LLM you want. This parameter is available for both Add Trigger and Edit Trigger.
2.2 Event-based trigger
Event-based triggers run workflows automatically when events are received from streaming systems. That supports real-time processing of operational data such as alerts, logs, or incident events.
Event type — An event-based trigger uses one of these sources:
- NATS
- Kafka
NATS configuration
When NATS is selected, the following fields are required:
| Field | Description |
|---|---|
| Stream Name | Stream from which events are consumed |
| CFXQL Filter | Filter expression so only relevant events are processed |
| Group Name | Consumer group used to process the stream |
Kafka configuration
When Kafka is selected, the following fields are required:
| Field | Description |
|---|---|
| Kafka Topic | Topic from which events are consumed |
| CFXQL Filter | Filter expression so only relevant events are processed |
| Consumer Group Name | Consumer group used for message consumption |
Event processing
For event-based triggers, incoming data is processed in this order:
- Events are read from the configured stream or topic.
- The configured CFXQL filter is applied to select relevant events.
- Matching events activate the trigger.
- The configured action runs.
Data passed to action
When a trigger activates, the action receives:
- Trigger name
- Trigger type
- Trigger message (text or JSON)
- Event payload from the stream or topic
Example pipeline (NATS)
Below is an example pipeline for reference; your deployment may use a different shape.
#rn:read-stream name = "{{STREAM_NAME}}"
--> *dm:filter {{CFXQL_FILTER|'*'}}
--> @workflow:execute_workflow name = '{{WORKFLOW_NAME}}' & triggername = '{{TRIGGER_NAME}}' & triggerMessage = '{{TRIGGER_MESSAGE}}'
Align placeholder names with your environment’s workflow and execute_workflow contract.
Event-based triggers enable real-time automation: workflows run in response to data from NATS or Kafka, with filtering so only the events you care about start execution.
3. Trigger Action
Trigger Action defines what happens when a trigger is activated. It determines how the system responds once the trigger conditions are met.
Action types
A trigger supports these action types:
| Action type | Purpose |
|---|---|
| Execute Workflow | Run an agent workflow |
| Execute Persona | Invoke an AI persona |
| Post Event | Publish an event for other triggers, agents, or workflows |
3.1 Execute Workflow
Runs an existing agent workflow when the trigger activates.
Configuration
| Field | Description |
|---|---|
| Workflow Name | Workflow selected from the workflows available in the project |
Behavior
- The selected workflow runs automatically.
- The workflow receives the trigger message (text or JSON).
- For event-based triggers, any applicable event payload is passed to the workflow.
3.2 Execute Persona
Runs an AI persona when the trigger activates.
Configuration
| Field | Description |
|---|---|
| Persona Name | Persona selected from the personas available in the project |
Behavior
- The selected persona is invoked automatically.
- The persona uses the trigger message as input.
- Any applicable event data is passed to the persona.
3.3 Post Event
Publishes an event that other triggers, agents, or workflows can consume. Use this to chain workflows and build event-driven automation.
Event targets — Events can be published to:
- A NATS stream
- A Kafka topic
NATS configuration
| Field | Description |
|---|---|
| Stream Name | Stream where the event is published |
Kafka configuration
| Field | Description |
|---|---|
| Kafka Topic | Topic where the event is published |
Event payload
The posted event includes:
- Trigger name
- Trigger type
- Trigger message (text or JSON)
- Event payload received from another source, when applicable
3.4 Summary
Trigger actions define how automation runs after activation:
- Execute Workflow — Runs a predefined workflow.
- Execute Persona — Invokes an AI persona.
- Post Event — Emits an event for downstream processing.
4. Edit Trigger
You can update an existing trigger to change its configuration and behavior.
Editable fields
These fields can be changed:
- Trigger Name
- Trigger Description
- Trigger Message (text or JSON)
- Schedule configuration (for scheduled triggers)
- Stream or filter configuration (for event-based triggers)
- Selected workflow or persona (depending on the action type)
Restrictions
These properties cannot be changed after the trigger is created:
- Trigger type (Scheduled or Event-Based)
- Action type (Execute Workflow, Execute Persona, or Post Event)
To use a different trigger type or action type, create a new trigger.
You can refine execution logic and inputs by editing a trigger. Core properties such as trigger type and action type remain fixed after creation.
5. Trigger types summary
| Type | Description |
|---|---|
| Scheduled | Runs at predefined intervals using a cron schedule |
| Event-based (NATS) | Runs on events from a NATS stream |
| Event-based (Kafka) | Runs on events from a Kafka topic |
6. Triggers page and job history
In Agentic Workflows → Triggers, the same page lists your triggers and, underneath, Trigger Jobs (execution history). Use Add Trigger and search or filter to create triggers and find rows in either list.
Configured triggers
The trigger list shows how each automation is set up at a glance: name, description, message, Scheduled or Event-based type, cron or event source, Action Type, Status, the Agent or workflow target, and End Time when an expiration exists. Scheduled rows show a cron expression; event-based rows reflect stream or topic configuration.
Trigger Jobs
Trigger Jobs is the run log. Each row is one execution—when it ran, which trigger, input, agent or workflow, Job ID, Completed or Failed status, and Failure Reason when applicable.
Job drill-down
Select a Job ID to open the full execution view: summary (duration, tokens, cost), execution path, step-by-step actions, inputs and outputs, tool calls, and final output.
Note
For observability dashboards, cost and token analysis, and related capabilities, see Observability.
7. Summary
Triggers automate workflow execution from time-based schedules or real-time events. They support continuous monitoring, reporting, and operational automation without requiring manual runs for each execution.