S3 Subscriptions / Notifications

The S3Notifications framework is used to send automatic update notifications to subscribers.

Subscriptions

Users can subscribe to get notified when new records get created or records get updated in a resource.

Subscriptions can be filtered (using saved filters) to limit notifications to records matching certain filter criteria.

Data Model

Subscriptions use the S3SubscriptionsModel in modules/s3db/pr.py:

The pr_subscription table stores the notification settings and links to the subscriber person entity (user) and the filter.

The pr_subscription_resource table is a component of pr_subscription and stores the name of the resource and the URL of the controller to check for updates.

All resources in a subscription use the same filter. If different filters are to be used, multiple subscriptions are required.

GUI

No generic user interface for subscriptions has been implemented so far.

A custom interface can be found in private/templates/DRMP/controllers.py. This interface manages a single subscription per user with multiple resources using a common filter.

Notifications

Data Model

Notifications build on the S3SubscriptionModel (see above) and the web2py Scheduler (for running tasks and logging).

Process

The notification process has 4 phases:

1. A background task "notify_check_subscriptions" (installed in zzz_1st_run.py) is run every 5 minutes to check for updates of resources which have subscriptions. This task schedules a separate, asynchronous "notify_notify" task for each resource/subscription pair which has updates.
2. Each "notify_notify" task generates a local HTTP POST request to the subscribed controller (request format "msg"), applying the subscription filters.
3. This request is handled by the S3Notifications.send() method, impersonating the subscriber. The send() method extracts the new/updated records, and renders and sends the notification message(s) to the subscriber. Sending of the messages uses current.msg.send_by_pe_id(), which in turn uses the contact information of the subscriber stored in pr_contact.
4. Messages are send asynchronously by the msg_process_outbox task.

Framework

All parts of the notifications framework are implemented as S3Notifications class in modules/s3/s3notify.py.

To impersonate the subscriber for send(), S3Notifications.notify() sends a temporary, single-use auth token together with the POST request. This auth token is handled in models/00_utils.py.

Notifications require a scheduler worker process to run in the background.

Message Templates

Rendering of notification messages happens in two phases:

• Pre-rendering using a hook function
• Rendering via web2py view templates (message templates)

The pre-rendering is to convert the extracted data into a suitable format for the message template. The pre-rendering routine is configurable both per deployment-template and per resource (resource-specific overrides deployment-specific), the default pre-renderer is S3Notifications._render().

The message templates are web2py view templates stored in private/template/XYZ/views/msg (falling back to views/msg).

Template names use a prefix (default: "notify") and the notification method name, like: notify_email.html (=template for email notifications).

The template name prefix can be configured per resource (using the "notify_template" setting), the default is "notify".

Message templates for EMAIL can further use a format suffix "html" or "text" (e.g. notify_email_html.html) - where both fall back to the name without suffix.

Any deployment-template-specific message templates (including fallbacks) is preferred over any default templates.

Configuration

Per Deployment

• in private/templates/XYZ/config.py or 000_config.py

Setting	Explanation
settings.msg.notify_renderer	Pre-renderer function, render(resource, data, meta_data, format=None)
settings.msg.notify_subject	Template for the subject line of notification emails
settings.msg.notify_email_format	Preferred email format (can be overridden per subscription) - "html" or "text"

Per Resource

• with s3db.configure()

Setting	Explanation
notify_fields	Fields to extract for notification emails (like list_fields)
notify_renderer	Pre-renderer function, see settings.msg.notify_renderer
notify_template	Prefix for the message template(s)

---

• S3 API Guide
• DeveloperGuidelines