Developer Area/Notification Plugins & Activities

Mahara has a notification system for sending messages to users. On the implementation side, the system is divided into two parts:

• Activities are the actions that trigger messages, such as posting to a group forum, sharing a page, joining an institution, sending a friend request, or direct messaging another user.
• Notifications are the plugins that deliver those messages to the user. Standard Mahara includes four notifications: Inbox, Email, and Email Digest.

The notification life-cycle

1. A piece of Mahara code calls the method activity_occurred($activitytype, $data, $plugintype=null, $pluginname=null, $delay=null)
   1. If the $delay field is true, or if the activity is marked for delay in the activity_type table in the database, then the activity is inserted into the activity_queue table to be handled by the cron job.
   2. Otherwise, the activity is handled immediately.
2. When the activity is handled, its ActivityType subclass is instantiated, and its notify_users() method is called. This in turn calls the singular notify_user() once for each user.
3. The notify_user() method then looks up the user's preference for which Notification type should be used for this Activity. It calls the appropriate PluginNotification subclass's static notify_user() method. The PluginNotification subclass then sends the message to the user in some way.
4. To ensure that notifications also show up in the user's inbox, the ActivityType also calls PluginNotificationInternal::notify_user(). If their notification preference was for inbox, it marks the message "unread". Otherwise, it marks it "read".

Activities

Activities are an API, but not a full-fledged plugin. Each Activity is defined by a class that extends ActivityType. Core activities are defined in lib/activity.php.

Plugins can also define their own activity types, in their lib.php file. Plugin activities should follow the naming pattern "ActivityType{$plugintype}{$pluginname}{$activityname}". For example, the "feedback" activity of the "comment" Artefact is called ActivityTypeArtefactCommentFeedback.

The bare minimum an ActivityType needs to implement is:

1. __construct($data, $cron = false)

It's poorly documented, but an ActivityType's constructor is meant to call the parent constructor, and then populate $this->users with a list of user records which should receive the message. The $data parameter will be an object, passed in by the call to activity_occurred().

public function __construct($data, $cron = false) {
    parent::__construct($data, $cron);
    $this->users = $this->get_my_users();
}

2. get_required_parameters()

This method should return an array which names the fields that must be present in $data. It should include all necessary data to determine the recipient(s) of the notification, as well as its content.

To specify the content of the message, you will additionally need to override get_message() and get_subject(), or override the $this->strings field to indicate the appropriate lang strings (see ActivityType->get_string_for_user() for the gory details of that approach).

You should not override the notify_users() and notify_user() methods, as they specify important details of how the class interacts with the PluginType classes. We should probably mark those "final".

See also

• Developer_Area/Mahara_Architecture_Introduction/Core_Subsystems#Activity_System
• Developer_Area/Core_Subsystems/Notifications
• Developer_Area/Specifications_in_Development/Notification_Feeds (not implemented yet)