= S3 Subscriptions / Notifications =
[[TOC]]

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:

[[Image(subscription_model.png)]]

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:

[[Image(notification_process.png)]]

 1. A background task "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)||

----
- [wiki:S3 S3 API Guide]
- DeveloperGuidelines