Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Platformbreadcrumb arrow Workflowsbreadcrumb arrow Referencebreadcrumb arrow Blueprintsbreadcrumb arrow On-call handoff report
Public preview Grafana Cloud
Last reviewed: November 9, 2026

On-call handoff report

Note

Grafana Workflows is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

When the on-call rotation changes, Grafana Assistant writes a handoff report from the past week of incidents and alert groups and posts it to Slack.

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.
  • Grafana Assistant in use 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.

StepIDTypeDescription
Only this scheduleonly-this-schedulefilterStops the run unless the change happened on your schedule. Put the exact IRM schedule name between the quotes.
Write the handoff reportwrite-reportassistant.promptAsks Grafana Assistant to build the handoff report from IRM data. Adjust the lookback window, the sections, or the team context in the prompt.
Post the report to Slackpost-reportslack.message.postPosts the handoff report. Set channelID to your team’s on-call channel.

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 
apiVersion: workflows.ext.grafana.app/v1alpha1
kind: Definition
metadata:
  name: on-call-handoff-report
  annotations:
    grafana.app/folder: <FOLDER_UID>
spec:
  name: On-call handoff report
  enabled: false
  startWhen:
    matchingRules:
      - eventNameRegex: 'grafana_irm_app\.schedule\.updated'
    schedules: []
  steps:
    - id: only-this-schedule
      type: filter
      name: Only this schedule
      description: >-
        Stops the run unless the change happened on your schedule. Put the exact IRM schedule
        name between the quotes.
      inputs:
        condition: "inputs.data.schedule.name == ''"
    - id: write-report
      type: assistant.prompt
      name: Write the handoff report
      description: >-
        Asks Grafana Assistant to build the handoff report from IRM data. Adjust the lookback
        window, the sections, or the team context in the prompt.
      inputs:
        prompt: |
          Write an on-call handoff report for the "${inputs.data.schedule.name}" on-call schedule in Grafana IRM.

          Outgoing on-call: ${json_stringify(inputs.data.previousOnCall.map(u, u.username))}
          Incoming on-call: ${json_stringify(inputs.data.currentOnCall.map(u, u.username))}
          Team: ${inputs.data.schedule.team != null ? inputs.data.schedule.team.name : 'not set'}
          Period: ${now() - duration('168h')} to ${now()}

          Research this period using Grafana IRM:
          1. Incidents for this team: anything still active, plus resolved incidents worth knowing about.
          2. Alert groups for this team: the noisiest ones, anything still firing or acknowledged, and repeats.
          3. Follow-ups the incoming engineer should own, such as unresolved action items or flapping alerts.

          Write slackMessage in Slack mrkdwn. Keep it under 2500 characters, lead with what needs attention now, and link incidents and alert groups where you can.
        outputSchema: |
          {
            "type": "object",
            "required": ["headline", "slackMessage"],
            "properties": {
              "headline": { "type": "string", "description": "One sentence on the state of the rotation." },
              "slackMessage": { "type": "string" }
            }
          }
        maxRetries: '3'
    - id: post-report
      type: slack.message.post
      name: Post the report to Slack
      description: Posts the handoff report. Set channelID to your team's on-call channel.
      inputs:
        channelID: ''
        messageText: |
          :handshake: *On-call handoff: ${inputs.data.schedule.name}*
          ${steps['write-report'].outputs.result.headline}

          ${steps['write-report'].outputs.result.slackMessage}

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.

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 the set of on-call users for a schedule changes.
  • The event data includes schedule (id, name, team), previousOnCall, currentOnCall, usersAdded, and usersRemoved, where each user has id, grafanaUserID, username, and email.
  • A filter step limits the workflow to one schedule, because the event fires for every schedule in the stack.
  • The assistant.prompt step asks Grafana Assistant to research the last 7 days of incidents and alert groups and return JSON that matches outputSchema.
  • Later steps read the validated object at steps['write-report'].outputs.result.
  • CEL has no string join, so user lists are rendered with json_stringify over a map() of usernames.
  • Customize the schedule name in the filter, the Slack channel, the lookback window in the prompt, and the report sections.

Next steps