wiki:AnnouncerPlugin

Version 9 (modified by ixokai, 6 years ago) (diff)

--

Flexible notifications for Trac

Description

The AnnouncerPlugin is meant to provide an extensible, user-customizable notification system that can be used to completely replace Trac's default notifications.

At the very least, it will allow users to receive notices about attachments, and to opt-out from receiving messages due to the always_notify_(owner|reporter|updater) options.

The full system (in the not-too-distant-future) will allow users to 'subscribe' to certain events by specifying simple yet powerful rules, such as asking to receive an announcement for any change that involves a ticket with a priority greater then 'high'. Later, a 'watch' feature is intended to replace CC usage, and allow watching of wiki-pages, and then to enable other plug-ins to provide new means for registering messages that users can subscribe to.

The AnnouncerPlugin is meant to be agnostic to what is being watched; where you should send something (email, IRC, jabber, ...), and what format it should look at. All in good time.

Modules

The plugin itself is very modular, and exactly what features you have will depend on which modules you enable.

Legacy Modules

These mimic the standard trac notification that has been in Trac for awhile. In all cases, they are configured via the [announcer] section of the trac.ini. In most cases, the options are identical to what was previously in the [notification] section. In fact its recommended that you simply rename [notification] to [announcer] if you are going to be using any of these compatibility modules.

  • StaticTicketSubscriber: If enabled, this module will obey the smtp_always_bcc option to deliver a copy of every announcement sent out to a single address.
  • LegacyTicketSubscriber: If enabled, this module will obey the always_notify_owner, always_notify_reporter and always_notify_updater option, except that individual users may choose to opt-out of this on a per-option basis. So if you don't want to receive messages just because you are the reporter, you can uncheck that.
  • CarbonCopySubscriber: If enabled, any name (or address) put into the CC field of a ticket will receive a notification. Note: I recommend you turn this off and instead use the CC field for groups and the Watch This feature for CC's! See below.

No image "Legacy-Prefs.png" attached to AnnouncerPlugin

Groups

With the joinable_groups option in the [announcer] section, the Trac Admins can create any number of joinable groups. Any users may then in their preferences choose to join them by simply clicking to opt-into the membership.

This feature is provided by JoinableGroupSubscriber, and is meant to create targeted groups of people that should be notified about certain important issues. One example might be 'security' that security-related bugs should notify everyone about. Another might be 'sitedown' that represents a critical failure at a customer's site where you want to be sure to notify certain high level management in your company.

In any case, by prepending the group with an @ and adding it into the CC box, everyone who has opted into that group will receive notification of changes to that ticket. E.g., adding '@security' to the CC field will send the security team a message whenever someone alters it. The CarbonCopySubscriber ignores any such entries (if its enabled at all)

Watches

If WatchSubscriber is enabled, then in the context-sensitive navigation portion of each ticket and wiki page, a 'Watch This' link will be provided. Clicking on it will add you to the watch list for the resource-- any changes to it will be sent to you. This can be in addition to the CC field if you have CarbonCopySubscriber enabled, or you can use it to replace the functionality. When a page is already watched, the link changes to 'Unwatch This'

Formatters

For tickets, both a plain text and HTML formatter are currently supplied, and you may choose which you wish to receive in your preferences. For wiki pages, only a plain text notice is currently available.

The HTML formatter also sends out a plain text alternative for those email clients that may not support HTML email.

Distributors

Although the goal is to allow many kinds of distribution, at this point we're only delivering to email addresses. The EmailDistributor uses the same options as the old trac notification, just (as above) in the announcer section and not the notification section. Some options it doesn't quite use yet but will in the future.

There are a few additional ones:

  • use_threaded_delivery: If Python is built with threads, this option will speed up actual delivery by a second or two-- that's not a long time, but it's time not spent delying a request from going through.
  • default_email_format: This should be either 'text/plain' or 'text/html' and represents the default format that it sends email as. Users may override this in their preferences.
  • email_address_resolvers: An ordered list of resolvers (see below) that the distributor uses to map usernames to email addresses. The first one that returns an address, wins.

Resolvers

Currently, the following resolvers can be configured to map usernames to email addresses:

  • DefaultDomainResolver: This will simply blindly append the domain specified in [announcer] smtp_default_domain onto the end of the username.
  • SpecifiedEmailResolver: This will allow the user to override the email address in Trac (or anywhere else) to demand all email be sent to a certain address specified in their user preferences (and separate from Trac's normal address)
  • SessionEmailResolver: This will retrieve the email address associated with the username's Trac session.

The order is important: if you specify resolvers as

[announcer]
email_address_resolvers = DefaultDomainResolver, SpecifiedEmailResolver, SessionEmailResolver

Then the only resolver that will ever be checked would be DefaultDomainResolver-- it blindly appends a domain name, after all. Its best for last.

The recommended setting is:

[announcer]
email_address_resolvers = SpecifiedEmailResolver, SessionEmailResolver

Unless you're in an intranet setup and DefaultDomainResolver is appropriate at the end.

Bugs/Feature Requests

Existing bugs and feature requests for AnnouncerPlugin are here.

If you have any issues, create a new ticket.

Download

Download the zipped source from here. Note: Announcer isn't quite available yet-- re-factoring a bit then I'll post the alpha version up.

Source

You can check out AnnouncerPlugin from here using Subversion, or browse the source with Trac. Note: Announcer isn't quite available yet-- re-factoring a bit then I'll post the alpha version up.

Example

Initially(very soon now), it'll simply be a drop-in replacement for the default notifications, extending them to include attachment additions and deletions, and allowing users to opt-out from receiving notices normally sent because of the always_notify_* options.

Recent Changes

[12503] by hasienda on 2013-01-02 21:37:29
AnnouncerPlugin: Extend AccountManager notifications as required, refs #843, #7759 and #7977.

Note, that any previous version of TracAnnouncer won't work with latest
AccountManagerPlugin 'trunk' code, and this already made me thinking about
a more robust change listener definition. But this is another subject.

[12407] by rjollos on 2012-12-06 02:31:07
Added entries to .gitignore for some pydev project files.
[12402] by rjollos on 2012-12-04 07:39:17
Refs #10584: In [12359], the full path to attachment_notification.html was not being used.

Author/Contributors

Author: ixokai
Contributors:

Attachments (6)

Download all attachments as: .zip