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.

The following additional settings are available:

notifications_api_common.settings.CLOUDEVENT_SPECVERSION = '1.0': The used cloudevent specification version

notifications_api_common.settings.IS_HTTPS = True: Indicate if HTTPS is used

notifications_api_common.settings.LOG_NOTIFICATIONS_IN_DB = False: Indicates whether or not failed notifications/cloud events should be saved to the database.

notifications_api_common.settings.NOTIFICATIONS_API_GET_DOMAIN = 'notifications_api_common.utils.get_site_domain': Dotpath of the function used to get the domain of the application

notifications_api_common.settings.NOTIFICATIONS_DISABLED = False: Enable or disable sending of notifications/cloud events

notifications_api_common.settings.NOTIFICATIONS_GUARANTEE_DELIVERY = True: Whether to raise a RuntimeError if the Notifications API is unconfigured when trying to send a notification/cloud event

notifications_api_common.settings.NOTIFICATIONS_SOURCE = '': The identifier of the application to use as the source in notifications and cloudevents

notifications_api_common.settings.NOTIFICATION_NUMBER_OF_DAYS_RETAINED = 60: the number of days for which you wish to keep failed notifications/cloud events in the database

notifications_api_common.settings.TIME_LEEWAY = 0: Time validation leeway in seconds

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