Notifications delivery channels

Owned by Valerii Kuznetsov
May 19, 2021

Concepts

  • Delivery channels are built on top of message output plugins
  • Message outputs plugins code stays backwards compatible with the original messaging system
  • Custom message output plugins will continue to work as is, but will not appear in centralised notification delivery channels until supporting code is added

Database

Enabled delivery channels for notifiable event are stored in notifiable_event_preference.default_delivery_channels for each notifiable event as a comma-separated list of output plugin names. They can be set only in the system context. They are treated as default, meaning that users can override the list of channels in their preferences (which in turn can be overridden by forced channels).

GraphQL

Default delivery channels for notifiable events are provided as part of totara_notification_event_resolver type:

type totara_notification_event_resolver {
  """
  The default delivery channels for this resolver.
  """
  default_delivery_channels: [totara_notification_delivery_channel!]!
}

Specific delivery channel properties are provided by totara_notification_delivery_channel type:

type totara_notification_delivery_channel {
  """
  Message component of this delivery channel.
  """
  component: String!
  """
  The human-readable label
  """
  label: String!
  """
  Whether this channel is checked/in use or not
  """
  is_enabled: Boolean!
  """
  If true, this channel is considered a child of another channel (and must have that enabled)
  """
  is_sub_delivery_channel: Boolean!
  """
  The specific component of the parent delivery channel
  """
  parent_component: String
  """
  Order for display purposes
  """
  display_order: Int!
}

Classes/interfaces

This table outlines the classes, interfaces, and methods most relevant for delivery channels.

Class, interface or model

Description

abstract class totara_notification\delivery\channel\delivery_channelThis class must be extended by output plugin in order to appear in centralised notifications. Extended classes will be auto-discovered as message_{$plugin_name}\totara_notification\delivery\channel\delivery_channel class.
class totara_notification\loader\delivery_channel_loaderThis class is responsible for auto-discovery of delivery channels and getting default delivery channels from event resolvers.
method \totara_notification\manager\notification_queue_manager::filter_message_processors_by_delivery_channel()

Core of delivery channels: this method checks and filters out message processors to be used according to delivery channels settings for the specific notifiable event resolver.

Adding custom delivery channels

To make a message output plugin available in centralised notifications as a delivery channel you need to extend totara_notification\delivery\channel\delivery_channel class and place it in message_{$plugin_name}\totara_notification\delivery\channel name space with the same name (delivery_channel). Implement at least all abstract methods and optionally other methods according to your needs.

message/output/[your_plugin]/classes/totara_notification/delivery/channel/delivery_channel.php
namespace message_your_plugin\totara_notification\delivery\channel;

use totara_notification\delivery\channel\delivery_channel as base_delivery_channel;

class delivery_channel extends base_delivery_channel {
    /**
     * Return the human-readable name of the delivery channel.
     *
     * @return string
     */
    public static function get_label(): string {
        return get_string('delivery_channel_label', 'message_your_plugin');
    }

    /**
     * Define the order the delivery channels should be sorted in.
     * The purpose is to force some semblance of order in the list.
     *
     * @return int
     */
    public static function get_display_order(): int {
        return 100;
    }

    // The below method has the default implementation but can be optionally overridden to gain more granular control over delivery channels

    /**
     * Component name of delivery channel that current plugin depends on
     * If parent delivery channel is disabled, this one will be disabled too
     */
    public static function get_parent(): ?string {
        return your_plugins_parent_delivery_channel::get_component();
    }

}

After this the new delivery channel will appear in centralised notification events management pages and user preferences.