From c9cb4328e814f674b0f7b42556c14e16518c354a Mon Sep 17 00:00:00 2001 From: Matias Bordese Date: Thu, 17 Aug 2023 10:47:16 -0300 Subject: [PATCH] Add documentation about shift swap requests (#2719) Related to https://github.com/grafana/oncall/issues/2589 --------- Co-authored-by: Vadim Stepanov Co-authored-by: Dieter Plaetinck --- docs/sources/insights-and-metrics/_index.md | 3 +- .../mobile-app/push-notifications/index.md | 24 ++++- docs/sources/on-call-schedules/_index.md | 11 +++ .../on-call-schedules/shift-swaps/_index.md | 98 +++++++++++++++++++ engine/apps/api/views/shift_swap.py | 2 - .../schedules/models/shift_swap_request.py | 1 - 6 files changed, 130 insertions(+), 9 deletions(-) create mode 100644 docs/sources/on-call-schedules/shift-swaps/_index.md diff --git a/docs/sources/insights-and-metrics/_index.md b/docs/sources/insights-and-metrics/_index.md index 5f606306..2c84ea81 100644 --- a/docs/sources/insights-and-metrics/_index.md +++ b/docs/sources/insights-and-metrics/_index.md @@ -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 diff --git a/docs/sources/mobile-app/push-notifications/index.md b/docs/sources/mobile-app/push-notifications/index.md index e5f569f9..ae873817 100644 --- a/docs/sources/mobile-app/push-notifications/index.md +++ b/docs/sources/mobile-app/push-notifications/index.md @@ -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//on-call-schedules/shift-swaps" +[shift-swaps]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/shift-swaps" +{{% /docs/reference %}} diff --git a/docs/sources/on-call-schedules/_index.md b/docs/sources/on-call-schedules/_index.md index 2493a55f..defc709c 100644 --- a/docs/sources/on-call-schedules/_index.md +++ b/docs/sources/on-call-schedules/_index.md @@ -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]( ) 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//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//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//on-call-schedules/shift-swaps" +[shift-swaps]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/alerting-and-irm/oncall/on-call-schedules/shift-swaps" {{% /docs/reference %}} diff --git a/docs/sources/on-call-schedules/shift-swaps/_index.md b/docs/sources/on-call-schedules/shift-swaps/_index.md new file mode 100644 index 00000000..97858cbf --- /dev/null +++ b/docs/sources/on-call-schedules/shift-swaps/_index.md @@ -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 () 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. + + + +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. + + + + +>**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. + + + +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. + + + +## 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. + + + +You can also check (and take) a swap request details in the web UI. + + + +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 %}} diff --git a/engine/apps/api/views/shift_swap.py b/engine/apps/api/views/shift_swap.py index 8d47589f..8e89d68c 100644 --- a/engine/apps/api/views/shift_swap.py +++ b/engine/apps/api/views/shift_swap.py @@ -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], diff --git a/engine/apps/schedules/models/shift_swap_request.py b/engine/apps/schedules/models/shift_swap_request.py index 232440ff..ba90e215 100644 --- a/engine/apps/schedules/models/shift_swap_request.py +++ b/engine/apps/schedules/models/shift_swap_request.py @@ -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