openwisp-notifications 1.0

Additional notify keyword arguments

Notification Widget

A javascript widget has been added to make consuming notifications easy for users. The notification widget provides following features:

• A minimalistic UI to help getting things done quickly.

• Dynamically loading notifications with infinite scrolling to prevent unnecessary network requests.

• Option to filter unread notifications.

• Option to mark all notifications as read on a single click.

Notification Toasts

A notification toast delivers notifications at real-time. This allows users to read notifications without even opening the notification widget. A notification bell is also played to alert each time a notification is displayed through notification toast.

Cache invalidation

The function register_notification_cache_update can be used to register a signal of a model which is being used as an actor, action_object and target objects. As these values are cached for the optimization purpose so their cached values are need to be changed when they are changed. You can register any signal you want which will delete the cached value. To register a signal you need to include following code in your apps.py.

from django.db.models.signals import post_save
from swapper import load_model

def ready(self):
    super().ready()

    # Include lines after this inside
    # ready function of you app config class
    from openwisp_notifications.handlers import register_notification_cache_update

    model = load_model('app_name', 'model_name')
    register_notification_cache_update(model, post_save, dispatch_uid="myapp_mymodel_notification_cache_invalidation")

Note: You need to import register_notification_cache_update inside the ready function or you can define another funtion to register signals which will be called in ready and then it will be imported in this function. Also dispatch_uid is unique identifier of a signal. You can pass any value you want but it needs to be unique. For more details read preventing duplicate signals section of Django documentation

Defining message_template

You can either extend default message template or write your own markdown formatted message template from scratch. An example to extend default message template is shown below.

# In templates/your_notifications/your_message_template.md
{% extends 'openwisp_notifications/default_message.md' %}
{% block body %}
    [{{ notification.target }}]({{ notification.target_link }}) has malfunctioned.
{% endblock body %}

Note: You can access all attributes of the notification using notification variables in your message template as shown above. Additional attributes actor_link, action_link and target_link are also available for providing hyperlinks to respective object.

Note: After writing code for registering or unregistering notification types, it is recommended to run database migrations to create notification settlings for these notification types.

register_notification_type

This function is used to register a new notification type from your code.

Syntax:

register_notification_type(type_name, type_config, models)

An example usage has been shown below.

from openwisp_notifications.types import register_notification_type
from django.contrib.auth import get_user_model

User = get_user_model()

# Define configuration of your notification type
custom_type = {
    'level': 'info',
    'verb': 'added',
    'verbose_name': 'device added',
    'message': '[{notification.target}]({notification.target_link}) was {notification.verb} at {notification.timestamp}',
    'email_subject' : '[{site.name}] A device has been added',
    'web_notification': True,
    'email_notification': True,
}

# Register your custom notification type
register_notification_type('custom_type', custom_type, models=[User])

Note: It will raise ImproperlyConfigured exception if a notification type is already registered with same name(not to be confused with verbose_name).

Note: You can use site and notification variables while defining message and email_subject configuration of notification type. They refer to objects of django.contrib.sites.models.Site and openwisp_notifications.models.Notification respectively. This allows you to use any of their attributes in your configuration. Similarly to message_template, message property can also be formatted using markdown.

unregister_notification_type

This function is used to unregister a notification type from anywhere in your code.

Syntax:

unregister_notification_type(type_name)

An example usage is shown below.

from openwisp_notifications.types import unregister_notification_type

# Unregister previously registered notification type
unregister_notification_type('custom type')

Note: It will raise ImproperlyConfigured exception if the concerned notification type is not registered.

Passing extra data to notifications

If needed, additional data, not known beforehand, can be included in the notification message.

A perfect example for this case is an error notification, the error message will vary depending on what has happened, so we cannot know until the notification is generated.

Here’s how to do it:

from openwisp_notifications.types import register_notification_type

register_notification_type('error_type', {
    'verbose_name': 'Error',
    'level': 'error',
    'verb': 'error',
    'message': 'Error: {error}',
    'email_subject': 'Error subject: {error}',
})

Then in the application code:

from openwisp_notifications.signals import notify

try:
    operation_which_can_fail()
except Exception as error:
    notify.send(
        type='error_type',
        sender=sender,
        error=str(error)
    )

Note: It is recommended that all notification types are registered or unregistered in ready method of your Django application’s AppConfig.

Deleting Notification Preferences

Deleting the notification preferences is an advanced option. Users should turn off web and email notifications instead of deleting notification preferences. Deleted notification preferences may be re-created automatically if the system needs it.

OPENWISP_NOTIFICATIONS_HOST

This setting defines the domain at which API and Web Socket communicate for working of notification widget.

Note: You don’t need to configure this setting if you don’t host your API endpoints on a different sub-domain.

If your root domain is example.com and API and Web Socket are hosted at api.example.com, then configure setting as follows:

OPENWISP_NOTIFICATIONS_HOST = 'https://api.example.com'

This feature requires you to allow CORS on your server. We use django-cors-headers module to easily setup CORS headers. Please refer django-core-headers’ setup documentation.

Configure django-cors-headers settings as follows:

CORS_ALLOW_CREDENTIALS = True
CORS_ORIGIN_WHITELIST = ['https://www.example.com']

Configure Django’s settings as follows:

SESSION_COOKIE_DOMAIN = 'example.com'
CSRF_COOKIE_DOMAIN = 'example.com'

Please refer to Django’s settings documentation for more information on SESSION_COOKIE_DOMAIN and CSRF_COOKIE_DOMAIN settings.

OPENWISP_NOTIFICATIONS_SOUND

This setting defines notification sound to be played when notification is received in real-time on admin site.

Provide an absolute or relative path(hosted on your webserver) to audio file as show below.

OPENWISP_NOTIFICATIONS_SOUND = '/static/your-appname/audio/notification.mp3'

OPENWISP_NOTIFICATIONS_CACHE_TIMEOUT

It sets the number of seconds the notification contents should be stored in the cache. If you want cached notification content to never expire, then set it to None. Set it to 0 if you don’t want to store notification contents in cache at all.

OPENWISP_NOTIFICATIONS_IGNORE_ENABLED_ADMIN

This setting enables the widget which allows users to silence notifications for specific objects temporarily or permanently. in the change page of the specified ModelAdmin classes.

E.g., if you want to enable the widget for objects of openwisp_users.models.User model, then configure the setting as following:

OPENWISP_NOTIFICATIONS_IGNORE_ENABLED_ADMIN = ['openwisp_users.admin.UserAdmin']

OPENWISP_NOTIFICATIONS_POPULATE_PREFERENCES_ON_MIGRATE

This setting allows to disable creating notification preferences on running migrations.

OPENWISP_NOTIFICATIONS_NOTIFICATION_STORM_PREVENTION

When the system starts creating a lot of notifications because of a general network outage (e.g.: a power outage, a global misconfiguration), the notification storm prevention mechanism avoids the constant displaying of new notification alerts as well as their sound, only the notification counter will continue updating periodically, although it won’t emit any sound or create any other visual element until the notification storm is over.

This setting allows tweaking how this mechanism works.

The default configuration is as follows:

OPENWISP_NOTIFICATIONS_NOTIFICATION_STORM_PREVENTION = {
    # Time period for tracking burst of notifications (in seconds)
    'short_term_time_period': 10,
    # Number of notifications considered as a notification burst
    'short_term_notification_count': 6,
    # Time period for tracking notifications in long time interval (in seconds)
    'long_term_time_period': 180,
    # Number of notifications in long time interval to be considered as a notification storm
    'long_term_notification_count': 30,
    # Initial time for which notification updates should be skipped (in seconds)
    'initial_backoff': 1,
    # Time by which skipping of notification updates should be increased (in seconds)
    'backoff_increment': 1,
    # Maximum interval after which the notification widget should get updated (in seconds)
    'max_allowed_backoff': 15,
}

Live documentation

A general live API documentation (following the OpenAPI specification) is available at /api/v1/docs/.

Browsable web interface

Additionally, opening any of the endpoints listed below directly in the browser will show the browsable API interface of Django-REST-Framework, which makes it even easier to find out the details of each endpoint.

Authentication

See openwisp-users: authenticating with the user token.

When browsing the API via the Live documentation or the Browsable web interface, you can use the session authentication by logging in the django admin.

Pagination

The list endpoint support the page_size parameter that allows paginating the results in conjunction with the page parameter.

GET /api/v1/notifications/notification/?page_size=10
GET /api/v1/notifications/notification/?page_size=10&page=2

List of endpoints

Since the detailed explanation is contained in the Live documentation and in the Browsable web page of each endpoint, here we’ll provide just a list of the available endpoints, for further information please open the URL of the endpoint in your browser.

GET /api/v1/notifications/notification/

POST /api/v1/notifications/notification/read/

GET /api/v1/notifications/notification/{pk}/

PATCH /api/v1/notifications/notification/{pk}/

DELETE /api/v1/notifications/notification/{pk}/

GET /api/v1/notifications/notification/user-setting/

GET /api/v1/notifications/notification/user-setting/{pk}/

PATCH /api/v1/notifications/notification/user-setting/{pk}/

GET /api/v1/notifications/notification/ignore/

GET /api/v1/notifications/notification/ignore/{app_label}/{model_name}/{object_id}/

PUT /api/v1/notifications/notification/ignore/{app_label}/{model_name}/{object_id}/

DELETE /api/v1/notifications/notification/ignore/{app_label}/{model_name}/{object_id}/

populate_notification_preferences

This command will populate notification preferences for all users for organizations they are member of.

Example usage:

# cd tests/
./manage.py populate_notification_preferences

Note: Before running this command make sure that the celery broker is running and reachable by celery workers.

create_notification

This command will create a dummy notification with default notification type for the members of default organization. This command is primarily provided for the sole purpose of testing notification in development only.

Example usage:

# cd tests/
./manage.py create_notification

1. Initialize your custom module

The first thing you need to do in order to extend openwisp-notifications is create a new django app which will contain your custom version of that openwisp-notifications app.

A django app is nothing more than a python package (a directory of python scripts), in the following examples we’ll call this django app as mynotifications but you can name it how you want:

django-admin startapp mynotifications

Keep in mind that the command mentioned above must be called from a directory which is available in your PYTHON_PATH so that you can then import the result into your project.

Now you need to add mynotifications to INSTALLED_APPS in your settings.py, ensuring also that openwisp_notifications has been removed:

INSTALLED_APPS = [
    # ... other apps ...
    # 'openwisp_notifications',        <-- comment out or delete this line
    'mynotifications',
]

For more information about how to work with django projects and django apps, please refer to the django documentation.

2. Install openwisp-notifications

Install (and add to the requirement of your project) openwisp-notifications:

pip install -U https://github.com/openwisp/openwisp-notifications/tarball/master

3. Add EXTENDED_APPS

Add the following to your settings.py:

EXTENDED_APPS = ['openwisp_notifications']

4. Add openwisp_utils.staticfiles.DependencyFinder

Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS in your settings.py:

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

5. Add openwisp_utils.loaders.DependencyLoader

Add openwisp_utils.loaders.DependencyLoader to TEMPLATES in your settings.py:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
                'openwisp_utils.loaders.DependencyLoader',
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    }
]

6. Inherit the AppConfig class

Please refer to the following files in the sample app of the test project:

• sample_notifications/__init__.py.

• sample_notifications/apps.py.

For more information regarding the concept of AppConfig please refer to the “Applications” section in the django documentation.

7. Create your custom models

For the purpose of showing an example, we added a simple “details” field to the models of the sample app in the test project.

You can add fields in a similar way in your models.py file.

Note: For doubts regarding how to use, extend or develop models please refer to the “Models” section in the django documentation.

8. Add swapper configurations

Add the following to your settings.py:

# Setting models for swapper module
OPENWISP_NOTIFICATIONS_NOTIFICATION_MODEL = 'mynotifications.Notification'
OPENWISP_NOTIFICATIONS_NOTIFICATIONSETTING_MODEL = 'mynotifications.NotificationSetting'
OPENWISP_NOTIFICATIONS_IGNOREOBJECTNOTIFICATION_MODEL = 'mynotifications.IgnoreObjectNotification'

9. Create database migrations

Create and apply database migrations:

./manage.py makemigrations
./manage.py migrate

For more information, refer to the “Migrations” section in the django documentation.

10. Create your custom admin

Refer to the admin.py file of the sample app.

To introduce changes to the admin, you can do it in two main ways which are described below.

Note: For more information regarding how the django admin works, or how it can be customized, please refer to “The django admin site” section in the django documentation.

from openwisp_notifications.admin import NotificationSettingInline

NotificationSettingInline.list_display.insert(1, 'my_custom_field')
NotificationSettingInline.ordering = ['-my_custom_field']

from django.contrib import admin
from openwisp_notifications.admin import (
    NotificationSettingInline as BaseNotificationSettingInline,
)
from openwisp_notifications.swapper import load_model

NotificationSetting = load_model('NotificationSetting')

admin.site.unregister(NotificationSettingAdmin)
admin.site.unregister(NotificationSettingInline)


@admin.register(NotificationSetting)
class NotificationSettingInline(BaseNotificationSettingInline):
    # add your changes here
    pass

11. Create root URL configuration

Please refer to the urls.py file in the test project.

For more information about URL configuration in django, please refer to the “URL dispatcher” section in the django documentation.

12. Create root routing configuration

Please refer to the routing.py file in the test project.

For more information about URL configuration in django, please refer to the “Routing” section in the Channels documentation.

13. Create celery.py

Please refer to the celery.py file in the test project.

For more information about the usage of celery in django, please refer to the “First steps with Django” section in the celery documentation.

14. Import Celery Tasks

Add the following in your settings.py to import celery tasks from openwisp_notifications app.

CELERY_IMPORTS = ('openwisp_notifications.tasks',)

15. Register Template Tags

If you need to use template tags of openwisp_notifications, you will need to register as shown in “templatetags/notification_tags.py” of sample_notifications.

For more information about template tags in django, please refer to the “Custom template tags and filters” section in the django documentation.

16. Register Notification Types

You can register notification types as shown in the section for registering notification types.

A reference for registering a notification type is also provided in sample_notifications/apps.py. The registered notification type of sample_notifications app is used for creating notifications when an object of TestApp model is created. You can use sample_notifications/models.py as reference for your implementation.

17. Import the automated tests

When developing a custom application based on this module, it’s a good idea to import and run the base tests too, so that you can be sure the changes you’re introducing are not breaking some of the existing feature of openwisp-notifications.

In case you need to add breaking changes, you can overwrite the tests defined in the base classes to test your own behavior.

See the tests of the sample_notifications to find out how to do this.

Note: Some tests will fail if templatetags and admin/base.html are not configured properly. See preceeding sections to configure them properly.

Other base classes that can be inherited and extended

The following steps are not required and are intended for more advanced customization.

Icons

Icons used are taken from Font Awesome project.

LICENSE: https://fontawesome.com/license

Sound

Notification sound is taken from Notification Sounds.

LICENSE: Creative Commons Attribution license