Skip to content

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

docs(triggers): breaking-change entry for polling triggers on republish (#16936)

Amr Elmohamadyb5cc5f5ee4c3
diff --git a/docs/build-pieces/piece-reference/triggers/overview.mdx b/docs/build-pieces/piece-reference/triggers/overview.mdx
index 2f686a30426..7bfdb7b38ad 100755
--- a/docs/build-pieces/piece-reference/triggers/overview.mdx
+++ b/docs/build-pieces/piece-reference/triggers/overview.mdx
@@ -63,7 +63,7 @@ export const createNewIssue = createTrigger({
- A failing `onDisable` is logged and ignored, so the flow still turns off. A failing `onEnable` fails the publish or the turn-on.
- A patch upgrade in the builder (e.g. 0.5.1 → 0.5.3) keeps the trigger's inputs. A minor or major upgrade resets them to the new version's defaults. Which row applies depends on the inputs that get published: if they match the running flow, `context.isRepublish` is still `true`; if they differ, the trigger starts fresh. Don't rely on an upgrade to clear stored state.
- `context.isRepublish` is `true` only in the rows that say so. Use it to keep stored state that is still valid, rather than starting fresh. See [Polling Trigger → Republishing a running flow](/build-pieces/piece-reference/triggers/polling-trigger#republishing-a-running-flow).
-- Don't count on a polling trigger's `onDisable` to clean up anything outside the store: on an upgrade it doesn't run.
+- A polling trigger's `onDisable` still runs when the flow is turned off or deleted, but not on an upgrade, because the trigger keeps running. If `onEnable` creates something outside the store, save its id in the store and, when `context.isRepublish` is `true` and the id exists, reuse it instead of creating another. If the trigger needs to register and unregister with every version, make it a webhook trigger: those run both hooks on every republish.
- `test` runs when the user loads sample data in the builder, and `run` runs on every poll or incoming event. Neither is part of turning the flow on or off.
## Context Object
diff --git a/docs/build-pieces/piece-reference/triggers/polling-trigger.mdx b/docs/build-pieces/piece-reference/triggers/polling-trigger.mdx
index 67f51edf51f..a6e414047ed 100644
--- a/docs/build-pieces/piece-reference/triggers/polling-trigger.mdx
+++ b/docs/build-pieces/piece-reference/triggers/polling-trigger.mdx
@@ -107,7 +107,7 @@ When an enabled flow is published again and its polling trigger is unchanged (sa
In the other cases ([full table](/build-pieces/piece-reference/triggers/overview#when-the-hooks-run)):
-- **Upgrading the piece version** with the same inputs skips the old version's `onDisable` and runs the new version's `onEnable` with `context.isRepublish` set to `true`. Use it to keep your checkpoint when your stored state is still valid. Don't rely on `onDisable` to clean up anything outside the store, since it doesn't run on an upgrade.
+- **Upgrading the piece version** with the same inputs skips the old version's `onDisable` and runs the new version's `onEnable` with `context.isRepublish` set to `true`. Use it to keep your checkpoint when your stored state is still valid. `onDisable` still runs when the flow is turned off or deleted; on an upgrade, reuse anything `onEnable` created outside the store (keep its id in the store) instead of creating it again.
- **Changing the trigger or its inputs** runs both hooks without `isRepublish`, so the trigger starts fresh.
- **Turning the flow off and on** also starts fresh. This is how to reset a polling trigger whose stored state has gone bad, such as an expired sync token.
diff --git a/docs/install/reference/breaking-changes-unreleased.mdx b/docs/install/reference/breaking-changes-unreleased.mdx
index 37797cabf91..a6177c16a5d 100644
--- a/docs/install/reference/breaking-changes-unreleased.mdx
+++ b/docs/install/reference/breaking-changes-unreleased.mdx
@@ -8,6 +8,17 @@ Entries here move to [Breaking Changes](/install/reference/breaking-changes) aut
## What has changed?
+#### Republishing no longer restarts polling triggers
+
+Republishing a running flow without changing its polling trigger (same piece, version, trigger and inputs) now leaves the trigger running: `onDisable` and `onEnable` don't run and its stored state is kept, so events created around the republish are no longer lost. When a piece is upgraded to a newer version with the same inputs, only the new version's `onEnable` runs, with `context.isRepublish` set to `true`. The old version's `onDisable` doesn't run.
+
+#### What you need to do
+
+Nothing for flows built on official pieces. If you maintain custom polling pieces:
+- To reset a polling trigger whose state has gone bad, turn the flow off and on. Republishing no longer resets it.
+- A polling trigger's `onDisable` still runs when the flow is turned off or deleted, but not on an upgrade, because the trigger keeps running. If `onEnable` creates something outside the store, save its id in the store and, when `context.isRepublish` is `true` and the id exists, reuse it instead of creating another. If the trigger needs to register and unregister with every version, make it a webhook trigger: those run both hooks on every republish.
+- Pass the whole `context` to `pollingHelper` (`pollingHelper.onEnable(polling, context)`), and in `onEnable` keep any state you store yourself when `context.isRepublish` is `true`. Otherwise the trigger starts from scratch on an upgrade. See [When the hooks run](/build-pieces/piece-reference/triggers/overview#when-the-hooks-run).
+
#### Apache Kafka 0.1.0: Publish messages is no longer an AI agent tool
**Publish messages** (several messages in one request) is no longer offered to AI agents as a tool; flow steps that use it keep working unchanged. Agents publish with **Publish message**, one message per call, so there is one agent tool for publishing.