Extension Point : INotificationSubscriber
The INotificationSubscriber subscribes users to notification events.
Trac provides an extendible and flexible notification system. Different people are interested in different kinds of notifications. Notification subscriptions allow administrators and / or users to configure the exact rules used that trigger sending of notifications.
The main part of this interface is the
match() function. It returns a list of subscriptions, in the form of tuples consisting of:
class: The name of the Python class. (This could probably be removed.)
distributor: Also known as
transport. E.g. the string
sid: The session ID of the subscriber. (Can be
1for authenticated session IDs,
0for anonymous session IDs.
address: The (email) address to use. (Can be
format: The MIME type to be used (e.g.
priority: An integer priority. Smaller numbers have higher priority than bigger numbers.
1is the highest priority.
adverb: Either the string
Since more than one component can handle the same realms and categories, the priorities and adverbs are used to resolve conflicting subscriptions.
The implementation can use any means to determine if a user is interested in hearing about a given event. Most check that the appropriate conditions apply and then retrieve the required information from the notify_subscription DB table.
The subscriptions in that table are configured in a shared preferences panel that uses two other methods of this interface:
description() method returns a description string shown to the user in the preferences panel (or
None if the plugin does use the
notify_subscriptions DB table.)
requires_authentication() method allows hiding the rule from unauthenticated users. (E.g. because only authenticated users can be ticket owners.)
default_subscriptions() method describes any default subscriptions that automatically exist without the user configuring
subscription DB entries in the preferences.
These are also displayed on the preferences panel, but can not be directly modified there. (They usually can be overriden by non-default subscriptions.)
The plugin still has to return the respective subscriptions from the
Default descriptions should be used when users can be determined by the event itself.
For instance, ticket author has a default subscription that is controlled via trac.ini.
Default subscriptions should be low priority (i.e. have a priority number much larger than
1, like 100) so that the user can easily override them.
The following example implements a simple subscriber that can trigger notifications when a new ticket is created with a high priority level.
from trac.core import * from trac.notification.api import INotificationSubscriber from trac.notification.model import Subscription class HighPriorityTicketNotificationSubscriber(Component): implements(INotificationSubscriber) # INotificationSubscriber methods def matches(self, event): if event.realm != 'ticket': return if event.category != 'created': return ticket = event.target if ticket['priority'] not in ('blocker', 'critical', 'major'): return klass = self.__class__.__name__ for i in Subscription.find_by_class(self.env, klass): yield i.subscription_tuple() def description(self): return "notify me when new high priority tickets are created" def requires_authentication(self): return False
See wiki:CookBook/Notification/Subscriptions for more examples.
Allows ticket owners to subscribe to (or unsubscribe from) change notifications for owned tickets.
Allows anyone to subscribe to (or unsubscribe from) change notifications for their own ticket changes.
Allows anyone to subscribe to (or unsubscribe from) change notifications for tickets they previously updated.
Allows ticket reporters to subscribe to (or unsubscribe from) change notifications for tickets they created.
Allows anyone to subscribe to (or unsubscribe from) change notifications for tickets where they are listed in CC.