Writing your own notification plugin

When writing a new notification plugin the plugins for SMS-as-Email and Teams can be used as guides.

To create a project for a new plugin easily it is recommended to use the Argus Notification Cookiecutter Template.

If a Python library that speaks the protocol of the medium already exists, we recommend that you use it. This helps keep the plugin itself short and simple. Just remember to add the library as a dependency in the pyproject.toml.

Note

Do not forget to add the path to your new notification plugin to the setting MEDIA_PLUGINS to be able to use it.

Also let us know about your notification plugin so that we can link your notification plugin and can add it to the frontend.

The plugin class inherits from the class NotificationMedium and needs to 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 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.

Class methods for sending notifications

class argus.notificationprofile.media.base.NotificationMedium

abstract classmethod send(event: Event, destinations: Iterable[DestinationConfig], **kwargs) → bool

Sends message about a given event to the given destinations

The send method is the method that does the actual sending of the notification. It gets the Argus event and a list of destinations as input and returns a boolean indicating if the sending was successful.

It is recommended to first filter the given QuerySet of destinations to only include destinations of the appropriate medium.

The rest is very dependent on the notification medium and, if used, the Python library. The given event can be used to extract relevant information that should be included in the message that will be sent to each destination.

Class methods for destinations

class argus.notificationprofile.media.base.NotificationMedium

abstract static get_label(destination: DestinationConfig) → str

Returns a descriptive label for this destination.

abstract classmethod has_duplicate(queryset: QuerySet, settings: dict) → bool

Returns True if a destination with the given settings already exists in the given queryset

classmethod raise_if_not_deletable(destination: DestinationConfig) → NoneType

Raises a NotDeletableError if the given destination is not able to be deleted (if it is in use by any notification profiles)

static update(destination: DestinationConfig, validated_data: dict) → DestinationConfig | NoneType

Updates a destination in case the normal update function is not sufficient and returns the updated destination in that case, returns None otherwise

abstract classmethod validate(instance: RequestDestinationConfigSerializer, dict: dict, user: User) → dict

Validates the settings of destination and returns a dict with validated and cleaned data

Your implementation of get_label should show a reasonable representation for a destination of that type that makes it easy to identify. For SMS that would simply be the phone number.

The method has_duplicate will receive a QuerySet of destinations and a dict of settings for a possible destination and should return True if a destination with such settings exists in the given QuerySet.

raise_if_not_deletable should check if a given destination can be deleted. This is used in case some destinations are synced from an outside source and should not be able to be deleted by a user. If that is the case a NotDeletableError should be raised. If not simply return None.

The method update only has to be implemented if the regular update method of Django isn’t sufficient. This can be the case if additional settings need to be updated.

Finally the function validate makes sure that a destination with the given settings can be updated or created. The function has_duplicate can be used here to ensure that not two destinations with the same settings will be created. Additionally the settings themselves should also be validated. For example for SMS the given phone number will be checked. Django forms can be helpful for validation. A ValidationError should be raised if the given settings are invalid and the validated and cleaned data should be returned if not.