Skip to content

notification.md

Latest commit

 

History

History
124 lines (92 loc) · 4.62 KB

notification.md

File metadata and controls

124 lines (92 loc) · 4.62 KB

Aam Digital - Notification API

for details about the internal implementation see README in module code folder

Overview

The Notification Module is watching for events that are configured to trigger (push) notifications to users. This module watches for database changes and creates notification events which can be sent through various channels:

  • Push Notifications through Firebase
  • "In-App" Notifications directly in the toolbar of our frontend UI
  • ... in the future maybe also email

Dependencies

Push Notifications are sent through Firebase Cloud Messaging (FCM).

API Specification

notification-api-v1.yaml

Check if feature is enabled

You can make a request to the API to check if a certain feature is currently enabled and available:

> GET /actuator/features

// response:
{
  "notification": { "enabled": true }
}

If the aam-services backend is not deployed at all, such a request will usually return a HTTP 504 error. You should also account for that possibility.

Usage

notifications.drawio.png

Setup

The following environment variables are required:

FEATURES_NOTIFICATIONAPI_ENABLED=true
DATABASECHANGEDETECTION_ENABLED=true

# Firebase Configuration: Confidential (!)
NOTIFICATIONFIREBASECONFIGURATION_CREDENTIALFILEBASE64=<base-64-encoded-firebase-credential-file>

APPLICATION_BASEURL=<your-instance>.aam-digital.com
# if necessary, you can also override the linkBaseUrl (prefer to use the shared APPLICATION_BASEURL however)
NOTIFICATIONFIREBASECONFIGURATION_LINKBASEURL=https://<your-instance>.aam-digital.com

Permission-Aware Notifications (optional)

To filter notifications based on entity-level permissions (so users only receive notifications for entities they can access), configure the connection to the replication-backend:

AAMREPLICATIONBACKENDCLIENTCONFIGURATION_BASEPATH=http://replication-backend:5984
AAMREPLICATIONBACKENDCLIENTCONFIGURATION_BASICAUTHUSERNAME=<admin-username>
AAMREPLICATIONBACKENDCLIENTCONFIGURATION_BASICAUTHPASSWORD=<admin-password>

If these variables are not set, notifications are sent without permission filtering (all users matching a notification rule receive the notification regardless of entity access). This is the expected default for systems without access control (no Config:Permissions document configured). To explicitly disable permission filtering set AAMREPLICATIONBACKENDCLIENTCONFIGURATION_BASEPATH= (empty value).

When the replication-backend is configured but temporarily unavailable, notifications are not sent (fail-closed) to avoid leaking data to unauthorized users.

Firebase Configuration (for Push Notifications)

If you want to send Push Notifications, we rely on Firebase Cloud Messaging (FCM).

  1. Create a Firebase Account
  2. Create a Firebase Project
  3. Select "Cloud Messaging" and "Add a web app" (you can skip the second step of setup through npm)
  4. Open the "Project Settings" page
  5. Under "Your apps" copy to JSON config object
    1. store this as assets/firebase-config.json in the Aam Digital frontend (or overwrite the empty sample file in your ndb-setup folder in your deployment)
    2. make sure this is proper json format (i.e. the keys are also in double quotes)
  6. Create a Service Account or new key for it
    1. ... through the firebase interface as described here
    2. download the firebase-credentials.json with its key
    3. Encode it as base64 run this to print the encoded file to the console: 
      base64 -i firebase-credentials.json
    4. Copy the output (remove line breaks to make it a single line of encoded text)
    5. Add this as an environment variable: NOTIFICATIONFIREBASECONFIGURATION_CREDENTIALFILEBASE64 as described above
  7. To apply the config restart the container, if necessary

Config:Permissions

Users need to have certain Entity Permissions in the frontend to be able to access and configure Notifications:

In the User Permissions doc Config:Permissions in the CouchDB, make sure the following rules are present:

{
  "default": [
    {
      "subject": [
        "NotificationConfig",
        "NotificationEvent"
      ],
      "action": "manage"
    }
  ]
}