Support prescribed labels (#3848)

# What this PR does

**Cleanup label typing:**
1. LabelParam -> two separate types LabekKey and LabelValue 
2. LabelData -> renamed to LabelPair. 
3. LabelKeyData -> renamed to LabelOption
Data is not giving any info about what this type represents. 
4. Remove LabelsData and LabelsKeysData types. They are just list of
types listed above and with new naming it feels obsolete.
5. ValueData removed. LabelPair is used instead.
6. Rework AlertGroupCustomLabel to use LabelKey type for key to make
type system more consistent. Name model type AlertGroupCustomLabel**DB**
and api type AlertGroupCustomLabel**API** to clearly distinguish them.

**Split update_labels_cache into two tasks** update_label_option_cache
and update_label_pairs_cache.
Original task was expecting array of LabelsData (now it's LabelPair) OR
one LabelKeyData ( now it's LabelOption). I believe having one function
with two sp different argument types makes it more complicated for
understanding.


**Make OnCall backend support prescribed labels**. OnCall will sync and
store "prescribed" field for key and values, so Label dropdown able to
disable editing for certain labels.

## Which issue(s) this PR fixes

## Checklist

- [x] Unit, integration, and e2e (if applicable) tests updated
- [ ] Documentation added (or `pr:no public docs` PR label added if not
required)
- [x] `CHANGELOG.md` updated (or `pr:no changelog` PR label added if not
required)

---------

Co-authored-by: Maxim Mordasov <[email protected]>
Co-authored-by: Yulya Artyukhina <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+– Support prescribed labels ([#3848](https://github.com/grafana/oncall/pull/3848))
 - Add status change trigger type to webhooks ([#3920](https://github.com/grafana/oncall/pull/3920))
 
 ### Fixed

engine/apps/alerts/models/alert.py

@@ -15,7 +15,7 @@
 from apps.alerts.signals import alert_group_escalation_snapshot_built
 from apps.alerts.tasks.distribute_alert import send_alert_create_signal
 from apps.labels.alert_group_labels import assign_labels, gather_labels_from_alert_receive_channel_and_raw_request_data
-from apps.labels.types import Labels
+from apps.labels.types import AlertLabels
 from common.jinja_templater import apply_jinja_template_to_alert_payload_and_labels
 from common.jinja_templater.apply_jinja_template import (
     JinjaTemplateError,
@@ -221,7 +221,7 @@ def _apply_jinja_template_to_alert_payload_and_labels(
         template_name: str,
         alert_receive_channel: "AlertReceiveChannel",
         raw_request_data: RawRequestData,
-        labels: typing.Optional[Labels],
+        labels: typing.Optional[AlertLabels],
         use_error_msg_as_fallback=False,
         check_if_templated_value_is_truthy=False,
     ) -> typing.Union[str, None, bool]:
@@ -246,7 +246,7 @@ def render_group_data(
         cls,
         alert_receive_channel: "AlertReceiveChannel",
         raw_request_data: RawRequestData,
-        labels: typing.Optional[Labels],
+        labels: typing.Optional[AlertLabels],
         is_demo=False,
     ) -> "AlertGroup.GroupData":
         from apps.alerts.models import AlertGroup

engine/apps/alerts/models/alert_receive_channel.py

@@ -294,8 +294,8 @@ class AlertReceiveChannel(IntegrationOptionsMixin, MaintainableObject):
     rate_limited_in_slack_at = models.DateTimeField(null=True, default=None)
     rate_limit_message_task_id = models.CharField(max_length=100, null=True, default=None)
 
-    AlertGroupCustomLabels = list[tuple[str, str | None, str | None]] | None
-    alert_group_labels_custom: AlertGroupCustomLabels = models.JSONField(null=True, default=None)
+    AlertGroupCustomLabelsDB = list[tuple[str, str | None, str | None]] | None
+    alert_group_labels_custom: AlertGroupCustomLabelsDB = models.JSONField(null=True, default=None)
     """
     Stores "custom labels" for alert group labels. Custom labels can be either "plain" or "templated".
     For plain labels, the format is: [<LABEL_KEY_ID>, <LABEL_VALUE_ID>, None]

engine/apps/alerts/models/channel_filter.py

@@ -20,7 +20,7 @@
     from django.db.models.manager import RelatedManager
 
     from apps.alerts.models import Alert, AlertGroup, AlertReceiveChannel
-    from apps.labels.types import Labels
+    from apps.labels.types import AlertLabels
 
 logger = logging.getLogger(__name__)
 
@@ -120,12 +120,12 @@ def select_filter(
         return None
 
     def is_satisfying(
-        self, raw_request_data: "Alert.RawRequestData", alert_labels: typing.Optional["Labels"] = None
+        self, raw_request_data: "Alert.RawRequestData", alert_labels: typing.Optional["AlertLabels"] = None
     ) -> bool:
         return self.is_default or self.check_filter(raw_request_data, alert_labels)
 
     def check_filter(
-        self, raw_request_data: "Alert.RawRequestData", alert_labels: typing.Optional["Labels"] = None
+        self, raw_request_data: "Alert.RawRequestData", alert_labels: typing.Optional["AlertLabels"] = None
     ) -> bool:
         if self.filtering_term_type == ChannelFilter.FILTERING_TERM_TYPE_JINJA2:
             try:

engine/apps/api/serializers/alert_receive_channel.py

@@ -15,6 +15,7 @@
 from apps.base.messaging import get_messaging_backends
 from apps.integrations.legacy_prefix import has_legacy_prefix
 from apps.labels.models import LabelKeyCache, LabelValueCache
+from apps.labels.types import LabelKey
 from apps.user_management.models import Organization
 from common.api_helpers.custom_fields import TeamPrimaryKeyRelatedField
 from common.api_helpers.exceptions import BadRequest
@@ -25,41 +26,45 @@
 from .labels import LabelsSerializerMixin
 
 
-class AlertGroupCustomLabelKey(typing.TypedDict):
-    id: str
-    name: str
-
-
-class AlertGroupCustomLabelValue(typing.TypedDict):
+# AlertGroupCustomLabelValue represents custom alert group label value for API requests
+# It handles two types of label's value:
+# 1. Just Label Value from a label repo for a static label
+# 2. Templated Label value which is actually a jinja template for a dynamic label.
+class AlertGroupCustomLabelValueAPI(typing.TypedDict):
     id: str | None  # None for templated labels, label value ID for plain labels
     name: str  # Jinja template for templated labels, label value name for plain labels
+    prescribed: bool  # Indicates of selected label value is prescribed. Not applicable for templated values.
 
 
-class AlertGroupCustomLabel(typing.TypedDict):
-    key: AlertGroupCustomLabelKey
-    value: AlertGroupCustomLabelValue
+# AlertGroupCustomLabel represents Alert group custom label for API requests
+# Key is just a LabelKey from label repo, while value could be value from repo or a jinja template.
+class AlertGroupCustomLabelAPI(typing.TypedDict):
+    key: LabelKey
+    value: AlertGroupCustomLabelValueAPI
 
 
-AlertGroupCustomLabels = list[AlertGroupCustomLabel]
+AlertGroupCustomLabelsAPI = list[AlertGroupCustomLabelAPI]
 
 
 class IntegrationAlertGroupLabels(typing.TypedDict):
     inheritable: dict[str, bool]
-    custom: AlertGroupCustomLabels
+    custom: AlertGroupCustomLabelsAPI
     template: str | None
 
 
 class CustomLabelSerializer(serializers.Serializer):
-    """This serializer is consistent with apps.api.serializers.labels.LabelSerializer, but allows null for value ID."""
+    """This serializer is consistent with apps.api.serializers.labels.LabelPairSerializer, but allows null for value ID."""
 
     class CustomLabelKeySerializer(serializers.Serializer):
         id = serializers.CharField()
         name = serializers.CharField()
+        prescribed = serializers.BooleanField(default=False)
 
     class CustomLabelValueSerializer(serializers.Serializer):
         # ID is null for templated labels. For such labels, the "name" value is a Jinja2 template.
         id = serializers.CharField(allow_null=True)
         name = serializers.CharField()
+        prescribed = serializers.BooleanField(default=False)
 
     key = CustomLabelKeySerializer()
     value = CustomLabelValueSerializer()
@@ -112,16 +117,26 @@ def update(
         return instance
 
     @staticmethod
-    def _create_custom_labels(organization: Organization, labels: AlertGroupCustomLabels) -> None:
+    def _create_custom_labels(organization: Organization, labels: AlertGroupCustomLabelsAPI) -> None:
         """Create LabelKeyCache and LabelValueCache objects for custom labels."""
 
         label_keys = [
-            LabelKeyCache(id=label["key"]["id"], name=label["key"]["name"], organization=organization)
+            LabelKeyCache(
+                id=label["key"]["id"],
+                name=label["key"]["name"],
+                prescribed=label["key"]["prescribed"],
+                organization=organization,
+            )
             for label in labels
         ]
 
         label_values = [
-            LabelValueCache(id=label["value"]["id"], name=label["value"]["name"], key_id=label["key"]["id"])
+            LabelValueCache(
+                id=label["value"]["id"],
+                name=label["value"]["name"],
+                prescribed=label["value"]["prescribed"],
+                key_id=label["key"]["id"],
+            )
             for label in labels
             if label["value"]["id"]  # don't create LabelValueCache objects for templated labels
         ]
@@ -147,8 +162,8 @@ def to_representation(cls, instance: AlertReceiveChannel) -> IntegrationAlertGro
 
     @staticmethod
     def _custom_labels_to_internal_value(
-        custom_labels: AlertGroupCustomLabels,
-    ) -> AlertReceiveChannel.AlertGroupCustomLabels:
+        custom_labels: AlertGroupCustomLabelsAPI,
+    ) -> AlertReceiveChannel.AlertGroupCustomLabelsDB:
         """Convert custom labels from API representation to the schema used by the JSONField on the model."""
 
         return [
@@ -158,8 +173,8 @@ def _custom_labels_to_internal_value(
 
     @staticmethod
     def _custom_labels_to_representation(
-        custom_labels: AlertReceiveChannel.AlertGroupCustomLabels,
-    ) -> AlertGroupCustomLabels:
+        custom_labels: AlertReceiveChannel.AlertGroupCustomLabelsDB,
+    ) -> AlertGroupCustomLabelsAPI:
         """
         Inverse of the _custom_labels_to_internal_value method above.
         Fetches label names from DB cache, so the API response schema is consistent with other label endpoints.
@@ -170,33 +185,37 @@ def _custom_labels_to_representation(
         if custom_labels is None:
             return []
 
-        # get up-to-date label key names
-        label_key_names = {
-            k.id: k.name
-            for k in LabelKeyCache.objects.filter(id__in=[label[0] for label in custom_labels]).only("id", "name")
+        # build index of keys id to name and prescribed flag
+        label_key_index = {
+            k.id: {"name": k.name, "prescribed": k.prescribed}
+            for k in LabelKeyCache.objects.filter(id__in=[label[0] for label in custom_labels]).only(
+                "id", "name", "prescribed"
+            )
         }
 
-        # get up-to-date label value names
-        label_value_names = {
-            v.id: v.name
+        # build index of values id to name and prescribed flag
+        label_value_index = {
+            v.id: {"name": v.name, "prescribed": v.prescribed}
             for v in LabelValueCache.objects.filter(id__in=[label[1] for label in custom_labels if label[1]]).only(
-                "id", "name"
+                "id", "name", "prescribed"
             )
         }
 
         return [
             {
                 "key": {
                     "id": key_id,
-                    "name": label_key_names[key_id],
+                    "name": label_key_index[key_id]["name"],
+                    "prescribed": label_key_index[key_id]["prescribed"],
                 },
                 "value": {
                     "id": value_id if value_id else None,
-                    "name": label_value_names[value_id] if value_id else typing.cast(str, template),
+                    "name": label_value_index[value_id]["name"] if value_id else typing.cast(str, template),
+                    "prescribed": label_value_index[value_id]["prescribed"] if value_id else False,
                 },
             }
             for key_id, value_id, template in custom_labels
-            if key_id in label_key_names and (value_id in label_value_names or not value_id)
+            if key_id in label_key_index and (value_id in label_value_index or not value_id)
         ]
 
 

engine/apps/api/serializers/labels.py

@@ -6,32 +6,36 @@
 
 class LabelKeySerializer(serializers.ModelSerializer):
     id = serializers.CharField()
+    prescribed = serializers.BooleanField(default=False)
 
     class Meta:
         model = LabelKeyCache
         fields = (
             "id",
             "name",
+            "prescribed",
         )
 
 
 class LabelValueSerializer(serializers.ModelSerializer):
     id = serializers.CharField()
+    prescribed = serializers.BooleanField(default=False)
 
     class Meta:
         model = LabelValueCache
         fields = (
             "id",
             "name",
+            "prescribed",
         )
 
 
-class LabelSerializer(serializers.Serializer):
+class LabelPairSerializer(serializers.Serializer):
     key = LabelKeySerializer()
     value = LabelValueSerializer()
 
 
-class LabelKeyValuesSerializer(serializers.Serializer):
+class LabelOptionSerializer(serializers.Serializer):
     key = LabelKeySerializer()
     values = LabelValueSerializer(many=True)
 
@@ -41,7 +45,7 @@ class LabelReprSerializer(serializers.Serializer):
 
 
 class LabelsSerializerMixin(serializers.Serializer):
-    labels = LabelSerializer(many=True, required=False)
+    labels = LabelPairSerializer(many=True, required=False)
 
     def validate_labels(self, labels):
         if labels: