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(version: str = 'v2')

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

Sends message about a given event to the given destinations

Loops over the destinations from cls.get_relevant_destinations and converts each destination to a medium-specific “address” via cls.get_relevant_address.

Returns a boolean: * True: everything ok * False: at least one destination failed

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(version: str = 'v2')

abstractmethod static get_label(destination: DestinationConfig) → str

Returns a descriptive label for this destination.

abstractmethod 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 cannot be deleted

Potential reasons:

• it is marked as “managed”, which means it is usable but read-only for end-users

• it is in use by at least one notification profile

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

Updates a destination

If the destination is marked as managed and the settings are being updated, a copy of the original will be made before changing the destination.

abstractmethod 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 managed by 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.

Writing destination plugins using Apprise

If one wishes to write a notification plugin for a medium supported by Apprise, see Apprise documentation: Supported services, a pre-made base class is provided that allows you to get started almost straight “out of the box”.

Class: argus.notificationprofile.media.base.AppriseMedium

A minimal example of how to use it can be found in:

Class: argus.notificationprofile.media.slack.SlackNotification

In this case as Apprise works with URLs, it can consume the destination webhook directly, so the notification class does not actually need anything.

Nevertheless, it is probably smart to set the constants to be less generic and provide an extension of the validate function using your desired MEDIA_SLUG.

Note that if you change the name of the core destination_url property, you will need to extend many more of the functions to use the new name.

The default destination_url field implementation only supports http / https URLs. To use custom schemes (like the generic service://configuration/?parameters in the Apprise docs), you need to create a custom subclass overriding the appropriate fields and functions.