---
title: "Invite on-call from incident label | Grafana Cloud documentation"
description: "When someone adds a team label to an active incident, invite that team's current on-call engineer to the incident."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Invite on-call from incident label

> Note
> 
> Grafana Workflows is currently in [public preview](https://grafana.com/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

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.

Expand table

| Step                        | ID                 | Type                          | Description                                                                                                                                        |
|-----------------------------|--------------------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| Find the team’s on-call     | `get-team-on-call` | `irm.team-current-oncall`     | Looks up who is on call for the IRM team named by the label value. No changes needed.                                                              |
| Invite the on-call engineer | `invite-on-call`   | `irm.invite-user-to-incident` | 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. |
| Note that the workflow ran  | `note-invite`      | `incident.add-note`           | Adds a timeline note saying this workflow invited the on-call engineer. No changes needed.                                                         |

For the inputs and outputs of each step type, refer to [Step and trigger types reference](https://grafana.com/docs/grafana-cloud/platform/workflows/reference/step-trigger-types).

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](https://grafana.com/docs/grafana-cloud/platform/workflows/as-code).

YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
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 code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy

```text
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](https://grafana.com/docs/grafana-cloud/platform/workflows/reference/blueprints)
- [Start from a blueprint](https://grafana.com/docs/grafana-cloud/platform/workflows/build/use-blueprints)
- [Manage workflows as code](https://grafana.com/docs/grafana-cloud/platform/workflows/as-code)
- [Step and trigger types reference](https://grafana.com/docs/grafana-cloud/platform/workflows/reference/step-trigger-types)