Set a Trigger to Start an Agent Cycle

A trigger determines when your agent runs a cycle. You set one trigger per data-defined agent (DDA), and choose from three trigger types, based on what starts the work:

  • Interval: Starts a cycle at a fixed time interval.

  • Cron: Starts a cycle on a schedule.

  • MQTT: Starts a cycle each time an MQTT message arrives on a topic.

You define the trigger in the trigger block of your agent configuration.

Interval Trigger

Starts a cycle at a fixed time interval:

trigger:
  type: interval
  intervalMs: 30000 # Run every 30 seconds
  immediate: true # Also run once immediately at startup
Field Required Default Description

type

Yes

None

The trigger type. In this case, interval.

intervalMs

Yes

None

Time to wait between agent cycles, in milliseconds. For example, 30000 starts a cycle every 30 seconds.

immediate

No

false

When set to true, the trigger starts a cycle immediately when the agent starts. After the initial cycle, the trigger starts cycles at the configured intervalMs value. When set to false, the trigger waits one full interval before it starts the first cycle.

Use the interval trigger to poll sensors, databases, or APIs at a fixed frequency.

Cron Trigger

Starts an agent cycle on a schedule using a cron expression:

trigger:
  type: cron
  cronExpression: '0 */6 * * *' # Every 6 hours
Field Required Description

type

Yes

The trigger type. In this case, cron.

cronExpression

Yes

A standard five-field cron expression: minute, hour, day of month, month, and day of week.

The following table shows common cron expressions and how often each expression starts an agent cycle:

Expression Meaning

* * * * *

Starts the agent cycle every minute.

0 * * * *

Starts the agent cycle every hour.

0 */6 * * *

Starts the agent cycle every 6 hours.

0 8 * * 1-5

Starts the agent cycle weekdays at 08:00.

0 0 * * *

Starts the agent cycle daily at midnight.

0 0 * * 0

Starts the agent cycle weekly on Sunday.

Use the cron trigger to start scheduled reports, daily summaries, shift-change analysis, or any job that runs at a specific time.

Cron expressions define schedules in minutes, so one minute is the shortest possible time between cycles. To start cycles more often, use the Interval Trigger.

MQTT Trigger

Starts a cycle each time an MQTT message arrives on a subscribed topic:

trigger:
  type: mqtt
  connection: factory-mqtt # Name from your connections: block
  topic: factory/events/alarm # MQTT wildcards (+ and #) are supported
Field Required Description

type

Yes

The trigger type. In this case, mqtt.

connection

Yes

The MQTT connection to listen on. Use a connection name from your connections: block.

topic

Yes

The MQTT topic filter to subscribe to. The topic field value can include MQTT wildcards (+ and #). The agent runs a cycle for each message received.

The message that triggered the cycle is available in the Sense stage as part of environmentalData. You do not need a separate MQTT sense substage to access the triggering message.

Use the MQTT trigger to start a cycle for agents that react immediately to specific events, such as alarms, state changes, or device alerts.

Choosing a Trigger

Scenario Trigger Type

Regular polling (sensors, databases).

interval

Scheduled reports or summaries.

cron

Immediate reaction to MQTT events.

mqtt

Next Steps