> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling and triggers

> Operating workflow triggers — cron and one-shot schedules, the 60-second evaluator, missed fires and backfillPolicy, pause and resume, and timezone semantics.

Last updated 2026-11-11

·
applies to 2026-05-02

·
main

This page is for operators wiring workflows to time-based triggers. A workflow can have one or more triggers. A time-based trigger is either a **cron** trigger, which fires on a cron expression in a timezone, or a **one-shot** trigger, which fires once at `oneShotFireAt`. A trigger takes one or the other, never both. There is no interval trigger: express "every N minutes or hours" as a cron expression.

For the workflow execution model itself, see [Workflow Execution flow](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md). Webhook and email triggers fire on an event instead of a time; see [Ingress](https://docs.gloo.com/forge/run/ingress.md) and [Email](https://docs.gloo.com/forge/run/email.md).

***

## How the evaluator works

The *workflow trigger evaluator* platform cron runs every 60 seconds. Each tick it reads up to 200 enabled triggers whose next fire time has passed, oldest first. Triggers beyond that page wait for the next tick.

For each due trigger, the evaluator claims the fire and schedules the launch. The launch goes through the same start path as a manual run, attributed to the trigger. A trigger without a pinned `versionId` runs the version that is active when the fire is claimed; one with a `versionId` always runs that version. Each fire passes the trigger's dispatch arguments, which are validated against the workflow's input schema when the trigger is saved.

The evaluator does not check whether an earlier run of the same trigger is still going. A trigger whose cadence is shorter than its runs starts overlapping runs.

Before each fire the evaluator checks that the trigger's creator still holds `workflows:manage` at the workflow's home and at the trigger's org unit: a person through their roles, an External App or platform API key through its own grants. If the creator does not, or the workflow was deleted, the trigger is paused and the reason is recorded. If a trigger is deleted after a fire is claimed, or a cron trigger is paused after its claim, the launch is skipped and recorded as `workflow_trigger_fire_skipped`. A one-shot is consumed at its claim, so pausing it afterwards does not stop the launch.

***

## Trigger types

### Cron triggers

Cron expressions give control over run timing: day of week, time of day, monthly cadence. The expression is parsed by [`croner`](https://github.com/hexagon/croner); an expression it cannot parse is rejected when the trigger is saved. Forge sets no minimum cadence, but the evaluator runs once a minute, so a fire can start up to a minute after its scheduled time.

Common patterns:

| Expression | Meaning |
| - | - |
| `0 9 * * 1-5` | Weekdays at 9 AM |
| `0 0 * * *` | Daily at midnight |
| `*/15 * * * *` | Every 15 minutes |
| `0 */4 * * *` | Every 4 hours |
| `30 8 1 * *` | 1st of every month at 8:30 AM |

After each fire, the next fire time is computed from the expression and the current time.

### One-shot triggers

`oneShotFireAt` is an epoch-millisecond time that must be in the future when the trigger is created. The trigger fires once, even if the evaluator reaches it late, and is then disabled; the row stays for its history. A one-shot whose time has passed cannot be resumed.

### Timezone support

A cron trigger takes an IANA timezone (`America/New_York`, `Europe/London`, `Asia/Tokyo`); the default is `UTC`, and an unknown zone is rejected when the trigger is saved. The expression is evaluated in that zone, so `0 9 * * 1-5` with `America/New_York` fires at 9 AM Eastern on weekdays across daylight saving changes.

DST hazard

Be careful with cron expressions during DST transitions. An expression like `0 2 * * *` (2 AM daily) may skip or double-fire on transition days depending on the timezone. **Prefer times outside the 1–3 AM window** for timezone-sensitive schedules.

***

## Missed fires and `backfillPolicy`

A cron fire is missed when its window passes without the evaluator claiming it, for example during a platform outage. When the evaluator next reaches the trigger, it looks at up to 11 due windows, oldest first, and applies the trigger's `backfillPolicy`:

| Policy | What fires |
| - | - |
| `coalesce` (default) | One run, for the last of the windows scanned. The earlier scanned windows are counted as misses. |
| `fire_each_missed` | One run for each scanned window, oldest first, up to 10, all launched in the same tick. A scanned window past 10 is dropped and counted as a miss. |
| `drop` | A run only when exactly one window is due. After a gap, nothing fires and the missed windows are counted. |

The scan starts at the trigger's next fire time and stops after 11 windows, so after a longer gap it covers only the oldest 11. `coalesce` then fires the 11th-oldest window, not the latest, and the windows beyond the scan are neither fired nor counted as misses. There is no lookback limit by time: the cap is the number of windows. Email triggers store `drop`, but they fire on mail, not on the clock. After any policy, the next fire time is computed from the current time, so the trigger does not keep catching up on later ticks. The trigger's `consecutiveMisses` counts the windows that did not run.

***

## Trigger lifecycle: enabled, paused, deleted

| State | What it means | How to get there |
| - | - | - |
| Enabled | The trigger has a next fire time, and the evaluator fires it when that time passes. | The default when a trigger is created |
| Paused | The trigger is disabled and the evaluator never claims it. A cron fire already claimed is skipped at launch; a claimed one-shot still launches. | An operator pause, or the creator losing `workflows:manage` |
| Deleted | The trigger row is removed. A fire already claimed is skipped at launch. | An operator deletes the trigger |

Resuming a cron trigger computes its next fire time from the current time and resets `consecutiveMisses` to 0. It does not backfill the windows that passed while it was paused, whatever its `backfillPolicy`. A one-shot resumes only while its `oneShotFireAt` is still in the future.

***

## Operate from Platform → Schedules

Builders create and edit a workflow's triggers on the workflow's **Schedule** tab. **Platform → Schedules** (`/platform/schedules`) is the admin-only view, with **Recurring**, **Upcoming** and **Triggers** tabs. The **Triggers** tab lists the enabled and paused triggers homed at your current org unit; triggers in other units, including the units below it, do not appear:

| Column | Description |
| - | - |
| **Workflow** | The workflow the trigger fires |
| **Schedule** | The cron expression and timezone, or the one-shot time |
| **Next fire** | The computed next fire time |
| **Status** | Whether the trigger is enabled or paused |
| **Owner** | **You** for your own triggers, otherwise **Unknown** |

From the row you can pause or resume a trigger, delete it, or run it now. Use this view, once per org unit, to audit which workflows run on schedules and to confirm next fire times after a timezone or DST change.

***

## Operator runbook

When you set up scheduling for a workflow:

1. **Write the cadence as a cron expression.** Use a one-shot trigger for a single future run.
2. **Set the timezone explicitly when the schedule is calendar-aligned.** For a cron that should fire at "9 AM" in some location, set the IANA zone; do not hand-compute UTC offsets.
3. **Avoid the DST hazard window.** Anything between 1 and 3 AM in a timezone that observes DST can skip or double-fire. Pick `0 4 * * *` instead of `0 2 * * *`.
4. **Pick a `backfillPolicy`.** Keep `coalesce` when one catch-up run is enough, use `fire_each_missed` when each window's run matters (up to 10 per pass), and use `drop` when a late run is worse than none. After a gap longer than 11 windows, no policy covers the whole backlog: start a manual run if a later window's run matters.
5. **Check overlap.** If a run can last longer than the cadence, widen the cadence: the trigger starts a new run even while the last one is going.
6. **Verify the next fire time after creation** on the workflow's Schedule tab or in **Platform → Schedules → Triggers**.

***

## Reference

| Detail | Value |
| - | - |
| Trigger kinds | Cron, one-shot (time-based); webhook and email (event-based) |
| Cron parser | `croner` |
| Default timezone | `UTC` |
| Evaluator cadence | Every 60 seconds |
| Due triggers per tick | 200; the rest wait for the next tick |
| `backfillPolicy` | `coalesce` (default), `fire_each_missed` (up to 10 windows), `drop` |

***

## Do it over the API

These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). The quickstart's `ACCESS_TOKEN` does not carry every scope they need, so mint it again with `scope=workflows:manage workflows:read agents:use credentials:use` from an app whose roles hold them (see [Requesting scopes at token mint](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) whose scopes include them; `workflows:manage` is elevated, so tick **Include elevated permissions** when you choose the key's scopes (see [Approve and administer scopes](https://docs.gloo.com/forge/console/settings/personal-keys.md#approve-and-administer-scopes)).

Schedule a workflow to fire at 9 AM Eastern on weekdays. A trigger takes either `cronExpression` (with `timezone`) or `oneShotFireAt`, never both. Without `versionId` each fire runs the active version, and `backfillPolicy` (`coalesce`, `fire_each_missed` or `drop`; default `coalesce`) says what happens to fires missed while the scheduler could not run:

```bash theme={null}
TRIGGER_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/triggers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekday-9am-eastern-v1" \
  -d "{\"orgUnitId\": \"$ORG_UNIT_ID\", \"cronExpression\": \"0 9 * * 1-5\", \"timezone\": \"America/New_York\"}" \
  | jq -r '.data.trigger.id')
```

This needs `workflows:manage` at the workflow's home and at the trigger's org unit, and the credential's scopes must also include `workflows:read`. An External App's trigger belongs to the app and is paused, with an audit event, when the app loses `workflows:manage`; a Personal key's belongs to its owner and keeps firing after the key expires.

Confirm the next fire time, which needs `workflows:read`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/triggers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {id, kind, cronExpression, timezone, enabled, nextFireAt}'
```

`nextFireAt` is epoch milliseconds, and null when the trigger is disabled or its workflow is paused or retired. `POST /api/v3/workflow-triggers/{triggerId}/pause` stops a trigger and `.../resume` starts it again.

Over MCP, create the trigger with `forge_call_operation`:

```json theme={null}
{
  "operationId": "createWorkflowTrigger",
  "input": { "workflowId": "<workflow id>", "orgUnitId": "<org unit id>", "cronExpression": "0 9 * * 1-5", "timezone": "America/New_York" },
  "idempotencyKey": "weekday-9am-eastern-v1"
}
```

and list it with `forge_call_read_operation`:

```json theme={null}
{ "operationId": "listWorkflowTriggers", "input": { "workflowId": "<workflow id>" } }
```

***

**Cross-links:** [Workflow Execution flow](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md) · [Observability](https://docs.gloo.com/forge/run/observability.md) · [Webhooks](https://docs.gloo.com/forge/run/webhooks.md)

## Trigger authority and signed ingress

Creating, changing, or resuming a trigger checks the signed-in operator against the
published version's Credential bindings and agents, just as publishing does. A trigger
that follows the active version checks that version at the time of the change. Pausing,
disabling (including from the edit dialog), and deleting a trigger remain available with
workflow management permission; re-enabling it checks the operator again. A disable that
also changes the schedule, backfill policy, or dispatch arguments is a change, and checks
the operator like any other.

Ingress for a version with company acting-for grants requires HMAC-SHA256 signing.
A capability URL alone is insufficient. Enable signing in the ingress configuration and
configure the same secret and signature header at the sender. Admission checks the
version it will launch before deduplication, so a later privileged publish cannot leave
an unsigned follow-active trigger open. Stored secrets and token hashes are never shown
in trigger reads.

Email routes follow the same rules. Creating a workflow route, or changing one other than
disabling it, checks the operator the same way. Mail for a version with company acting-for
grants is accepted only on a route whose sender policy requires a DKIM-aligned sender; an
open route rejects it before any run starts.

A Platform API dispatch that names a callback the published version does not allow gets
`422` with the reason. A workflow its owner must fix first, such as one with no home, gets
`503`.

## Published callback destinations

In Workflow Settings, select a callback destination policy and publish a new version:

* **Disabled:** no caller callback is accepted. This is also the behavior of older versions
  with no policy.
* **Caller-selected destination:** an authenticated external application can choose an
  HTTPS callback URL that passes the existing network-address checks.
* **Fixed destination:** publish the exact HTTPS URL and active external application ID.
  The application must be owned by the workflow's home org unit or one of its descendants,
  and configuring it requires external application management permission at the
  application's org unit. A caller cannot substitute another URL or application, and each
  run rechecks the application's owner before it starts.

Existing callback users must republish with an explicit policy before dispatching with
callbacks. Do not rewrite historical published versions. Runs retain their authorized
callback destination through retries and finalization; editing a draft or publishing a
new version does not redirect an existing run. A test run of a draft sends no callback,
whatever policy the draft holds, because a draft is not a published version. Existing
Slack and channel destinations remain fields of the published graph.

Rolling back rechecks the rollback operator's publish authority and records that actor
as publisher and grantor. Other versions' grants remain available to their pinned runs.

## Where a workflow may run

A workflow runs at its home org unit. Every launch (the Run button, a schedule, a
capability URL, the Platform API, the Personal Agent) is decided there: a person may
launch it when they hold workflow execution for the whole platform, or when a role grant
for `workflows:use` covers the home, either at the home itself or at one of its parent
units. A grant at an unrelated unit does not count, and naming a different org unit on
the request does not change where the check happens. The Run button in the Console also
checks workflow execution for the whole platform before it decides at the home, so a
person whose `workflows:use` grant is held only at the home, or at one of its parent
units, cannot yet start the run from the Run button.

A Platform API dispatch is bounded by the calling application's own owning org unit: an
application owned by an org unit may dispatch a workflow only when that unit is the
workflow's home or one of the home's parent units. An application owned by unit A can
therefore dispatch workflows homed at A or below it, but not at a sibling of A or at A's
parent, even when its role grants hold `workflows:use` there. A launchable workflow outside
that tree answers `404`. The application comes from how the request authenticated, never
from the request body. A plain API key has no owning org unit, and neither does an
application owned by a user, factory or project, so neither can dispatch a workflow through
the Platform API. Schedules and capability URLs carry the authority checked when their
trigger was authored.

A workflow with no home, or whose home no longer resolves, cannot be launched by anyone.
Set its home before running it.

## Related

* [Signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md): start a run from an outside system.
* [Webhooks](https://docs.gloo.com/forge/run/webhooks.md): send events out when a run changes.
* [Observability](https://docs.gloo.com/forge/run/observability.md): watch scheduled runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.