--- title: "Configure triggers | Grafana Cloud documentation" description: "Configure event-based, schedule-based, and manual triggers for Grafana Workflows, including event matching rules, cron schedules, timezones, and deduplication." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Configure triggers > Note > > Grafana Workflows is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. Triggers define when a workflow starts. A workflow can have an event-based trigger, a schedule-based trigger, or run only when you start it manually. You can also combine event and schedule triggers in a single workflow. ## Configure event triggers Event triggers start a workflow when an incoming event matches a regular expression pattern. ### How event matching works Events are named according to the pattern `{app}.{resource-type}.{event-type}`, for example, `grafana_irm_app.incident.updated`. Workflows tests each matching rule against this name. Each matching rule is a regular expression. If any rule matches the incoming event name, the workflow starts. ### Add an event trigger in the editor 1. Select **Event** as the trigger type when creating or editing a workflow. 2. Select an event, for example, **Incident Updated**. To match a pattern instead, select **Custom event** and enter a regular expression in **Event Name Regex**. For example, a pattern of `grafana_irm_app\.incident\..*` triggers the workflow on any incident event. ### Add event triggers in YAML Define matching rules in the `startWhen.matchingRules` section of the workflow definition: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml startWhen: matchingRules: - eventNameRegex: "grafana_irm_app\\.incident\\.updated" ``` You can define multiple matching rules. The workflow triggers if any rule matches: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml startWhen: matchingRules: - eventNameRegex: "grafana_irm_app\\.incident\\.updated" - eventNameRegex: "grafana_irm_app\\.alertgroup\\.updated" ``` ### Identify available event sources The following table lists the available event sources: Expand table | App | Resource | Event | Example event name | Description | |-------------------|--------------|-----------|--------------------------------------|------------------------------------------------------| | `grafana_irm_app` | `incident` | `updated` | `grafana_irm_app.incident.updated` | Fires any time an incident is created or updated. | | `grafana_irm_app` | `alertgroup` | `updated` | `grafana_irm_app.alertgroup.updated` | Fires any time an alert group is created or updated. | | `grafana_irm_app` | `schedule` | `updated` | `grafana_irm_app.schedule.updated` | Fires when the current on-call users change. | When a workflow triggers on an incident event (`grafana_irm_app.incident.*`), Workflows loads the incident into the workflow context. Steps can reference it using `${resources.incident.event.title}` and similar expressions. For details, refer to [Load incident data](/docs/grafana-cloud/platform/workflows/load-incident-data). When a workflow triggers on an alert group event (`grafana_irm_app.alertgroup.*`), Workflows loads the alert group data into the workflow context. Steps can reference it using `${resources.alertgroup.event.title}` and similar expressions. For details, refer to [Load alert group data](/docs/grafana-cloud/platform/workflows/load-alert-group-data). ## Configure schedule triggers Schedule triggers start a workflow at recurring times using cron syntax. Schedules follow the standard five-field Unix cron format and default to UTC. text ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```text minute hour day-of-month month day-of-week ``` ### Add a schedule trigger in the editor 1. Select **Schedule** as the trigger type when creating or editing a workflow. 2. In the configuration panel, set the schedule in **Form** mode, or select **Cron** and enter a cron expression in **Cron Expression**. ### Add schedule triggers in YAML Define schedules in the `startWhen.schedules` section of the workflow definition: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml startWhen: schedules: - "0 9 * * 1-5" ``` ### Run a schedule in a specific timezone To run a schedule in a timezone other than UTC, prefix the expression with `CRON_TZ=`, where *TIMEZONE* is an IANA timezone name. For example, the following schedule runs at 9:00 AM Eastern time on weekdays, accounting for daylight saving time: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml startWhen: schedules: - "CRON_TZ=America/New_York 0 9 * * 1-5" ``` Use any IANA timezone name, for example, `America/Los_Angeles`, `Europe/London`, or `Asia/Tokyo`. Expressions without a `CRON_TZ=` prefix run in UTC. ### Understand cron syntax Cron fields support wildcards (`*`), ranges (`1-5`), steps (`*/10`), and lists (`1,3,5`): Expand table | Field | Range | Special characters | |--------------|-------------------|--------------------| | Minute | 0-59 | `*`, `,`, `-`, `/` | | Hour | 0-23 | `*`, `,`, `-`, `/` | | Day of month | 1-31 | `*`, `,`, `-`, `/` | | Month | 1-12 | `*`, `,`, `-`, `/` | | Day of week | 0-6 (0 is Sunday) | `*`, `,`, `-`, `/` | The following examples show common schedule patterns: Expand table | Schedule | Meaning | |----------------------------------------|------------------------------------------| | `0 9 * * 1-5` | Every weekday at 9:00 AM UTC | | `CRON_TZ=America/New_York 0 9 * * 1-5` | Every weekday at 9:00 AM Eastern time | | `*/30 * * * *` | Every 30 minutes | | `0 0 1 * *` | First day of every month at midnight UTC | ## Trigger workflows manually You can manually trigger any workflow from the editor, regardless of whether it has event or schedule triggers configured. **Run** is available after you save the workflow for the first time and turn on **Enable**. It runs the workflow as it’s shown in the editor, including unsaved changes. To manually trigger a workflow in the editor: 1. Click **Run** in the editor header. 2. In the **Trigger Workflow** dialog box, edit the JSON event payload as needed and click **Trigger Workflow**. Workflows expects an event in [CloudEvents](https://cloudevents.io/) shape. The fields under `data` become available in your steps as `inputs.data.*`. The other fields (`id`, `type`, `source`, `time`) describe the event itself. > Note > > **Run** doesn’t load incident or alert group data from the sample event, and it doesn’t apply trigger filters. To test a workflow that uses that data, add the incident or alert group as a resource. For details, refer to [Test with incident data](/docs/grafana-cloud/platform/workflows/load-incident-data/#test-with-incident-data) and [Test with alert group data](/docs/grafana-cloud/platform/workflows/load-alert-group-data/#test-with-alert-group-data). To create a workflow that runs only when manually triggered, leave both `matchingRules` and `schedules` empty: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml startWhen: matchingRules: [] schedules: [] ``` ## Deduplicate workflow runs The `runOnceFor` option prevents duplicate workflow runs for the same incident, alert group, or other event source. Set it to a template that builds a key from the event data. The workflow runs once for each key. Use `${...}` segments for CEL expressions inside the template. For example, setting `runOnceFor` to `incident:${inputs.data.incidentID}` means that if multiple events arrive for the same incident ID, the workflow runs only for the first event. This is useful when you want to react to an incident exactly once, even if IRM sends several related events in quick succession. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml spec: runOnceFor: "incident:${inputs.data.incidentID}" startWhen: matchingRules: - eventNameRegex: "grafana_irm_app\\.incident\\..*" ``` ### Reference only event data Workflows builds the deduplication key before the workflow starts, so the only part of the workflow context it can use is `inputs`. This means `runOnceFor` can’t reference `steps` or `resources`. No step has run yet, and incident, alert group, and secret resources aren’t loaded. Referencing either one causes a validation error when you save the workflow. Use the matching field from the event payload instead. For example, use `${inputs.data.incidentID}` rather than `${resources.incident.event.incidentID}`. To find the field names available for an event, refer to [Step and trigger types reference](/docs/grafana-cloud/platform/workflows/reference). > Note > > You can’t use `runOnceFor` on a workflow that has a schedule trigger. Workflows already runs each scheduled time once, so setting `runOnceFor` on a scheduled workflow causes a validation error when you save the workflow. ## Combine event and schedule triggers A workflow can have both event and schedule triggers. The workflow starts when any matching rule matches an incoming event or when any schedule fires. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml startWhen: matchingRules: - eventNameRegex: "grafana_irm_app\\.incident\\.updated" schedules: - "0 9 * * 1-5" ``` ## Next steps - [Create workflows](/docs/grafana-cloud/platform/workflows/create-workflows) - [Load incident data](/docs/grafana-cloud/platform/workflows/load-incident-data) - [Load alert group data](/docs/grafana-cloud/platform/workflows/load-alert-group-data) - [Use CEL expressions](/docs/grafana-cloud/platform/workflows/use-expressions) - [Sample event payloads](/docs/grafana-cloud/platform/workflows/reference/event-payloads) - [Step and trigger types reference](/docs/grafana-cloud/platform/workflows/reference)