Add responders improvements

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Changed
+
+- Simplify Direct Paging workflow. Now when using Direct Paging you either simply specify a team, or one or more users
+  to page by @joeyorlando ([#3128](https://github.com/grafana/oncall/pull/3128))
+
 ## v1.3.47 (2023-10-25)
 
 ### Fixed

docs/sources/integrations/manual/index.md

@@ -22,58 +22,53 @@ However, sometimes you might need to page a [team][manage-teams] or request assi
 are not part of these pre-defined rules.
 
 For such ad-hoc scenarios, Grafana OnCall allows you to create an alert group, input necessary information, and decide
-who will be alerted – a team, a user, or an on-call user from a specific schedule.
+who will be alerted – a team, or a set of users.
 
 ## Page a team
 
-Click on **+ New alert group** on the **Alert groups** page to start creating a new alert group.
-From there, you can configure the alert group to notify a particular team and optionally include additional users or
-schedules. Here are the inputs you need to fill in:
+Click on **+ Escalation** on the **Alert groups** page to start creating a new alert group.
+From there, you can configure the alert group to notify a particular team and optionally include additional users. Here are the inputs you need to fill in:
 
-- **Title**: Write a brief and clear title for your alert group.
-- **Message**: Optionally, add a message to provide more details or instructions.
+- **Message**: Write a message to provide more details or instructions to those whom you are paging.
 - **Team**: Select the team you want to page. The team's
-[direct paging integration](#learn-the-flow-and-handle-warnings) will be used for notification.
-- **Additional Responders**: Optionally, include more responders for the alert group.
-These could be any combination of users and schedules.
-For each additional responder (user or schedule), you can select a notification policy: [default or important][notify].
+  [direct paging integration](#learn-the-flow-and-handle-warnings) will be used for notification. _Note_ that you will only
+  see teams that have a "contactable" direct paging integration (ie. it has an escalation chain assigned to it, or has
+  at least one Chatops integration connected to send notifications to).
+- **Users**: Include more users to the alert group. For each additional user, you can select a notification policy:
+  [default or important][notify].
 
 > The same feature is also available as [**/escalate**][slack-escalate] Slack command.
 
-## Add responders for an existing alert group
+## Add users to an existing alert group
 
-If you want to page more people for an existing alert group, you can do so using the **Notify additional responders**
-button on the specific alert group's page. Here you can select more users, or choose users who are on-call for specific
-schedules. The same functionality is available in Slack using the **Responders** button in the alert group's message.
+If you want to page more people for an existing alert group, you can do so using the **+ Add**
+button, within the "Participants" section on the specific alert group's page. The same functionality is available in
+Slack using the **Responders** button in the alert group's message.
 
-Notifying additional responders doesn't disrupt or interfere with the escalation chain configured for the alert group;
-it simply adds more responders and notifies them immediately. Note that adding responders for an existing alert group
+Notifying additional users doesn't disrupt or interfere with the escalation chain configured for the alert group;
+it simply adds more responders and notifies them immediately. Note that adding users for an existing alert group
 will page them even if the alert group is silenced or acknowledged, but not if the alert group is resolved.
 
 > It's not possible to page a team for an existing alert group. To page a specific team, you need to
-[create a new alert group](#page-a-team).
+> [create a new alert group](#page-a-team).
 
 ## Learn the flow and handle warnings
 
 When you pick a team to page, Grafana OnCall will automatically use the right direct paging integration for the team.
 "Direct paging" is a special kind of integration in Grafana OnCall that is unique per team and is used to send alerts
 to the team's ChatOps channels and start an appropriate escalation chain.
 
-If a team hasn't set up a direct paging integration, or if the integration doesn't have any escalation chains connected,
-Grafana OnCall will issue a warning. If this happens, consider
-[setting up a direct paging integration](#set-up-direct-paging-for-a-team) for the team
-(or reach out to the relevant team and suggest doing so).
-
 ## Set up direct paging for a team
 
-To create a direct paging integration for a team, click **+ New alert group** on the **Alert groups** page, choose the team,
-and create an alert group, **regardless of any warnings**. This action automatically triggers Grafana OnCall to generate
-a [direct paging integration](#learn-the-flow-and-handle-warnings) for the chosen team. Alternatively, navigate to
-the **Integrations** page and create a new integration with type "Direct paging" from there, assigning it to the team.
+By default all teams will have a direct paging integration created for them. However, these are not configured by default.
+If a team does not have their direct paging integration configured, such that it is "contactable" (ie. it has an
+escalation chain assigned to it, or has at least one Chatops integration connected to send notifications to), you will
+not be able to direct page this team. If this happens, consider following the following steps for the team (or reach out
+to the relevant team and suggest doing so).
 
-After setting up the integration, you can customize its settings, link it to an escalation chain,
-and configure associated ChatOps channels.
-To confirm that the integration is functioning as intended, [create a new alert group](#page-a-team)
+Navigate to the **Integrations** page and find the "Direct paging" integration for the team in question. From the
+integration's detail page, you can customize its settings, link it to an escalation chain, and configure associated
+ChatOps channels. To confirm that the integration is functioning as intended, [create a new alert group](#page-a-team)
 and select the same team for a test run.
 
 {{% docs/reference %}}

docs/sources/open-source/_index.md

@@ -96,7 +96,7 @@ features:
       should_escape: false
     - command: /escalate
       url: <ONCALL_ENGINE_PUBLIC_URL>/slack/interactive_api_endpoint/
-      description: Direct page user(s) or schedule(s)
+      description: Direct page a team or user(s)
       should_escape: false
 oauth_config:
   redirect_urls:

engine/apps/alerts/models/alert_group.py

@@ -70,6 +70,16 @@ class LogRecordUser(typing.TypedDict):
     avatar_full: str
 
 
+class PagedUser(typing.TypedDict):
+    id: int
+    username: str
+    name: str
+    pk: str
+    avatar: str
+    avatar_full: str
+    important: bool
+
+
 class LogRecords(typing.TypedDict):
     time: str  # humanized delta relative to now
     action: str  # human-friendly description
@@ -509,22 +519,57 @@ def declare_incident_link(self) -> str:
     def happened_while_maintenance(self):
         return self.root_alert_group is not None and self.root_alert_group.maintenance_uuid is not None
 
-    def get_paged_users(self) -> QuerySet[User]:
+    def get_paged_users(self) -> typing.List[PagedUser]:
         from apps.alerts.models import AlertGroupLogRecord
 
-        users_ids = set()
-        for log_record in self.log_records.filter(
+        user_ids: typing.Set[str] = set()
+        users: typing.List[PagedUser] = []
+
+        log_records = self.log_records.filter(
             type__in=(AlertGroupLogRecord.TYPE_DIRECT_PAGING, AlertGroupLogRecord.TYPE_UNPAGE_USER)
-        ):
+        )
+
+        for log_record in log_records:
             # filter paging events, track still active escalations
             info = log_record.get_step_specific_info()
             user_id = info.get("user") if info else None
+            important = info.get("important") if info else None
+
             if user_id is not None:
-                users_ids.add(
+                user_ids.add(
                     user_id
-                ) if log_record.type == AlertGroupLogRecord.TYPE_DIRECT_PAGING else users_ids.discard(user_id)
+                ) if log_record.type == AlertGroupLogRecord.TYPE_DIRECT_PAGING else user_ids.discard(user_id)
+
+        user_instances = User.objects.filter(public_primary_key__in=user_ids)
+        user_map = {u.public_primary_key: u for u in user_instances}
 
-        return User.objects.filter(public_primary_key__in=users_ids)
+        # mostly doing this second loop to avoid having to query each user individually in the first loop
+        for log_record in log_records:
+            # filter paging events, track still active escalations
+            info = log_record.get_step_specific_info()
+            user_id = info.get("user") if info else None
+            important = info.get("important") if info else False
+
+            if user_id is not None and (user := user_map.get(user_id)) is not None:
+                if log_record.type == AlertGroupLogRecord.TYPE_DIRECT_PAGING:
+                    # add the user
+                    users.append(
+                        {
+                            "id": user.pk,
+                            "pk": user.public_primary_key,
+                            "name": user.name,
+                            "username": user.username,
+                            "avatar": user.avatar_url,
+                            "avatar_full": user.avatar_full_url,
+                            "important": important,
+                            "teams": [{"pk": t.public_primary_key, "name": t.name} for t in user.teams.all()],
+                        }
+                    )
+                else:
+                    # user was unpaged at some point, remove them
+                    users = [u for u in users if u["pk"] != user_id]
+
+        return users
 
     def _get_response_time(self):
         """Return response_time based on current alert group status."""

engine/apps/alerts/models/alert_receive_channel.py

@@ -245,6 +245,41 @@ def create(cls, **kwargs):
             channel.save()
         return channel
 
+    @classmethod
+    def get_orgs_direct_paging_integrations(
+        cls, organization: "Organization"
+    ) -> models.QuerySet["AlertReceiveChannel"]:
+        return cls.objects.filter(
+            organization=organization,
+            integration=AlertReceiveChannel.INTEGRATION_DIRECT_PAGING,
+        )
+
+    @property
+    def is_contactable(self) -> bool:
+        """
+        Returns true if:
+        - the integration has more than one channel filter associated with it
+        - the default channel filter has at least one notification method specified or an escalation chain associated with it
+        """
+        if self.channel_filters.count() > 1:
+            return True
+
+        default_channel_filter = self.default_channel_filter
+        if not default_channel_filter:
+            return False
+
+        notify_via_slack = self.organization.slack_is_configured and default_channel_filter.notify_in_slack
+        notify_via_telegram = self.organization.telegram_is_configured and default_channel_filter.notify_in_telegram
+
+        notify_via_chatops = notify_via_slack or notify_via_telegram
+        custom_messaging_backend_configured = default_channel_filter.notification_backends is not None
+
+        return (
+            default_channel_filter.escalation_chain is not None
+            or notify_via_chatops
+            or custom_messaging_backend_configured
+        )
+
     def delete(self):
         self.deleted_at = timezone.now()
         self.save()