The Notifications Framework, better than creating a complete set of subscriptions, notifications and UI options, is an open framework intended for site administrators and module developers to build custom features.

The most up to date documentation will be as usual on the code itself and the Notifications API and some of the plug-in modules will be extensively documented. The reference implementation for a Notifications plug-in providing new event and subscription types is the Notifications Content module, that will be more accurately documented.

Contributed plug-ins will be welcomed or if implementing the Notifications API from other module in a different package let us know so we can link it from the project main page.

There's a special lightweight API module, Notifications Lite that can be used to send really simple notifications from other modules.

Overview

The notifications module is just the main engine that handles events, queries subscribed users, queues notifications and does the queue processing passing the right data for message composition and sending.

However, all the subscription and event types, and also messages and sending methods are provided by plug-in modules.

So the notifications module just processes the data and sends it through the different stages not knowing anything about specific subscription types or events or messaging methods.

Subscriptions handling

For each individual subscription of a user to an object/object type/user there's a row in the notifications table.

The subscription conditions are stored in the notifications_field table, which allows any number of conditions for a given subscription, one row for each condition.

For example:
User a may be subscribed to:
- Nodes of type x
- Posted by user y
- With taxonomy term t
Or User b may be subscribed to:
- Nodes of type 'blog'
- Posted by user x
This last one would make a subscription to a user's blog.

All this may cause some overlap, having more than one notification for a user in response to the same event.

This should be resolved in the final message composition and sending steps, preventing a user being notified more than once for the same event. I.e. a user may be subscribed to a given taxonomy term and also to a given node type, causing the same node post to produce two notifications, one for the taxonomy term and one for the node type.

However, when the user wants immediate notifications for the first subscription but delayed ones for the second one (such as a daily message) it seems OK to send the event notification in both messages. Thus this de-duping will be done only for messages in the same time interval.

The UI for subscribing and unsubscribing is also provided by a plug-in module. There's the notifications_ui module which handles simple node subscriptions but this one could be replaced by a different module if you want a different kind of UI.

The processing model

How system events are processed and converted into final notifications to users:

  1. An event is triggered
    These events will be defined by plug-in modules and may respond to any Drupal action, like node posting, editing, comment posting etc. A module triggers an event, builds an array with the event parameters and calls notifications_event($event).
  2. The event is filled in and stored
    The notifications module will add default parameters to the event and the event will be stored calling notifications_event_save($event).
  3. Processing and queueing
    Then notifications_queue($event) will be called. This function will populate the notifications_queue table with a list of pending event notifications for specific users. To query the list of subscribed users, hook_notifications('query', $event) will be called, with the modules returning query conditions for the notifications table. All the queued notifications will be filled in with a single db query.
  4. Queue processing on cron
    The notifications_queue table will be checked periodically, compiling pending notifications for each user
    There are two kinds of notifications:
    - Messages to send right away. When the 'delivery interval' is zero, each event produces a single message.
    - Messages to be digested. When we have notifications to be delivered for a given interval, all the events corresponding to that interval will be compiled and digested in a single message
  5. Message composition
    All the events, and other related objects for a message -nodes, comments - will be fetched and passed to the message composition layer. This layer will fetch message templates from messaging system and will run them through token replacement using these objects.
    Note: The message templates may depend on the delivery method, so message templates are handled also by messaging system. I.e. you may want longer notifications for emails but shorter one for SMS's.
  6. Message delivery
    The message array is passed to the messaging layer which will do the final formatting, depending on delivery method and send away the message to the user. For further information on messages, see the messaging framework.

Comments

mhdg’s picture

mhdg commented

When updating node via a bash, php script, as immediate notification is fired in hook_exit, you should not forget to call it.

example:

#!/usr/bin/env php

// Bootstrapping Drupal
require_once './includes/bootstrap.inc';
drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL);

// Logging in as admin user
global $user;
$user->uid = 1;

$node = node_load(113);
$node->body = "test2";
node_save_action($node);
module_invoke_all('exit');
$node_link = l(t('view'), 'node/'. $node->nid);
$watchdog_args = array('@type' => $node->type, '%title' => $node->title);
    watchdog('content', '@type: test.php  %title.', $watchdog_args, WATCHDOG_NOTICE, $node_link);
    drupal_set_message(t('@type %title has been updated.', $t_args));