| 20 | | Announcer is itself a plug-in, but it will be able to be enhanced by other plug-ins should anyone want to. As such it has a number of places where its existing behavior can be added to: |
| 21 | | * Producers: These initiate an event; the core Announcer producers are almost all implementations of I*ChangeListener interfaces, such as ITicketChangeListener, IAttachmentChangeListener, and IWikiChangeListener. When they receive events across these various interfaces, they package them into an event and (in particular) classify each event as a "realm" and "category". For example, "ticket, created", "ticket, changed", "ticket, deleted", "ticket, attachment added", etc. |
| 22 | | * Subscribers: These are responsible for discovering who is interested about hearing an event. Every subscriber registers itself as willing to handle subscriptions for a particular realm and/or category, and from there it checks to see what users may be interested in an event. The subscriber returns the user who is interested about the event and what method they're interested in hearing about it via-- e.g., email, IRC, IM, or whatever. |
| 23 | | * Formatters: Once it has been decided that this particular user is interested in hearing about this event, a formatter is invoked to transform that event into an actual message. Plain text, HTML, oneliner, are all example formatters. If someone would like the ticket change email to always display certain key properties even if not changed, all that's needed is a new formatter to accomplish that. |
| 24 | | * Distributors: Finally, the Distributor is the component that actually -sends- the message. Each one generally transmits via one type of communication channel; email, IRC, AIM, and suchlike. |
| 25 | | * Resolvers: The purpose of a resolver is to turn a username into an address. For certain corporate sites, a component to simply append "@example.com" to the authenticated trac username will be sufficient. The default resolver will simply use whatever email address the authenticated person has set in trac. Others may be more complicated and query an external resource to determine where to send "fubarbaz"'s emails. |
| 26 | | * Preferences: Various components may change their behavior based on user-preferences; does the user prefer HTML or plain-text? does the user not want to get messages when they update tickets? Etc. As each of these components is optional, and others may add new ones at a whim, how to manage the preferences was something of a problem. Each component could add its own preference panel, but that would litter up the interface a lot. Instead, Announcer provides its own preference interface that behaves the same way as IPreferencePanelProvider, except instead of providing an entire panel, it provides only a single "box". All the boxes are rendered together. |
| | 18 | ==== Legacy Modules ==== |
| 33 | | Specifically, done: |
| 34 | | '''Producers''':: |
| 35 | | !TicketChangeProducer, !AttachmentChangeProducer. These both plug into the respective I*!ChangeListener's, and so any change to a ticket-- including adding/removing attachments-- are converted into announcement events and sent through. Notably, attachments on wiki pages aren't yet but just because talking about changes to attachments without their parent wiki would be silly. !WikiChangeProducer is top of the list once I start receiving emails from the system :) |
| 36 | | '''Subscribers''':: |
| 37 | | !StaticTicketSubscriber adds a static subscription to every event; its essentially identical to smtp_always_bcc. !LegacyTicketSubscriber mimics the behavior of always_notify_(owner|reporter|updater) but allows users to opt-out of these decisions. !CarbonCopySubscriber mimics the CC field behavior. !RuleBasedTicketSubscriber to do simple filtering on ticket events is about half done. |
| 38 | | * !JoinableGroupSubscriber: Admin define a list of 'groups' in trac.ini-- simple names. Anyone can then, in their preferences, indicate they are a member of said group. Such as 'sec' for security issues. If "@(group)" is added to the CC field, all members of the group will receive the notice. The purpose being bringing special attention to a topic to a group of people who are interested in that topic. !CarbonCopySubscriber appropriately just ignores any CC that starts with an @. |
| | 24 | * ''!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. |
| 40 | | '''Distributors''':: |
| 41 | | !EmailDistributor is basically done-- what with liberal theft from trac.notifications meaning I didn't have to re-implement the actual /sending/. :) Eventually I'm going to make it launch an external process (without waiting) I think -- as an option. I don't want a blocking SMTP going bad screwing up Trac. |
| 42 | | '''Resolvers''':: |
| 43 | | Subscriptions can provide either a name, or an address; in the case of an address (such as !StaticTicketSubscriber) its just sent. In the case of a name though, an address has to be obtained. !SessionEmailResolver grabs the email address associated with a session. !DefaultEmailResolver appends a set domain name on the end of the user name that's specified in trac.ini (The theory is that if you are hooking your Trac up to a corporate authentication, and your username is the same as your email, this can turn 'shansen' into 'shansen@example.org'). !SpecifiedEmailResoler allows a user to (in preferences) specifically choose an alternate email address (separate from the one obtained anywhere else) that they'd like to send to. |
| 44 | | * It's worth noting, ''which'' resolvers that are used are set in a trac.ini option and in order. So for my sit I'd set it to !SpecifiedEmailResolver, !SessionEmailResolver. So the email address used is the one specified in the session-- unless someone picks a different one. And yes I know they can change their main address, I do have a situation where it is undesirable to random notices to the main trac address but still desirable for said address to remain. |
| | 26 | * ''!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. |
| | 27 | |
| | 28 | [[Image(AnnouncerPlugin:Legacy-Prefs.png)]] |
| | 29 | |
| | 30 | ==== Groups ==== |
| | 31 | |
| | 32 | 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. |
| | 33 | |
| | 34 | 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. |
| | 35 | |
| | 36 | 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) |
| | 37 | |
| | 38 | [[Image(AnnouncerPlugin:Groups-Prefs.jpg)]] |
| | 39 | |
| | 40 | |
| | 41 | ==== Watches ==== |
| | 42 | |
| | 43 | 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' |
| | 44 | |
| | 45 | [[Image(AnnouncerPlugin:WatchThis.png)]] |
| | 46 | |
| | 47 | |
| | 48 | ==== Formatters ==== |
| | 49 | |
| | 50 | 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. |
| | 51 | |
| | 52 | The HTML formatter also sends out a plain text alternative for those email clients that may not support HTML email. |
| | 53 | |
| | 54 | [[Image(AnnouncerPlugin:HtmlEmail.jpg)]] |
| | 55 | |
| | 56 | |
| | 57 | ==== Distributors ==== |
| | 58 | |
| | 59 | 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. |
| | 60 | |
| | 61 | There are a few additional ones: |
| | 62 | * 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. |
| | 63 | * 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. |
| | 64 | * 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. |
| | 65 | |
| | 66 | ==== Resolvers ==== |
| | 67 | |
| | 68 | Currently, the following resolvers can be configured to map usernames to email addresses: |
| | 69 | |
| | 70 | * ''!DefaultDomainResolver'': This will simply blindly append the domain specified in [announcer] smtp_default_domain onto the end of the username. |
| | 71 | * ''!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) |
| | 72 | * ''!SessionEmailResolver'': This will retrieve the email address associated with the username's Trac session. |
| | 73 | |
| | 74 | The order is important: if you specify resolvers as |
| | 75 | |
| | 76 | {{{ |
| | 77 | [announcer] |
| | 78 | email_address_resolvers = DefaultDomainResolver, SpecifiedEmailResolver, SessionEmailResolver |
| | 79 | }}} |
| | 80 | |
| | 81 | Then the only resolver that will ever be checked would be DefaultDomainResolver-- it blindly appends a domain name, after all. Its best for last. |
| | 82 | |
| | 83 | The recommended setting is: |
| | 84 | |
| | 85 | {{{ |
| | 86 | [announcer] |
| | 87 | email_address_resolvers = SpecifiedEmailResolver, SessionEmailResolver |
| | 88 | }}} |
| | 89 | |
| | 90 | Unless you're in an intranet setup and DefaultDomainResolver is appropriate at the end. |
