Polling / DB Watcher Trigger
The bridge for legacy systems. Actively monitors external databases, storage buckets, or spreadsheets for state changes and releases normalized data into the canvas.
Spec v1.1
Pull-Driven
Port Overview
No input ports
Entry point node — driven by the engine's internal PollingService.
Polling Trigger
Trigger
Output ports
onResult
Node Properties
Configuration settings for the active watcher. The engine dispatches a background worker at the specified interval to execute the query and process results.
PollingTrigger
Resource Configuration
| Property | Type | Default | Description |
|---|---|---|---|
| sourceType | enum | SqlDatabase | SqlDatabase | S3Bucket | GoogleSheet | RestApi |
| connectionRef | string | required | Vault reference to credentials (e.g., connection string, AWS keys). |
| query | string | null | The SQL query, file path, or API endpoint to poll. |
| pollingInterval | int | 5 | Wait time between poll attempts. |
| pollingUnit | enum | Minutes | Seconds | Minutes | Hours |
Instance Strategy
| Property | Type | Default | Description |
|---|---|---|---|
| correlationExpression | expression | null | A JSONPath or regex to extract a unique Instance Context ID from the result row. |
| onMatch | enum | MapOrCreate |
MapOrCreate — (Genesis) Creates a new instance if the resolved ID is unknown. Updates if known.MapOrDiscard — (Signal) Only updates existing instances. If no match is found, the signal is dropped.AlwaysCreate — Ignores the resolved ID and spawns a parallel instance (useful for stateless logs).MapOrReplace — Aborts the existing instance and starts a fresh one with the new payload.
|
| deduplicationKey | expression | null | Field used to ensure the same record isn't processed twice (e.g., $.id or $.last_modified). |
Stateful Polling
To prevent re-triggering on the same data, the engine tracks the
deduplicationKey in a high-speed cursor store. If a polled row matches a known key, it is skipped unless the data has changed.
Port Detail
Each row or item found during a poll generates a unique trigger event.
Output ports
onResult
signal
Fires once for every record/row detected in the polling cycle.
// Row data written to WorkflowContext[nodeId]:
{
"id": 1024,
"status": "NEW",
"created_at": "2026-03-26T10:00:00Z",
"payload": { ... }
}
{
"id": 1024,
"status": "NEW",
"created_at": "2026-03-26T10:00:00Z",
"payload": { ... }
}