Add constant MEDIA_SETTINGS_KEY to media

docs/integrations/notifications/writing-notification-plugins.rst

@@ -28,22 +28,37 @@ implement the following:
 Class constants
 ---------------
 
-You need to set the constants `MEDIA_SLUG`, `MEDIA_NAME` and
-`MEDIA_JSON_SCHEMA`.
-
-The media name is the name of the service you want to send notifications by.
-This is used only for display purposes so you might want to keep it short and
-sweet. So for example `Email`, `SMS` or `MS Teams`.
-
-The media slug is the slugified version of that, so the name simplified to only
-contain lowercase letters, numbers, underscores and hyphens. Always have it
-start with a letter, a-z. For example `email`, `sms` or `msteams`.
-
-The media `json schema <https://json-schema.org/>`_ is a representation of how
-a destination that will be used by this notification plugin should look like.
-Such a destination should include all necessary information that is needed to
-send notifications with your notification plugin. In case of SMS that is a
-phone number or for MS Teams a webhook.
+You need to set the constants ``MEDIA_SLUG``, ``MEDIA_NAME`` and
+``MEDIA_JSON_SCHEMA``. If your plugin only takes or needs a single
+configuration flag you should also set ``MEDIA_SETTINGS_KEY``.
+
+MEDIA_NAME
+   The media name is the name of the service you want to send notifications by.
+   This is used only for display purposes so you might want to keep it short
+   and sweet. So for example ``"Email"``, ``"SMS"`` or ``"MS Teams"``.
+
+MEDIA_SLUG
+   The media slug is the slugified version of that, so the name simplified to
+   only contain lowercase letters, numbers, underscores and hyphens. Always
+   have it start with a letter, a-z. For example ``"email"``, ``"sms"`` or
+   ``"msteams"``.
+
+MEDIA_JSON_SCHEMA
+   The media `json schema <https://json-schema.org/>`_ is a representation of
+   how a destination that will be used by this notification plugin should look
+   like, so that it is possible to autogenerate a form with JavaScript. It will
+   be accessible via the API. Such a destination should include all necessary
+   information that is needed to send notifications with your notification
+   plugin. In case of SMS that is a phone number or for MS Teams a webhook.
+
+MEDIA_SETTINGS_KEY
+   The media settings key is the name of the most important key in the settings
+   JSON field. It is used to cut down on the amount of code you need to write
+   if there is only one piece of config you need to send the notification.
+   Among other things, it is used to check for duplicate entries, so in a way
+   it acts as storage for the value of the primary key for a destination plugin. For that reason, it must be
+   required in the json schema. For example for an email plugin this would be
+   "email_address" or for a SMS plugin it would be "phone_number".
 
 Class methods for sending notifications
 ---------------------------------------

src/argus/notificationprofile/media/base.py

@@ -46,6 +46,23 @@ def modelinstance_to_dict(obj):
 
 
 class NotificationMedium(ABC):
+    """
+    Must be defined by subclasses:
+
+    Class attributes:
+
+    - MEDIA_SLUG: short string id for the medium, lowercase
+    - MEDIA_NAME: human friendly id for the medium
+    - MEDIA_SETTINGS_KEY: the field in settings that is specific for this medium
+    - MEDIA_JSON_SCHEMA: A json-schema to describe the settings field to
+      javascript, used by the API
+
+    Class methods:
+
+    - send(event, destinations): How to send the given event to the given
+      destinations of type MEDIA_SLUG.
+    """
+
     class NotDeletableError(Exception):
         """
         Custom exception class that is raised when a destination cannot be
@@ -192,12 +209,18 @@ def update(destination: DestinationConfig, validated_data: dict) -> DestinationC
 class AppriseMedium(NotificationMedium):
     MEDIA_SLUG = "apprise"
     MEDIA_NAME = "Apprise"
+    MEDIA_SETTINGS_KEY = "destination_url"
     MEDIA_JSON_SCHEMA = {
         "title": "Apprise Settings",
         "description": "Settings for a DestinationConfig using Apprise.",
         "type": "object",
-        "required": ["destination_url"],
-        "properties": {"destination_url": {"type": "string", "title": "Apprise destination url"}},
+        "required": [MEDIA_SETTINGS_KEY],
+        "properties": {
+            MEDIA_SETTINGS_KEY: {
+                "type": "string",
+                "title": "Apprise destination url",
+            }
+        },
     }
 
     class Form(forms.Form):

src/argus/notificationprofile/media/email.py

@@ -55,12 +55,18 @@ def send_email_safely(function, additional_error=None, *args, **kwargs) -> int:
 class EmailNotification(NotificationMedium):
     MEDIA_SLUG = "email"
     MEDIA_NAME = "Email"
+    MEDIA_SETTINGS_KEY = "email_address"
     MEDIA_JSON_SCHEMA = {
         "title": "Email Settings",
         "description": "Settings for a DestinationConfig using email.",
         "type": "object",
-        "required": ["email_address"],
-        "properties": {"email_address": {"type": "string", "title": "Email address"}},
+        "required": [MEDIA_SETTINGS_KEY],
+        "properties": {
+            MEDIA_SETTINGS_KEY: {
+                "type": "string",
+                "title": "Email address",
+            },
+        },
     }
 
     class FormV3(forms.Form):

src/argus/notificationprofile/media/sms_as_email.py

@@ -37,17 +37,18 @@
 class SMSNotification(NotificationMedium):
     MEDIA_SLUG = "sms"
     MEDIA_NAME = "SMS"
+    MEDIA_SETTINGS_KEY = "phone_number"
     MEDIA_JSON_SCHEMA = {
         "title": "SMS Settings",
         "description": "Settings for a DestinationConfig using SMS.",
         "type": "object",
-        "required": ["phone_number"],
+        "required": [MEDIA_SETTINGS_KEY],
         "properties": {
-            "phone_number": {
+            MEDIA_SETTINGS_KEY: {
                 "type": "string",
                 "title": "Phone number",
                 "description": "The phone number is validated and the country code needs to be given.",
-            }
+            },
         },
     }