===== Notifications Infrastructure Proposal/Questions =====

  * Date: 2008/11/07
  * Author: Bill Erickson

==== Introduction ====

The purpose of this document is to define how Evergreen components generate and manage notifications.  It does not attempt to define notification triggers (e.g. hold available) or delivery mechanisms (e.g. email).  It only attempts to lay out the inter-module and database communication for managing the data.  For more on proposed triggers and delivery mechanisms, see [[http://open-ils.org/dokuwiki/doku.php?id=scratchpad:notification_system]]. 


==== Creating notices ====

  - Some positive event occurs.  Example events include "hold available for pickup" and "max fines reached".
  - Context information is passed directly to a new class method OpenILS::Notify->create_notification($user_id, $context).  
    * $context is a key/value set of data relevant to the notification.  For example, {hold_id: 123}  
    * The handler for this type of event is the only code that needs to understand the content of $context.
    * $context will be stored in the DB as a JSON object.
    * $context should only contain object IDs, where necessary, and not full objects, since they will be re-retrieved at notice generation time, to ensure current data.
    * Many notice types will not require any $context data.  For example, "max fines reached" may only need the user.
  - See if there already exists a like pending notification type in the database for this user.  If so, stop there.
  - Based on the type of event and user/org_unit settings, determine which delivery mechanism(s) and scheduling will be used for this type of event.
  - For each delivery mechanism, create a new row in the notification table (action.notification_queue? notification.queue?) table.<code>
# DB table
id
usr
create_time
notification_type
delivery_protocol
notify_time
# The big question, how do we manage delivery times?  
# what else?</code>
  - CRON job, which regularly checks, picks up the next batch of notices whose delivery window coincides with "now"
  - Each notice is passed to OpenILS::Notify->send_notification($notice_id)
  - If a handler has been registered for this event type, call the handler with the context data.  The handler, using the "hold ready for pickup" example, might be a class called OpenILS::Notify::Handler::Holds, which defines and registers the handler code for each type of hold-related notice.
  - Handler collects hold-related data from the DB to build a notification context object.
    * The context object will be the same regardless of delivery protocol.
  - Pass the context object to the delivery handler.  For example, OpenILS::Notify::Protocol::SMTP
    * This passes the context object through the appropriate notification template to generate the notice content
    * Sends notice

==== Canceling Notices ====

  - Negative event occurs.  For example, "captured hold cancelled" and "sufficient funds paid".
  - Context info (same as create-notice context) is passed to OpenILS::Notify->cancel_notification($user_id, $context).
  - context info is passed to the registered handler, which finds any like notifications in the DB and deletes/cancels them.  In other words, it's up to the handler to determine what constitutes a matching notification.
 

==== Managing notification windows ====

There are two main points to consider:
  - Manditory pre-notify delay.  
    * For example, before sending a hold notification, the system should wait at least 1 hour before generating an email so, for example, the captured item can be marked as damaged and the hold retargeted.
    * This one seems relatively straightforward.  Somewhere, the database stores a timestamp which represents the earliest possible delivery time.
  - Day/Time specific notification windows.
    * For example, "I accept phone notifications weekdays, between 5pm and 7pm".  
    * Feedback based time windows, For finding out the best time to call(for a phone notification) automatically.  Last time we called customer X at 3:30pm we received a busy, try an hour later next time.  
    * **??**

==== Managing Templates ====

Ideally, templates would live in the database, however, that would require a template editor of some sort.  For now, we may just want to leave them on the file system with org-unit settings that map to the relevant template file.

==== Miscellaneous ====

The open-ils.penalty server already understands max overdues and max fines.  It's here that fine, overdue, and other penalty-related events will be generated and canceled.  Other events will be managed on a per-type basis.