Support prescribed labels

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+– Support prescribed labels ([#3848](https://github.com/grafana/oncall/pull/3848))
+
 ### Fixed
 
 - Quotes in templates not rendering results correctly ([#3884](https://github.com/grafana/oncall/pull/3884))

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(required=False, 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(required=False, 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, required=False)
 
     class Meta:
         model = LabelKeyCache
         fields = (
             "id",
             "name",
+            "prescribed",
         )
 
 
 class LabelValueSerializer(serializers.ModelSerializer):
     id = serializers.CharField()
+    prescribed = serializers.BooleanField(default=False, required=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:

engine/apps/api/tests/test_alert_receive_channel.py

@@ -1407,6 +1407,59 @@ def test_update_alert_receive_channel_labels(
     assert alert_receive_channel.labels.count() == 0
 
 
+@pytest.mark.django_db
+def test_update_alert_receive_channel_presribed_labels(
+    make_organization_and_user_with_plugin_token,
+    make_alert_receive_channel,
+    make_user_auth_headers,
+):
+    organization, user, token = make_organization_and_user_with_plugin_token()
+    alert_receive_channel = make_alert_receive_channel(organization)
+    client = APIClient()
+
+    url = reverse("api-internal:alert_receive_channel-detail", kwargs={"pk": alert_receive_channel.public_primary_key})
+    key_id = "testkey"
+    value_id = "testvalue"
+    data = {
+        "labels": [
+            {
+                "key": {"id": key_id, "name": "test", "prescribed": True},
+                "value": {"id": value_id, "name": "testv", "prescribed": True},
+            }
+        ]
+    }
+    response = client.patch(
+        url,
+        data=json.dumps(data),
+        content_type="application/json",
+        **make_user_auth_headers(user, token),
+    )
+
+    alert_receive_channel.refresh_from_db()
+
+    assert response.status_code == status.HTTP_200_OK
+    assert alert_receive_channel.labels.count() == 1
+    label = alert_receive_channel.labels.first()
+    assert label.key_id == key_id
+    assert label.value_id == value_id
+
+    # Check if cached labels are prescribed
+    assert label.key.prescribed is True
+    assert label.value.prescribed is True
+
+    response = client.patch(
+        url,
+        data=json.dumps({"labels": []}),
+        content_type="application/json",
+        **make_user_auth_headers(user, token),
+    )
+
+    alert_receive_channel.refresh_from_db()
+
+    assert response.status_code == status.HTTP_200_OK
+    assert alert_receive_channel.labels.count() == 0
+
+
 @pytest.mark.django_db
 def test_update_alert_receive_channel_labels_duplicate_key(
     make_organization_and_user_with_plugin_token,
@@ -1576,7 +1629,12 @@ def test_alert_group_labels_post(alert_receive_channel_internal_api_setup, make_
     labels = [{"key": {"id": "test", "name": "test"}, "value": {"id": "123", "name": "123"}}]
     alert_group_labels = {
         "inheritable": {"test": False},
-        "custom": [{"key": {"id": "test", "name": "test"}, "value": {"id": "123", "name": "123"}}],
+        "custom": [
+            {
+                "key": {"id": "test", "name": "test", "prescribed": False},
+                "value": {"id": "123", "name": "123", "prescribed": False},
+            }
+        ],
         "template": "{{ payload.labels | tojson }}",
     }
     data = {

engine/apps/api/tests/test_labels.py

@@ -37,15 +37,15 @@ def test_labels_get_keys(
 
 
 @patch(
-    "apps.labels.client.LabelsAPIClient.get_values",
+    "apps.labels.client.LabelsAPIClient.get_label_by_key_id",
     return_value=(
         {"key": {"id": "keyid123", "name": "team"}, "values": [{"id": "valueid123", "name": "yolo"}]},
         MockResponse(status_code=200),
     ),
 )
 @pytest.mark.django_db
 def test_get_update_key_get(
-    mocked_get_values,
+    mocked_get_label_by_key_id,
     make_organization_and_user_with_plugin_token,
     make_user_auth_headers,
 ):
@@ -55,7 +55,7 @@ def test_get_update_key_get(
     response = client.get(url, format="json", **make_user_auth_headers(user, token))
     expected_result = {"key": {"id": "keyid123", "name": "team"}, "values": [{"id": "valueid123", "name": "yolo"}]}
 
-    assert mocked_get_values.called
+    assert mocked_get_label_by_key_id.called
     assert response.status_code == status.HTTP_200_OK
     assert response.json() == expected_result