Documentation Grafana Cloud Alerts and IRM 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 through manual execution. 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. Workflow matching rules are tested 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. In the configuration panel, enter a regular expression pattern.

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:

Event names follow the pattern {app}.{resource-type}.{event-type}.

When a workflow triggers on an incident event (grafana_irm_app.incident.*), the engine 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.*), the engine automatically 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, enter a 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=<IANA zone>. 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. Bare 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. Manual triggers are useful for testing workflows before enabling them for automatic execution.

To manually trigger a workflow in the editor:

1. Click Run in the editor header.
2. In the Trigger Workflow dialog, 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 executions for the same logical event. It takes a template string that renders against the event data to produce a deduplication 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 the system produces several related events in quick succession.

YAML Copy

spec:
  runOnceFor: "incident:${inputs.data.incidentID}"
  startWhen:
    matchingRules:
      - eventNameRegex: "grafana_irm_app\\.incident\\..*"

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