---
title: "Welcome the incoming on-call | Grafana Cloud documentation"
description: "Send a Slack direct message to whoever just went on call, with their shift end time and a start-of-shift checklist."
---

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

# Welcome the incoming on-call

> 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.

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](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/integrations/chat-and-collaboration/slack/).

## 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                                                                                              |
|-------------------------|----------------|-------------------------------|----------------------------------------------------------------------------------------------------------|
| Look up the new shift   | `get-on-call`  | `irm.schedule-current-oncall` | Fetches the current on-call users and shift times for the schedule that changed. No changes needed.      |
| Anyone to message?      | `can-message`  | `filter`                      | Continues only when at least one newly added on-call user has a linked Slack account. No changes needed. |
| DM the incoming on-call | `send-welcome` | `slack.direct-message.send`   | Sends the welcome message. Edit the checklist to match your team’s start-of-shift routine.               |

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

```text
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](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)