Documentation Grafana Cloud Alerts and IRM Workflows Create workflows

Create workflows

You can create and edit workflows using the visual editor in the Grafana UI or by writing definitions in YAML or JSON. This page covers both approaches, including how to add steps, configure fields, and define conditional branches.

Before you begin

To create workflows, you need:

• A Grafana Cloud account with Workflows enabled for your stack
• Familiarity with the available step types and trigger options

Create a workflow in the editor

The workflow editor provides a visual canvas for building workflows. The editor has three areas: a tree canvas on the left that shows the workflow structure, a configuration panel on the right for editing the selected node, and a header with controls for saving, testing, and enabling the workflow.

Choose a trigger

When you create a new workflow, the first step is to choose a trigger. The editor presents three options:

• Event: React to events matching a regex pattern, for example, grafana_irm_app\.incident\.created.
• Schedule: Run on a cron schedule in UTC, for example, 0 9 * * 1-5 for weekdays at 9:00 AM.
• Manual: Trigger the workflow only through the UI or API.

Select a trigger type and configure its settings in the configuration panel. For details on trigger options, refer to Configure triggers.

Add steps

To add a step to your workflow:

1. Click + on the last node in the tree.
2. Browse or search the action palette that appears in the configuration panel.
3. Click a step type or drag it onto the drop zone.

The new step appears in the tree and the configuration panel displays its configuration form. Fill in the required fields for the step type you selected.

For a full list of available step types and their inputs, refer to Step types reference.

Configure step fields

The configuration panel renders form fields based on the step type. Field types include text inputs, text areas for longer content like message bodies, checkboxes for boolean values, dropdowns for constrained choices like HTTP methods, and JSON editors for structured data.

Fields that accept string values can include CEL expressions using ${expression} syntax to reference the workflow context. For example, you can set a URL field to https://api.example.com/incidents/${inputs.data.incidentID} to dynamically include the incident ID from the triggering event.

For details on expressions and the workflow context, refer to Use CEL expressions.

Add conditional logic

To add conditional branching:

1. Add a Switch step from the action palette.
2. The switch node appears in the tree. Click + on it to add condition branches.
3. Select each condition node and enter a CEL expression in the configuration panel, for example, inputs.data.severity == "critical".
4. Add steps inside each condition branch by clicking + on the condition node.
5. A branch with no condition expression acts as the default case.

After all branches have at least one step, a down-arrow appears on the switch node. Click it to add continuation steps that run after the switch completes, regardless of which branch executed.

Test a workflow

Click Test in the header to run the workflow with sample data. Enter a JSON object as the test input, or leave it empty for workflows that don’t depend on event data. The test run executes the workflow and you can view the results in Runs.

View the JSON definition

Click JSON in the header to open a read-only drawer showing the workflow definition as JSON. This view is useful for reviewing the full structure or copying the definition for use in version control.

Write a workflow definition

You can define workflows directly in YAML or JSON and submit them through the API. This approach is useful for version control, code review, and managing workflows as part of your infrastructure-as-code process.

Understand the definition structure

The following example shows the top-level structure of a workflow definition:

YAML Copy

apiVersion: workflows.ext.grafana.com/v1alpha1
kind: Definition
metadata:
  name: my-workflow
  namespace: my-namespace
spec:
  name: 'My Workflow'
  enabled: true
  startWhen:
    matchingRules: []
    schedules: []
  steps: []
  resources:
    secrets: {}
    incidents: {}
    alertgroups: {}
  runOnceFor: ''

• name: A human-readable name for the workflow.
• enabled: When true, the workflow runs automatically when its trigger conditions are met. When false, the workflow can only run through manual triggers or test execution.
• startWhen: Defines the trigger conditions. Contains matchingRules for event triggers and schedules for cron triggers. For details, refer to Configure triggers.
• steps: An ordered list of steps that execute sequentially.
• resources.secrets: An optional map of reference names to secret URIs for authentication. For details, refer to Manage secrets.
• resources.incidents: An optional map of reference names to incident identifiers. Values can be literal IDs or CEL expressions. For details, refer to Load incident data.
• resources.alertgroups: An optional map of reference names to alert group identifiers. Values can be literal IDs or CEL expressions. For details, refer to Load alert group data.
• runOnceFor: An optional template string for deduplication. Use ${...} segments for CEL expressions. For details, refer to Configure triggers.

Define steps

Each step requires a type, an id, and typically a set of inputs:

YAML Copy

steps:
  - id: call-api
    type: http.call
    name: 'Fetch incident details'
    inputs:
      method: 'GET'
      url: 'https://api.example.com/incidents/${inputs.data.incidentID}'

Step IDs must start with a lowercase letter and can contain lowercase letters, numbers, hyphens, and underscores.

Define branches

Use the switch step type with branches to add conditional logic:

YAML Copy

steps:
  - id: route-by-severity
    type: switch
    branches:
      - condition: "inputs.data.severity == 'critical'"
        steps:
          - id: page-oncall
            type: irm.page-user
            inputs:
              userIdentifier: "oncall@example.com"
              identifierType: "email"
              incidentID: "${inputs.data.incidentID}"
              important: true
              message: "Critical incident: ${inputs.data.title}"
      - condition: "inputs.data.severity == 'warning'"
        steps:
          - id: notify-channel
            type: slack.message.post
            inputs:
              channelID: 'C0123456789'
              messageText: 'Warning: ${inputs.data.title}'
      - steps:
          - id: log-event
            type: noop

Branches evaluate in order. The first branch whose condition evaluates to true runs. A branch with no condition field acts as the default case. Branches can be nested for complex routing logic.

Next steps

• Configure triggers
• Use CEL expressions
• Load incident data
• Load alert group data
• Manage secrets
• Step types reference