Quickstart

Installation

Pre-requisites

  • Python 3.7 or higher

  • Setuptools 30.3.0 or higher

  • Only the PostgreSQL database is supported

  • Working Celery 5.0 or higher setup and deploy at least one worker

Install from PyPI

Install from PyPI with pip:

pip install notifications-api-common

This library ships with support for notifications, in the form of view(set) mixins and some simple configuration data models.

Installation

Add the following apps

...,
"rest_framework",
"solo",
"simple_certmanager",
"zgw_consumers",
"notifications_api_common",
...

to your INSTALLED_APPS setting.

Three additional settings are available:

  • NOTIFICATIONS_DISABLED: a boolean, default False. Set to True to completely disable the sending of notifications.

  • NOTIFICATIONS_GUARANTEE_DELIVERY: a boolean, default True. Set to False to not raise a RuntimeError when the Notifications API is unconfigured.

  • IS_HTTPS: a boolean, default True. Set to False to indicate that no HTTPS is being used.

  • NOTIFICATIONS_API_GET_DOMAIN: a string, default notifications_api_common.utils.get_site_domain. You can set a different dot path to specify which method should be used to get the domain.

Make sure to migrate your database:

python manage.py migrate

Configuration

In the admin interface, open the notifications configuration and create a Service for the NC to use.

Make sure you also have the SITE_DOMAIN setting set up correctly, as the domain configured there is used to build the documentation URL.

After entering the configuration, you can register your channels - this action is idempotent:

python manage.py register_kanalen

Usage in code

Define at least one Kanaal instance, typically this would go in api/kanalen.py:

from zrc.datamodel.models import Zaak

from notifications_api_common.kanalen import Kanaal

ZAKEN = Kanaal(
    "zaken",  # label of the channel/exchange
    main_resource=Zaak,  # main object for this channel/exchange
    kenmerken=(  # fields to include as 'kenmerken'
        "bronorganisatie",
        "zaaktype",
        "vertrouwelijkheidaanduiding"
    )
)

To send notifications, add the mixins to the viewsets:

  • notifications_api_common.viewsets.NotificationCreateMixin: send notifications for newly created objects

  • notifications_api_common.viewsets.NotificationUpdateMixin: send notifications for (partial) upates to objects

  • notifications_api_common.viewsets.NotificationDestroyMixin: send notifications for destroyed objects

  • notifications_api_common.viewsets.NotificationViewSetMixin: a combination of all three mixins above

and define the attribute notifications_kanaal on the viewset:

from .kanalen import ZAKEN


class ZaakViewSet(NotificationViewSetMixin, viewsets.ModelViewSet):
    ...
    notifications_kanaal = ZAKEN