Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Messaging 2.0

From MoodleDocs
Enhanced messaging configuration
Project state implemented, merged into repository
Tracker issue MDL-27171
Discussion http://moodle.org/mod/forum/discuss.php?d=172825
Assignee Ruslan Kabalin

Moodle 2.0


Enhanced messaging system

The messaging system in 2.0 has been revamped significantly:

  • it is now event-driven;
  • it allows users to control exactly what messages they receive and how;
  • it allows administrator to override user settings and set defaults.

Messaging behaviour is controlled by the combination of administrator settings, that define which message outputs are enabled, which outputs can, cannot and should be used for which messages, and user settings that defines which messages user will receive (given that the admin permitted user to control them). The system works graciously when things are not fully configured. For example, jabber notifications can only be send if a Jabber server has been configured, and user has specified his jabber ID in messaging configuration.

Messaging system is enabled by default and controlled via Site Administration > Advanced features > Enable messaging system

Configuration for administrator

There is a dedicated menu item where administrator may configure messaging settings, it is located in Site Administration > Plugins -> Message outputs menu. The menu contains the items for managing messaging outputs, defining default outputs and items for configuring particular outputs like email or jabber.

Manage message outputs

This page summarises which messaging outputs (or processors) you have in the system. You may enable or disable a particular output and proceed to message output system configuration screen. The outputs that are not configured are highlighted and cannot be used in the system (they are not listed in messaging preferences configuration screens). Disabled outputs cannot be used in the system either.

Manage message outputs.jpg

Default message outputs

Default message outputs page is a grid of message outputs (processors) across the top row and message types (providers) across the left column. The intersection cell of particular output and type contains default preferences for chosen messaging type and output.

Default message outputs.jpg

The default preferences menu for each item is identical and allow administrator to choose permission and default setting when user is logged-in and offline. The possible preferences are:

  • Disallowed - the message of chosen type will never be delivered through the chosen output, user is not allowed to change the personal preference for this combination of message type and output.
  • Permitted - the message of chosen type is allowed to be delivered through the chosen output, default preferences can be set by administrator using the checkboxes below, user can control this preference on the messaging preferences page (and change the suggested defaults the most preferable way).
  • Forced - the message of chosen type will be delivered through the chosen output, user is not allowed to change the personal preference for this combination of message type and output.

Outputs configuration

As it was mentioned earlier, the Message outputs menu contains the configuration for outputs that have system configuration settings. Unless output is configured, it cannot be used in the system.

Note: Former settings Admin > Server > Email and Admin -> Server -> Jabber have been moved to Site Administration > Plugins -> Message outputs. Settings upportname, supportemail and supportpage that were on Email settings page were moved to Site Administration > Server -> Support contact.

Configuration for user

Users may configure the messaging preferences in their profile settings My Profile settings > Messaging. The message preferences are configured in "Configure destinations for incoming messages" box that contain a grid of enabled and configured message outputs and message types user has capabilities to access. If particular combination of message type and output is permitted by administrator, user may change the preferences by ticking off the corresponding boxes.

User message preferences.jpg

Some message outputs may require user configuration (e.g. jabber needs ID to be specified), in which case user will not able to set the preferences for the output unless it is configured on the user level. Message output settings are listed at the bottom of messaging preferences page.

User message preferences settings.jpg

Under the bonnet

Capabilities

In order to configure messaging settings in the site administration menu admin requires moodle/site:config permission. User is able to configure personal messaging preferences if moodle/user:editownmessageprofile is granted.

Message types (providers)

Any plugin can declare any number of message types which can be used on Default message preferences and user messaging preferences pages. When the particular message type is being dispatched, the delivery method will be chosen based on messaging permissions and preferences defined by admin and user.

Adding new message type

Message types for the plugins are declared in db/messages.php in plugin directory (or in lib/db/messages.php for the core components). This file contains an array of message types. Each type is presented as array with optional parameters:

  • capability that user require to receive the message dispatch by this component (plugin);
  • defaults optional default settings for some message output.

The file is processed during plugin installation and upgrade. The message type along with capability is stored in message_providers table.

For example (mod/quiz/db/messages.php):

$messageproviders = array (
    
    // notify teacher that a student has submitted a quiz attempt
    'submission' => array (
        'capability'  => 'mod/quiz:emailnotifysubmission'
    ),
    
    // confirm a student's quiz attempt
    'confirmation' => array (
        'capability'  => 'mod/quiz:emailconfirmsubmission'
    )

);

The snippet above will create two message types: submission and confirmation. In the database these records will look like:

id	name	        component	capability
12	submission	mod_quiz	mod/quiz:emailnotifysubmission
13	confirmation	mod_quiz	mod/quiz:emailconfirmsubmission

Once the provider has been added to the database, it become visible on Default message preferences admin interface and, if permitted based on capabilities, on User messaging preferences page.

As it was mentioned above, it is also possible to set default message outputs settings in messages.php file. The optional default setting contains an array of message output names with the default settings. These settings define permission and defaults for online and offline states. The possible settings are:

Type Constants
Permissions MESSAGE_DISALLOWED | MESSAGE_PERMITTED | MESSAGE_FORCED
Defaults for loggedin state MESSAGE_DEFAULT_LOGGEDIN
Defaults for loggedoff state MESSAGE_DEFAULT_LOGGEDOFF

Using the combination of the settings above the permission and/or defaults can be defined in the messages.php file, e.g.:

$messageproviders = array (
    
/// Ordinary single forum posts
    'assignment_updates' => array (
        'defaults' => array(
            'popup' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN,
            'email' => MESSAGE_FORCED,
        ),
    ),
    
);

Only one of Permissions constants should be used for single setting (e.g. 'popup' => MESSAGE_PERMITTED + MESSAGE_DISALLOWED is invalid will result in having the suggested default setting for popup output ignored completely). The above snippet will set default message preferences to:

Default message outputs preset example.jpg

For those processors that are not listed in defaults array (like jabber in the code example above) or if plugin do not have defaults setting at all, or if default setting is invalid, the following defaults are set automatically:

'email' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF;
'anyotheroutput' => MESSAGE_PERMITTED;

Message provider name

The message provider should have a name defined in the corresponding language file. The string should have a key of the format messageprovider:provider_name, e.g. (mod/quiz/lang/en/quiz.php):

$string['messageprovider:confirmation'] = 'Confirmation of your own quiz submissions';
$string['messageprovider:submission'] = 'Notification of quiz submissions';

Message outputs (processors)

Each message output is presented as a plugin (see /message/output). The outputs for email, jabber and web-based popups already exist. A new plugin for different messaging delivery method (e.g. twitter or SMS) can be added quite easily.

The typical message output plugin directory looks like:

message/output/jabber/
├── db
│   ├── install.php
│   └── upgrade.php
├── lang
│   └── en
│       └── message_jabber.php
├── lib.php
├── message_output_jabber.php
├── settings.php
└── version.php

message_output class

The plugin should contain message_output_name.php file (e.g. /message/output/jabber/message_output_jabber.php) with message_output_name class (where name is the actual plugin name) that extends an abstract class called message_output in /message/output/lib.php with the methods:

class message_output_name extends message_output {

    public function send_message($message) {
       // Given a message object and user info, this actually
       // sends it. This function is called by send_message
       // function in lib/messagelib.php
    }

    public function config_form($preferences) {
       // This defines the config form fragment used on user
       // messaging preferences interface (message/edit.php)
    }

    public function process_form($form, &$preferences) {
       // This processes the data from the config form fragment
       // (used in message/edit.php)
    }

    public function load_data(&$preferences, $userid) {
       // This loads up user config for this plugin set via
       // config form fragment (used in message/edit.php)
    }

    public function is_system_configured() {
       // This is an optional method that is supposed to return
       // true if output is configured on the system level
       // for example jabber server settings for jabber plugin.
       // Available as of Moodle 2.1
    }

    public function is_user_configured($user = null) {
       // This is an optional method that is supposed to return
       // true if output is configured on the user level
       // for example user's jabber ID for jabber plugin.
       // $user parameter defaults to $USER global
       // Available as of Moodle 2.1
    }

    public function get_default_messaging_settings() {
        // Allows you to specify what the default message
        // settings should be for this output, in case
        // the message provider supplying the message
        // has not specified them in its messages.php file
        // Available as of Moodle 2.1
    }
}

Settings file

If messaging output plugin requires system configuration, it should provide settings.php file with configuration settings. The link to configuration page will be displayed as a part of admin menu tree (in Site Administration > Plugins -> Message outputs) and in the Manage message outputs page. See Admin_settings for more details.

Lanuage file

The plugin should have a message_name.php file (where name is the actual plugin name) in the correct language directory structure with at least one pluginname string with the name of the processor, e.g.:

$string['pluginname'] = 'Jabber message';

Installation and Upgrade

Like in any other moodle plugin, the message processor plugin should have install and upgrade routines defined in install.php and upgrade.php respectively. At the very list the plugin should register itself in message_processors table which will make it listed on messaging configuration pages. The example content of install.php file for jabber messaging processor is:

function xmldb_message_jabber_install(){
    global $DB;

    $result = true;

    $provider = new stdClass();
    $provider->name  = 'jabber';
    $DB->insert_record('message_processors', $provider);
    return $result;
}

Also the plugin should contain the version.php file. e.g.:

$plugin->version  = 2008090900;
$plugin->requires = 2008091500;

Message dispatching

Messages are dispatched by calling /lib/messagelib.php message_send -method which returns the message ID or false for errors:

$eventdata = new object();
$eventdata->component         = 'mod_forum';    // the component sending the message. Along with name this must exist in the table message_providers
$eventdata->name              = 'posts';        // type of message from that module (as module defines it). Along with component this must exist in the table message_providers
$eventdata->userfrom          = $userfrom;      // user object
$eventdata->userto            = $userto;        // user object
$eventdata->subject           = $postsubject;   // very short one-line subject
$eventdata->fullmessage       = $posttext;      // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN;   // text format
$eventdata->fullmessagehtml   = $posthtml;      // html rendered version
$eventdata->smallmessage      = '';             // useful for plugins like sms or twitter

$result = message_send($eventdata);

The name of each provider is a string with a name like messageprovider:name from the component lang file (in this case, forum.php is derived automatically from mod/forum):

$string['messageprovider:posts'] = 'Subscribed forum posts';
$string['messageprovider:digests'] = 'Subscribed forum digests';

More providers can be added throughout Moodle as necessary, it's quite easy. See the Events API for info.

See also