wiki:AnnouncerPlugin

Version 40 (modified by Ryan J Ollos, 14 years ago) (diff)

Link to new FullBlogPlugin for AnnouncerPlugin.

Flexible notifications for Trac

Notice: This plugin is unmaintained and available for adoption.

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.

See also WikiNotificationPlugin.

Modules

The plugin itself is very modular, and exactly what features you have will depend on which modules you enable. You select modules in the 'Plugins' page of the 'Admin' section of your trac.

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.

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'

General Wiki

If you would like to receive more general notice of wiki changes, you can use the GeneralWikiSubscriber. With it you may specify any number of patterns, and if they match a wiki page name, you'll receive a notice if that page is created, edited, deleted, or such.

In particular, you may use a pattern of '*' and you'll see any wiki changes that happen on the site.

This is particularly useful in situations where the wiki uses a hierarchal structure; so if you use a pattern such as 'Project*', then 'Project/Plan' and 'Project/Concerns' will all match.

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.

The following trac.ini options are available to configure the ticket formatter:

ticket_email_subject
Determines the subject of the email that is sent out. Defaults to Ticket #${ticket.id}: ${ticket['summary']}.
ticket_email_header_fields
A list of fields that are always sent at the top of the email notification; Defaults to owner, reporter, milestone, priority, severity.

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 delaying 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.

Plugins

The AnnouncerPlugin has plugins to support the following Trac plugins:

Bugs/Feature Requests

Existing bugs and feature requests for AnnouncerPlugin are here.

If you have any issues, create a new ticket.

Installation and Configuration

After installing AnnouncerPlugin, be sure to run trac-admin /path/to/env upgrade. This is needed because the plugin adds a table to the db. The upgrade script allows the plugin to create the needed table.

As of r3107 (dubbed v0.2), the AnnouncerPlugin has been working (for me!) in a basic way in our corporate Trac installation. This includes all the mentioned modules above, in particular the notification of Wiki additions/changes/deletions to anyone interested, 'watching' interesting resources, HTML ticket notifications, and such.

The email distribution is not as stable and complete as the default Trac notifications yet; there's many options that are not yet taken into account, and a lot of stuff particularly focused around codecs that are simply ignored right now. That isn't to say it won't work, just that you should be prepared for errors if you're ambitious enough to use it until more people have tried it :)

Development Version

The trunk branch has been under heavy development and changes a number of things in the AnnouncerPlugin. One key change is the module naming convention. You will need to edit your trac.ini components section and change any reference to announcerplugin to announcer. There are many other module changes, so it's probably best to use the Trac plugin admin to configure AnnouncerPlugin after an upgrade.

I am currently developing AnnouncerPlugin against Trac 0.12 and python 2.6. I can't think of any reason it won't work with older version, but buyer beware. I am always willing to accept patches.

As of [8087] there is preliminary support for sending encrypted and/or cryptographically signed emails. OpenPGP support is provided by GnuPG and working only with plain text formatted messages by now. There's still a lot to be done. See more details at the corresponding development page.

Prerequisites

Download

Installation

The easiest way to install AnnouncerPlugin is to simply point easy_install at the t-h.o SVN repository, a la:

 easy_install http://trac-hacks.org/svn/announcerplugin/0.11

Alternatively, you may download the source via one of the above methods and go into the 0.11 directory and then run:

 python setup.py install

For the new 0.12/trunk branches see the i18n/l10n section below for an important hint on egg creation that applies to system wide installations as well.

After you have installed the AnnouncerPlugin, you must carefully evaluate the modules you wish to use and enable them. The simplest method of doing this is through 0.11's built in Admin panels.

The following recommendations should make the decisions easier:

  • Producers - It is recommended you enable all of the producers; they are the source of events that are fed into the AnnouncementSystem.
    • TicketChangeProducer
    • WikiChangeProducer
    • AttachmentChangeProducer
  • Subscribers - Evaluate the descriptions of the subscriber modules above, and decide which features you want users to support.
    • For compatiblity with your current setup, the following are recommended:
      • LegacyTicketSubscriber
      • StaticTicketSubscriber (if you use smtp_always_bcc)
      • CarbonCopySubscriber
    • Additional options that are recommended:
      • WatchSubscriber (to allow the user to Watch tickets or wiki entries; if you use this its possible to replace existing CC functionality with this more privacy-aware option)
      • GeneralWikiSubscriber
    • Possibly useful:
      • JoinableGroupSubscriber (this was more of a proof-of-concept then anything else; but with WatchSubscriber above and a disabled CarbonCopySubscriber, it can allow you to completely redefine the CC field)
  • Distributors - Only EmailDistributor is available at this point, so is essentially required.
  • Formatters - It is recommended that both formatter modules be enabled. If one is disabled, then events from that specified realm will never be able to be sent to anyone.
    • TicketEmailFormatter
    • WikiEmailFormatter
  • Resolvers - For all subscriptions besides those sent from CarbonCopySubscriber, a resolver must be present to translate a name into an address
    • SessionEmailResolver (recommended, will use the session's email address (authenticated or otherwise) to send mail)
    • DefaultDomainEmailResolver (recommended if you used the smtp_default_domain option previously)
    • SpecifiedEmailResolver (not recommended-- a proof of concept if nothing else)

So, basically, for a system that is basically compatible with your existing setup and allowing minimally invasive wiki features, the following is suggested in trac.ini:

[components]
announcerplugin.* = enabled
announcerplugin.subscribers.ticket_groups.* = disabled

Configuration

This plugin may break notifications from other Trac plugins that use the default Trac notification system. A plugin that sends notifications using the t:TracNotifications system needs to be modified to use the AnnouncerPlugin API. For example, see FullBlogPlugin.

The easiest way to configure Announcer is to first configure the Trac notification system as described in t:TracNotification, and then simply rename the [notification] section in your trac.ini to [announcer]. Where possible, the option names are the same. Additional options that may be available are specified above in the modules section.

For better collaborate with the WatchlistPlugin the two contextual navigation items Watch This/Unwatch This on the wiki page can be renamed by specifying the following in the [announcer] section. An empty value removes them completely.

ctxtnav_names = Notify me, Do not notify me 

About i18n/l10n support

The development version of this plugin is prepared for localization.
But English message texts are still the (POSIX) default. If this isn't your preferred language, you can

  1. look, if it's already available from the Trac plugin l10n project at Transifex or
  2. do it yourself (see the l10n cookbook page for Trac plugins for more details).

You've done a new translation? Superb! Contributing your translation is highly appreciated.
You could send it to the plugin's maintainer or contribute to Trac plugin l10n project via Transifex:

Top translations: Trac_Plugin-L10N » announcer

http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/announcer/chart/image_png

Kindly provided by http://sw.transifex.net/2/static/charts/images/tx-logo-micro.png

Preparing the plugin from source requires the additional step of compiling message catalog files. Walk through:

cd announcerplugin
python ./setup.py egg_info
python ./setup.py compile_catalog -f
python ./setup.py bdist_egg

If you missed the 3rd step, you'll get an error in the 4th step complaining about missing locale directory. This is just a side-effect, because there are no complied message catalogs for inclusion into Python egg, hence the whole path is missing.
To exclude translations marked as # fuzzy by the translator, you'll want to omit the extra -f argument to message catalog compilation. Again, for more details see the l10n cookbook page for Trac plugins.

Recent Changes

17678 by rjollos on 2020-02-22 19:54:57
TracAnnouncer 1.2.0dev: Fix syntax error in r17660

Refs #12120, Fixes #13733.

17660 by rjollos on 2020-01-22 22:09:21
TracAnnouncer 1.2.0dev: Make prefs compatible with Trac 1.2

Refs #12120, Fixes #13733.

16900 by rjollos on 2017-10-18 06:00:30
TracAnnouncer 1.2.0dev: Use IEmailAddressResolver from Trac 1.2

Refs #12120.

(more)

Author/Contributors

Author: ixokai
Maintainer: doki_pen
Contributors: hasienda

Attachments (6)

Download all attachments as: .zip