Documentation Grafana Cloud Platform Workflows Reference Blueprints Welcome the incoming on-call

Welcome the incoming on-call

Send a Slack direct message to whoever just went on call, with their shift end time and a start-of-shift checklist.

This Grafana Workflows blueprint is in the On-call category of the Blueprints library.

Before you begin

To use this blueprint, you need:

• Grafana IRM set up on your stack.
• Slack connected to Grafana IRM. For details, refer to Configure Slack for Grafana IRM.

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: welcome-incoming-on-call
  annotations:
    grafana.app/folder: <FOLDER_UID>
spec:
  name: Welcome the incoming on-call
  enabled: false
  startWhen:
    matchingRules:
      - eventNameRegex: 'grafana_irm_app\.schedule\.updated'
        filter: 'size(inputs.data.usersAdded) > 0'
    schedules: []
  steps:
    - id: get-on-call
      type: irm.schedule-current-oncall
      name: Look up the new shift
      description: Fetches the current on-call users and shift times for the schedule that changed. No changes needed.
      inputs:
        scheduleIdentifier: '${inputs.data.scheduleID}'
        identifierType: 'id'
    - id: can-message
      type: filter
      name: Anyone to message?
      description: Continues only when at least one newly added on-call user has a linked Slack account. No changes needed.
      inputs:
        condition: "steps['get-on-call'].outputs.users.exists(u, u.slack != null && inputs.data.usersAdded.exists(a, a.email == u.email))"
    - id: send-welcome
      type: slack.direct-message.send
      name: DM the incoming on-call
      description: Sends the welcome message. Edit the checklist to match your team's start-of-shift routine.
      inputs:
        users: "${json_stringify(steps['get-on-call'].outputs.users.filter(u, u.slack != null && inputs.data.usersAdded.exists(a, a.email == u.email)).map(u, u.slack.user_id))}"
        message: |
          :wave: You're now on call for *${inputs.data.schedule.name}*.
          Your shift ends ${size(steps['get-on-call'].outputs.shifts) > 0 ? steps['get-on-call'].outputs.shifts[0].shift_end : 'when the schedule says so'} (UTC).

          Start-of-shift checklist:
          • Check that your notification rules in Grafana IRM are up to date.
          • Review open incidents and any alert groups that are still firing.
          • Read the handoff notes from the previous on-call.

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.schedule.updated event.

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

text Copy

size(inputs.data.usersAdded) > 0

How the steps fit together

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

• Triggers on grafana_irm_app.schedule.updated, which fires when on-call users change.
• The trigger filter continues only when inputs.data.usersAdded is not empty, so runs where someone only left the rotation are skipped.
• The schedule event identifies users by email but not by Slack ID, so irm.schedule-current-oncall looks up the schedule by inputs.data.scheduleID (identifierType id) to get each user’s linked Slack account (users[].slack.user_id, null when not linked) and the shift times.
• CEL macros do the matching.
• filter() keeps on-call users who were just added and have Slack linked, map() extracts their Slack IDs, and json_stringify() turns the list into the JSON array the users parameter expects.
• exists() in a filter step stops the run when nobody can be messaged.
• When several people join at once, they get one group DM.
• Customize the checklist in the message.

Next steps

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