Documentation Grafana Cloud Platform Workflows Reference Blueprints Invite on-call from incident label

Invite on-call from incident label

When someone adds a team label to an active incident, invite that team’s current on-call engineer to the incident.

This Grafana Workflows blueprint is in the Incidents category of the Blueprints library.

Before you begin

To use this blueprint, you need:

• Grafana IRM set up on your stack.

Steps

Steps run in order from first to last. A step inside a switch branch runs only when Workflows chooses that branch.

For the inputs and outputs of each step type, refer to Step and trigger types reference.

Before you turn on the workflow, customize any steps that need input from you, such as a channel ID or a schedule name. Each step’s description says what to set.

Workflow definition

Save this definition as a YAML file to create the workflow with gcx, the Workflows API, or Terraform, or give it to a coding agent as an example. Replace FOLDER_UID with the UID of the folder for the workflow. Blueprints start disabled, so finish customizing the steps before you set enabled to true. For details, refer to Manage workflows as code.

YAML Copy

apiVersion: workflows.ext.grafana.app/v1alpha1
kind: Definition
metadata:
  name: invite-on-call-from-incident-label
  annotations:
    grafana.app/folder: <FOLDER_UID>
spec:
  name: Invite on-call from incident label
  enabled: false
  startWhen:
    matchingRules:
      - eventNameRegex: 'grafana_irm_app\.incident\.updated'
        filter: "inputs.data.eventKind == 'incident_added_label' && inputs.data.key == 'team' && resources.incident.event.status == 'active'"
    schedules: []
  steps:
    - id: get-team-on-call
      type: irm.team-current-oncall
      name: Find the team's on-call
      description: Looks up who is on call for the IRM team named by the label value. No changes needed.
      inputs:
        teamIdentifier: '${inputs.data.label}'
        identifierType: 'name'
    - id: invite-on-call
      type: irm.invite-user-to-incident
      name: Invite the on-call engineer
      description: Invites the team's first on-call user to the incident. Critical incidents are sent as important. Edit the message to give responders more context.
      inputs:
        userID: "${steps['get-team-on-call'].outputs.users[0].email}"
        incidentID: '${inputs.data.incidentID}'
        important: "${resources.incident.event.severity.matches('(?i)^critical$')}"
        message: 'You were invited to incident "${resources.incident.event.title}" (${resources.incident.event.severity}) because your team was added to it.'
    - id: note-invite
      type: incident.add-note
      name: Note that the workflow ran
      description: Adds a timeline note saying this workflow invited the on-call engineer. No changes needed.
      inputs:
        incidentID: '${inputs.data.incidentID}'
        message: "The **Invite on-call from incident label** workflow invited ${steps['get-team-on-call'].outputs.users[0].username}, on call for the **${inputs.data.label}** team, because the team label was added."

How it works

This section explains when the workflow runs and how its steps work together.

When it runs

This blueprint starts on the grafana_irm_app.incident.updated event.

Its trigger filter starts a run only when this CEL expression is true:

text Copy

inputs.data.eventKind == 'incident_added_label' && inputs.data.key == 'team' && resources.incident.event.status == 'active'

How the steps fit together

These notes cover how the steps connect and which Workflows behaviors the blueprint relies on.

• Triggers on eventKind incident_added_label, whose event data carries the label key and value as inputs.data.key and inputs.data.label.
• The trigger filter keeps only labels with the key team on active incidents.
• The label value is used as the IRM team name, so label values must match IRM team names exactly.
• irm.invite-user-to-incident takes a user’s email, so the workflow first looks up the team’s current on-call with irm.team-current-oncall and invites the first on-call user.
• IRM records the invitation and notifies the user, so the workflow only adds a timeline note saying it ran.
• If nobody is on call, the invite step fails and the run shows as failed.
• The important flag is a CEL expression that renders true for Critical incidents.
• Customize the label key in the trigger filter and the invitation message.
• The alert group version of this blueprint is Invite on-call from alert group label.

Next steps

• Blueprints
• Start from a blueprint
• Manage workflows as code
• Step and trigger types reference