= S3 Subscriptions / Notifications =
[[TOC]]

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

== Subscriptions ==

Person Entities (e.g. 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 ===

[[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. The "check_subscriptions" 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.
4) 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.

=== Framework ===

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

=== Configuration ===

==== Per Deployment ====

==== Per Resource ====

==== Per Subscription ====
== Notifications ==