Documentation Grafana Cloud Platform Workflows Configure triggers

Configure triggers

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

startWhen:
  matchingRules:
    - eventNameRegex: "grafana_irm_app\\.incident\\.updated"

You can define multiple matching rules. The workflow triggers if any rule matches:

YAML Copy

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:

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.

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.

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

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

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=<TIMEZONE>, 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

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):

The following examples show common schedule patterns:

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 shape. The fields under data become available in your steps as inputs.data.*. The other fields (id, type, source, time) describe the event itself.

To create a workflow that runs only when manually triggered, leave both matchingRules and schedules empty:

YAML Copy

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

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.

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

startWhen:
  matchingRules:
    - eventNameRegex: "grafana_irm_app\\.incident\\.updated"
  schedules:
    - "0 9 * * 1-5"

Next steps

• Create workflows
• Load incident data
• Load alert group data
• Use CEL expressions
• Sample event payloads
• Step and trigger types reference