= 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.

NB: It is a requirement for the notification lookup request that it applies the same permission rules as if the respective user would access the resource online, so that they are only notified about such records they are permitted to access - and of course all additional role-based content rules in the controller are also applied.

For that to work, obviously the subscription must be associated with a user, and hence with the pe_id of a user. If the subscription is not associated with an individual user, then the lookup request is, logically, anonymous.

That means, if you want to subscribe a person entity that is not an individual user, but e.g. a group or an organization, then the target controller and table must be accessible by the ANONYMOUS role.

=== 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 a simple selector is insufficient (like {{{~.master_id=x}}}) then a [wiki:S3/FieldSelectors#ContextPaths context selector] may be useful. If different filters are required, then multiple subscriptions will also be required.

=== GUI ===

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

A custom interface can be found in modules/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 "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 ''modules/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 modules/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