AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
icon: ⚡
Triggers
Triggers define how and when a flow starts. The module handles registration, event capture, testing, and deduplication, tracking each enabled trigger as a TriggerSource record and driving enable/disable side effects (BullMQ scheduling, external webhook registration).
Entities & services
- TriggerStrategy —
POLLING,WEBHOOK,APP_WEBHOOK,MANUAL. - TriggerSource — persisted link between a flow version and its registered trigger; soft-deleted on disable; unique per
(projectId, flowId, simulate). - TriggerEvent — a captured payload stored as a File ref; used for test-data selection in the builder.
sourceNameformat:pieceName@version:triggerName. - AppEventRouting — routing table for APP_WEBHOOK: maps
(appName, event, identifierValue)to a flow. - Services:
flow-trigger-side-effect.ts,trigger-source-service.ts,dedupe-service.ts,test-trigger-service.ts.
How it works
- Strategies: POLLING = cron via BullMQ repeating job + Redis dedupe. WEBHOOK = external service pushes to an AP webhook URL. APP_WEBHOOK = app-native events routed via AppEventRouting (Slack, GitHub). MANUAL = user-triggered only.
- On enable: POLLING creates the repeating job — the piece's
setSchedulesupplies either a cron (CRON_EXPRESSION) or a rolling interval (INTERVAL→ BullMQevery); when the piece sets nothing the default is a rolling interval ofAP_TRIGGER_DEFAULT_POLL_INTERVALminutes (default 5). WEBHOOK submits ON_ENABLE hook (+ renewal job if the piece needs periodic re-registration); APP_WEBHOOK creates routing records. - On disable: removes repeating jobs, submits ON_DISABLE hook (unregister), deletes routing records.
- Testing (
testTriggerService, distributed-locked):SIMULATIONcreates asimulate=truesource and collects events;TEST_FUNCTIONsubmits a TEST hook and saves outputs as TriggerEvents.
Gotchas
- Deduplication (polling): extracts
__DEDUPE_KEY_PROPERTY, Redis INCR with 30s TTL — first passes, duplicates filtered; the dedupe key is stripped from returned payloads. - Republishing leaves an unchanged polling trigger running (
isTriggerUnchanged): a publish runsonDisable(old) → onEnable(new), which resetlastPoll/lastItem(and every custom checkpoint) to now and silently dropped events created in between. When the flow was alreadyENABLED, stays enabled, and the trigger keeps the same piece, piece version, trigger name and deep-equalsettings.input(flowPublishUtils.isTriggerUnchanged),flowTriggerSideEffectskips both engine hooks for a POLLING trigger: the store is untouched and only the poll job is re-pointed to the new flow version with the previous trigger source's schedule (no previous schedule → hooks run). The hooks are skipped, not run against a guarded store, because any store-wrapping rule changes what piece code sees mid-hook and broke real pieces (pinterest's mid-pagination bookmark, azure-ad's stale delta link failing the publish); skipping makes the trigger indistinguishable from a flow nobody republished, which is safe for custom pieces too. With the same inputs but a new piece version only the new version'sonEnableruns, withisRepublish=true(flowPublishUtils.isRepublish→context.isRepublish); the old version'sonDisableis skipped for POLLING, because pre-guard versions delete their checkpoint unconditionally and the old code can't be fixed after it ships.pollingHelper.onEnablekeeps the checkpoint only if the piece passes the wholecontext, and custom state needs its ownisRepublishguard inonEnable. The cost: a pollingonDisablethat cleans up something external (none in the repo) won't run on an upgrade, so that object leaks while the newonEnablecreates a fresh one. A trigger swap, any props change, or an off→on toggle runs the hooks normally and starts fresh; off→on is the way to reset a polling trigger whose state has gone bad (e.g. an expired sync token), since a republish no longer does. The props check is not cosmetic: a checkpoint kept across a props change points at a resource that is no longer being polled, andpollingHelper.polltreats aLAST_ITEMid it cannot find (findIndex → -1) as "no checkpoint", emitting every item. Both publish paths —flowService.updatedPublishedVersionIdandflowApprovalRequestService.approve(its own disable→enable) — use these two decisions; any new publish path must too. - A missing timestamp permanently kills a TIMEBASED polling trigger —
pollingHelper.polladvances the checkpoint withitems.reduce((acc, i) => Math.max(acc, i.epochMilliSeconds), lastPoll), andMath.max(n, NaN)isNaN, so a single item whose date field was never requested (dayjs(undefined).valueOf()→NaN) writesNaNintolastPoll; every later poll then filters on> NaN→ false and the trigger silently never fires again, with no error anywhere. Two guards, both needed: request the date in the API'sfields/select mask, and drop items with an unusable date before mapping toepochMilliSeconds. The filter must check the raw value, not just.isValid()—dayjs(undefined)is now and reports valid. - The timestamp you poll on may be client-supplied, and a future one is fatal. Google Drive sets
modifiedTimefrom the local file mtime on upload, not the upload moment, so it can be older thancreatedTime— or years ahead if the uploader's clock is fast. A TIMEBASED watermark ismax(epochMilliSeconds)over the emitted items, so one future-dated row pusheslastPollinto the future and the trigger emits nothing until wall-clock catches up. Hold back items timestamped afterDate.now()— they fire once the clock passes them. Do not clamp the watermark instead: a clamped watermark re-emits that same row on every poll forever. - The simulate flag lets a production source and a test source coexist independently.
- Renewal jobs re-register expiring webhook pieces via the ON_RENEW hook.
*/Xcron is not "every X minutes" — it means "minutes divisible by X", so it double-fires at :00 and :X for X > 30 and gaps unevenly when X doesn't divide 60. UseINTERVAL/intervalMsfor a rolling interval; reserve cron for wall-clock schedules. This bit the default poll schedule until GIT-1632.- A
basic-ftplogin that fails leaves the control socket open.access()connects first and then logs in, so a refused login rejects with the socket still established, and the caller's client variable was never assigned, so nofinallycloses it. Measured against vsftpd on one refused login: the Node process stayed alive 304s waiting on that handle, versus 3s oncegetClientcallsclose()before rethrowing. Any helper that builds an FTP client must close it on a failedaccess(). basic-ftponly fills inmodifiedAtfromMLSD.parseListUnixandparseListDOSset only the unparsedrawModifiedAt, and the library deliberately refuses to parse it because LIST dates carry no reliable timezone or year. A LIST-only server therefore hands youmodifiedAt: undefined, anddayjs(undefined)is now, so every file looks freshly modified on every poll and a TIMEBASED trigger re-fires the whole folder forever (ENG-1032; against vsftpd, 6 polls emitted the same file and its subdirectory 12 times).MDTMviaclient.lastModis the reliable fallback: precise UTC for files, but550on a directory, andbasic-ftprejects concurrent commands on one control connection, so ask only for regular files and ask sequentially. Treat only550as "skip this entry" — swallowing everylastModerror loses files, because one entry's transient blip is skipped while a sibling's newer timestamp still advanceslastPollpast it. CheckFEATonce per poll rather than per file, and when the server offers neitherMLSDnorMDTMkeep the old "treat as now" behaviour instead of failing: there is no timestamp to be had, and changing what those flows do is a worse trade than leaving them as they are.- Trigger health (
triggerRunStats): Redis keytrigger_run:{platformId}:{pieceName}:{date}:{status}, 14-day retention, shown in Platform Admin (Cloud). - A polling
itemsthat catches its own connect or auth error and returns[]hides the outage. The worker counts the poll COMPLETED, logs no warning and the flow stays enabled, so a rotated password looks like an empty folder. Let it throw:pollingHelper.pollfails before it writeslastPoll, the poll counts FAILED with a worker warn, and the next good poll catches up on everything missed. SFTP New File was fixed this way (ENG-796); dozens of community triggers still swallow errors the same way.
Editions
All four strategies available in CE/EE/Cloud. Cloud additionally surfaces trigger health stats in Platform Admin.
Key files
Entry point: flowTriggerSideEffect, exported from trigger-source/flow-trigger-side-effect.ts and called by trigger-source-service.ts on enable and disable.
packages/server/api/src/app/trigger/trigger-source/— TriggerSource CRUD, entity, and the enable/disable side effects per strategypackages/server/api/src/app/trigger/trigger-events/— TriggerEvent storage, entity, and endpointspackages/server/api/src/app/trigger/test-trigger/— simulation and test-function modes, plus their endpointspackages/server/api/src/app/trigger/app-event-routing/— APP_WEBHOOK routing table and entitypackages/server/api/src/app/trigger/trigger-run/— per-platform trigger health tracking and stats endpointspackages/server/api/src/app/trigger/dedupe-service.ts— Redis-based deduplication for pollingpackages/server/api/src/app/trigger/trigger.module.ts— module registrationpackages/core/shared/src/lib/automation/trigger/— TriggerSource schema, TriggerStrategy enum, handshake and schedule optionspackages/web/src/app/builder/test-step/— builder test panel, event selector, and the manual webhook test dialogpackages/web/src/app/builder/flow-canvas/— trigger node widget and the add-trigger button above it
Paths verified 2026-07-17.