Add documentation about shift swap requests (#2719)
Related to https://github.com/grafana/oncall/issues/2589 --------- Co-authored-by: Vadim Stepanov <vadimkerr@gmail.com> Co-authored-by: Dieter Plaetinck <dieter@plaetinck.be>
This commit is contained in:
Matias Bordese
GitHub
parent
179a1db471
commit
c9cb4328e8
6 changed files with 130 additions and 9 deletions
|
|
@ -177,7 +177,8 @@ Logs contain the following fields, where the fields followed by * are always ava
|
|||
|
||||
resource types are: `integration_heartbeat`, `escalation_chain`, `integration`, `outgoing_webhook`,
|
||||
`escalation_policy`, `public_api_token`, `schedule_export_token`,`user_schedule_export_token`,
|
||||
`oncall_shift`, `web_schedule`, `ical_schedule`, `calendar_schedule`, `organization`, `user`, `webhook`.
|
||||
`oncall_shift`, `web_schedule`, `ical_schedule`, `calendar_schedule`, `shift_swap_request`, `organization`,
|
||||
`user`, `webhook`.
|
||||
|
||||
### Maintenance insight logs
|
||||
|
||||
|
|
|
|||
|
|
@ -11,11 +11,12 @@ weight: 200
|
|||
|
||||
# Push notifications
|
||||
|
||||
There are three types of push notifications for the mobile app:
|
||||
There are four types of push notifications for the mobile app:
|
||||
|
||||
- **Mobile push** - Sends a typical push notification to your mobile device. Intended for all types of alerts.
|
||||
- **Mobile push important** - Sends a push notification for important alerts. We recommend (and default) to louder notifications.
|
||||
- **On-Call Shift Notifications** - Sends announcements for upcoming shifts (optional).
|
||||
- **On-call shift notifications** - Sends announcements for upcoming shifts (optional).
|
||||
- **Shift swap notifications** - Sends announcements for [shift swap requests][shift-swaps] (optional).
|
||||
|
||||
## Add mobile app to notification policies
|
||||
|
||||
|
|
@ -39,7 +40,7 @@ correct configuration of **Do Not Disturb** and **Volume** overrides.
|
|||
### Android
|
||||
|
||||
On Android, we leverage the "Notification channels" system feature.
|
||||
Each type of notification (**important**, **default**, and **on-call shifts**) registers a channel.
|
||||
Each type of notification (**important**, **default**, and **info**) registers a channel.
|
||||
In this channel, you may configure the sound style, vibration, and so on.
|
||||
**Customize notifications** takes you to this system menu, while hitting the **back** button or swiping left (if enabled) takes you back to the application.
|
||||
|
||||
|
|
@ -71,7 +72,7 @@ notifications triggered by the application, which is described above.
|
|||
|
||||
On iOS, all configuration (such as sound selection, Do Not Disturb override, etc) happens inside the app.
|
||||
|
||||
For every type of notification (**important**, **default**, and **on-call shifts**), you can configure the sound and its style (constant vs intensifying).
|
||||
For every type of notification (**important**, **default**, and **info**), you can configure the sound and its style (constant vs intensifying).
|
||||
|
||||
You can also enable or disable Do Not Disturb override for **important** notifications.
|
||||
|
||||
|
|
@ -82,4 +83,17 @@ You can also enable or disable Do Not Disturb override for **important** notific
|
|||
|
||||
On-call shift notifications are sent to announce upcoming shifts, roughly ~15 minutes in advance.
|
||||
|
||||
To enable or disable on-call shift notifications, use the **On-call shift notifications** section in the **Push notifications** settings.
|
||||
To enable or disable on-call shift notifications, use the **info notifications** section in the **Push notifications** settings.
|
||||
|
||||
### Shift swap notifications
|
||||
|
||||
Shift swap notifications are generated when a [shift swap ][shift-swaps] is requested,
|
||||
informing all users in the on-call schedule (except the initiator) about it.
|
||||
|
||||
To enable or disable shift swap notifications and their follow-ups, use the **info notifications** section
|
||||
in the **Push notifications** settings.
|
||||
|
||||
{{% docs/reference %}}
|
||||
[shift-swaps]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/shift-swaps"
|
||||
[shift-swaps]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/shift-swaps"
|
||||
{{% /docs/reference %}}
|
||||
|
|
|
|||
|
|
@ -45,6 +45,14 @@ read-only and cannot be edited from the UI.
|
|||
To learn more, read our [Get started with Grafana OnCall and Terraform](
|
||||
<https://grafana.com/blog/2022/08/29/get-started-with-grafana-oncall-and-terraform/>) blog post.
|
||||
|
||||
### Shift swap requests
|
||||
|
||||
Sometimes you may need someone to cover your scheduled on-call shifts (e.g. you are going on vacation
|
||||
for a couple of weeks). You can then create a shift swap request, which will let your teammates
|
||||
know about this as well as allowing them to volunteer and take your affected shifts for that period.
|
||||
|
||||
Learn more about [Shift swap requests][shift-swaps]
|
||||
|
||||
{{% docs/reference %}}
|
||||
[ical-schedules]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/ical-schedules"
|
||||
[ical-schedules]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/ical-schedules"
|
||||
|
|
@ -54,4 +62,7 @@ To learn more, read our [Get started with Grafana OnCall and Terraform](
|
|||
|
||||
[web-schedule]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/web-schedule"
|
||||
[web-schedule]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/web-schedule"
|
||||
|
||||
[shift-swaps]: "/docs/oncall/ -> /docs/oncall/<ONCALL VERSION>/on-call-schedules/shift-swaps"
|
||||
[shift-swaps]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/shift-swaps"
|
||||
{{% /docs/reference %}}
|
||||
|
|
|
|||
98
docs/sources/on-call-schedules/shift-swaps/_index.md
Normal file
98
docs/sources/on-call-schedules/shift-swaps/_index.md
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
title: Shift swaps
|
||||
canonical: https://grafana.com/docs/oncall/latest/on-call-schedules/shift-swaps/
|
||||
description: "Learn more about Grafana OnCall shift swaps"
|
||||
keywords:
|
||||
- Grafana
|
||||
- oncall
|
||||
- schedule
|
||||
- swap
|
||||
title: Shift swaps
|
||||
weight: 400
|
||||
---
|
||||
|
||||
# Shift swaps
|
||||
|
||||
Shift swaps provide a convenient way for on-call engineers to find team members to exchange on-call shifts
|
||||
in a schedule for a specified time span to covered planned or unplanned unavailability.
|
||||
|
||||
## Make a swap request
|
||||
|
||||
To request a shift swap, you can use the OnCall mobile app or the web UI in a schedule details page.
|
||||
|
||||
In the app, tapping one of your shifts presents an option to construct a shift swap request for that and/or
|
||||
other shifts.
|
||||
|
||||
It is also possible to setup a request from a schedule view, tapping on the `request a swap`
|
||||
button (<img src="/static/img/oncall/swap-mobile-button.png" width="25px">) displayed in the top-right corner.
|
||||
Include shifts by tapping them and/or specify starting and ending datetimes (they don't need to match
|
||||
shifts exactly). The optional description will be displayed when notifying other users about the request.
|
||||
|
||||
<img src="/static/img/oncall/swap-mobile-request-2.png" width="300px">
|
||||
|
||||
In the web UI, you can follow a similar flow via the `Request shift swap` button, available in the `Rotations` lane
|
||||
of a schedule, or clicking the button shown when hovering on a particular shift event in which you are on-call.
|
||||
|
||||
<img src="/static/img/oncall/swap-web-hover.png">
|
||||
<img src="/static/img/oncall/swap-web-request.png">
|
||||
|
||||
>**Note**: no recurrence rules support is available when requesting a shift swap. If you need to recurrently change a shift,
|
||||
consider creating a higher level layer rotation with the desired updates.
|
||||
|
||||
Upon submitting the request, a Slack notification will be sent to the channel associated to the correspondent
|
||||
schedule, if there is one. A [mobile push notification][shift-swap-notifications] will be sent to team members who
|
||||
participate in the schedule and have the notifications enabled.
|
||||
|
||||
<img src="/static/img/oncall/swap-slack-notification.png">
|
||||
|
||||
Push notifications are sent 4 weeks ahead of the requested shift swap, or shortly after creation in case
|
||||
the shift swap start time is less than 4 weeks away, but always during users' working hours (by default 9am-5pm on
|
||||
weekdays, according to the user's mobile device timezone).
|
||||
|
||||
As long as the request is open, there will be follow-up mobile notifications as well as Slack updates
|
||||
to remind about the request.
|
||||
The follow-up notifications will be sent at the following intervals before the swap start:
|
||||
|
||||
- 4 weeks
|
||||
- 3 weeks
|
||||
- 2 weeks
|
||||
- 1 week
|
||||
- 3 days
|
||||
- 2 days
|
||||
- 1 day
|
||||
- 12 hours
|
||||
|
||||
You can delete the swap request at any time. If the swap has been taken, it will automatically be undone upon removal.
|
||||
|
||||
>**Note**: if [RBAC][rbac] is enabled, a user is required to have the `SCHEDULES_WRITE` permission to create,
|
||||
update, take or delete a swap request. `SCHEDULES_READ` will be enough to get details about existing requests.
|
||||
|
||||
## Check existing swap requests
|
||||
|
||||
To review existing swap requests, check the events identified with the swap request icon in a schedule view,
|
||||
in the mobile app or in the web UI.
|
||||
|
||||
<img src="/static/img/oncall/swap-web-shift.png">
|
||||
|
||||
## Take a swap request
|
||||
|
||||
If you are not the request owner and the request is still open, you have the option to take the swap. By doing so,
|
||||
you will replace the requester in the given schedule for their respective shifts during the specified period.
|
||||
|
||||
If no one takes the swap request before its starting datetime, the request will be closed, and the original user
|
||||
will remain on-call if there is a shift at that time.
|
||||
|
||||
Before taking a swap, you can review the involved shifts times.
|
||||
|
||||
<img src="/static/img/oncall/swap-mobile-details-2.png" width="300px">
|
||||
|
||||
You can also check (and take) a swap request details in the web UI.
|
||||
|
||||
<img src="/static/img/oncall/swap-web-take.png">
|
||||
|
||||
Once a swap is taken, the affected rotations and the final schedule will reflect the changes.
|
||||
|
||||
{{% docs/reference %}}
|
||||
[shift-swap-notifications]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/mobile-app/push-notifications#shift-swap-notifications"
|
||||
[rbac]: "/docs/oncall/ -> /docs/oncall/latest/user-and-team-management/#role-based-access-control-rbac"
|
||||
{{% /docs/reference %}}
|
||||
|
|
@ -87,8 +87,6 @@ class ShiftSwapViewSet(PublicPrimaryKeyMixin[ShiftSwapRequest], BaseShiftSwapVie
|
|||
permission_classes = (IsAuthenticated, RBACPermission)
|
||||
|
||||
rbac_permissions = {
|
||||
# TODO: add note to public documentation about these permissions also giving access to shift swaps
|
||||
# unless we want to make a separate resource type for them?
|
||||
"metadata": [RBACPermission.Permissions.SCHEDULES_READ],
|
||||
"list": [RBACPermission.Permissions.SCHEDULES_READ],
|
||||
"retrieve": [RBACPermission.Permissions.SCHEDULES_READ],
|
||||
|
|
|
|||
|
|
@ -220,7 +220,6 @@ class ShiftSwapRequest(models.Model):
|
|||
|
||||
@property
|
||||
def insight_logs_type_verbal(self):
|
||||
# TODO: add this resource type to the insight logs public docs
|
||||
return "shift_swap_request"
|
||||
|
||||
@property
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue