Configure team hours

Team hours define when a team is working, for example Monday to Friday, 09:00–17:00 in the team’s timezone. After you set a team’s hours, you can use them in two places:

In an escalation chain, the Pause escalation until team hours step holds the escalation until the team’s next working period starts, so low-urgency alerts don’t page anyone overnight.
In a routing template, the within_team_hours variable lets a route match only during or outside the team’s hours, so you can send the alert to a different escalation chain.

Team hours belong to a team. Each user can also set their own working hours, which show availability on schedule hover cards and don’t affect escalation. For those, refer to Define custom working hours.

How team hours work

Each team has one timezone and up to three intervals.

Timezone: IRM reads every time range in the team’s timezone, including across daylight saving time changes. If you don’t choose a timezone, IRM uses UTC.
Intervals: An interval is a named weekly schedule, such as Business hours or Weekend coverage. Each interval sets which days are working days and up to three time ranges for each of those days, for example 09:00–12:00 and 13:00–17:00.
Combined result: The team is within its hours when the current time falls in any time range of any interval.

IRM treats a team with no team hours as always within its hours. A Pause escalation until team hours step for that team never pauses, and within_team_hours is True. This means you can add the step or the variable before the team has set its hours, and no alert group waits forever.

A time range starts and ends on the same day. To cover an overnight shift, split it across two days: set the first day’s End time to 00:00, and start the next day’s range at 00:00.

Choose between the step and the variable

Use the routing variable when different people or chains should handle the alert depending on the time, for example the team during the day and a dedicated after-hours schedule at night. The decision happens once, when the alert arrives.

Use the escalation step when the same people should handle the alert, but not until they’re working. The decision happens when the escalation reaches the step, which can be well after the alert arrives.

You can combine both. For example, route critical alerts outside team hours to an after-hours chain, and send everything else to a chain that starts with Pause escalation until team hours.

Before you begin

To view a team’s hours, you need the grafana-irm-app.other-settings:read permission, which the Settings Reader and Settings Editor roles include.

To edit a team’s hours, you need:

The grafana-irm-app.other-settings:write permission, which the Admin basic role and the Settings Editor role include. For details, refer to Roles and permissions.
Membership in the team, if the Require team membership for updates setting is on. Administrators can edit any team. Refer to Require team membership for updates.

Without write access, you can still open a team’s settings and switch between its intervals to read the hours, but the fields and Save are disabled.

Set a team’s hours

Set team hours from the team’s IRM settings:

Go to IRM > Settings > Teams.
Click Edit team (the pencil icon) next to the team.
In the Team hours section, turn on Enable. The editor starts with one interval that covers Monday to Friday, 09:00–17:00.
Select the team’s Timezone.
Optional: Under Intervals, enter a Label to name the interval. An interval you don’t name is saved as Interval 1, Interval 2, and so on.
Set the interval’s working days and times:
- Turn each day on or off with its switch.
- Set a Start time and End time for each range. An end time of 00:00 means the end of that day.
- Click Add time range to split a day into up to three ranges.
- Click Apply DAY to all enabled days to copy the first working day’s ranges to the other working days.
Optional: Click Add to add another interval, up to three. Click the trash icon to remove one.
Click Save.

IRM blocks saving while there’s a problem, for example two ranges on the same day that overlap, or an interval with no working days. A message under the editor names the interval and day to fix.

To stop using team hours, turn off Enable and click Save. This removes all of the team’s intervals, and IRM treats the team as always within its hours again.

Set team hours with the API

You can also read and replace a team’s intervals with the HTTP API. Each request replaces all of the team’s intervals. Refer to Team hours HTTP API.

The API can’t change a team’s timezone. Set it in IRM > Settings > Teams before you rely on the hours you send.

Pause an escalation until team hours

Use the Pause escalation until team hours step to delay the rest of an escalation chain until a team is working. For example, a chain for low-priority alerts can notify the team during the day without waking anyone at night.

To add the step:

Go to IRM > Escalation chains and select a chain.
In the Add escalation step drop-down, select Pause escalation until team hours.
Select the team whose hours the step uses. The step starts with the escalation chain’s own team, if it has one, but you can choose any team.
Drag the step to where the pause should happen. Steps after it run when the pause ends.

When an escalation reaches the step:

If the team is within its hours, or has no team hours, escalation continues straight to the next step.
If the team is outside its hours, escalation pauses until the team’s next time range starts. The alert group timeline shows escalation paused for '<TEAM>' until <DATE_AND_TIME> (UTC). In Slack, the time shows in each reader’s local time.
When the pause ends, the timeline shows escalation resumed for '<TEAM>': team hours reached, and the next step runs.

IRM checks the team’s hours again when the pause is due to end, so changes you make to the hours while an alert group is paused still apply to it. Acknowledging or resolving the alert group stops the escalation as usual. To end a pause early, use Skip to the next escalation step.

If a step has no team, IRM skips it and the timeline shows skipped escalation step "Pause escalation until team hours": team is not set.

To add the step with the API, create an escalation policy with the type pause_until_team_working_hours and the team in team_to_notify. Refer to Escalation policies HTTP API.

Example: Page the team only during its hours

This chain notifies the Platform team about a low-priority alert, but only during the team’s hours:

1. Pause escalation until Platform team hours
2. Notify team members one by one (round-robin): Platform
3. Wait 30 minutes
4. Notify all team members: Platform

An alert that arrives on a Saturday waits until the Platform team’s hours start on Monday, then notifies one member of the team. An alert that arrives on a weekday afternoon notifies a team member right away.

Route alerts by team hours

Routing templates can read the within_team_hours variable. It’s True when the integration’s team is within its hours, and False when it’s outside them.

The variable uses the team assigned to the integration that received the alert, not the team of any escalation chain. It’s True when the integration has no team, or when that team has no team hours.

For example, to send critical alerts that arrive outside team hours to an after-hours escalation chain, add this route above your other routes:

{# Critical, outside team hours #}
{{ payload.severity == "critical" and not within_team_hours }}

To match only alerts that arrive while the team is working:

{# During team hours #}
{{ within_team_hours }}

Keep the following in mind when you use the variable:

The variable is only available in routing templates, not in appearance or other behavioral templates.
The template preview doesn’t know whether the team is within its hours, so a preview of a template that uses within_team_hours doesn’t show the live result. Check routing with a test alert instead.
IRM picks the route once, when the alert group is created. An alert group doesn’t move to another route when team hours start or end. To change what happens partway through an escalation, use the Pause escalation until team hours step.
When team hours start or end, routing can take up to 30 seconds to reflect it. Saving new team hours applies to routing immediately.

For more about routes, refer to Configure routing rules.