Changes between Version 3 and Version 4 of TracDev/NotificationApi

Timestamp:

Dec 6, 2014, 1:24:04 PM (9 years ago)

Author:

Peter Suter

Comment:

Document new notification API, replacing old page entirely

TracDev/NotificationApi

@@ -1 @@
-= Trac Notification API =
-[wiki:TracNotification TracNotification] provides support for event triggered notifications.
- ''As of 0.12 only email notification has been implemented. It is used exclusively by the ticket system. This might change in the future, if i.e. the [wiki:TracDev/Proposals/Announcer proposal] for integration of the [th:wiki:AnnouncerPlugin AnnouncerPlugin] infrastructure would be done.''
+[[PageOutline(2-3)]]
 
-== Existing Interface ==
-This is how it's implemented in Trac 0.12. Source: [source:trunk/trac/notification.py trac/notification.py]
+= Trac Notification API
 
-{{{#!th
-type
-}}}
-{{{#!th
-name
-}}}
-{{{#!th
-doc-string/notes
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-IEmailSender(Interface)
-}}}
-{{{#!td
-Extension point interface for components that allow sending e-mail.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-Send message to recipients.
-}}}
-|----------------
-{{{#!td colspan="3"
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-!NotificationSystem(Component)
-}}}
-{{{#!td
-Name of the component implementing `IEmailSender`.[[BR]]
-This component is used by the notification system to send emails. Trac currently provides `SmtpEmailSender` for connecting to an SMTP server, and `SendmailEmailSender` for running a `sendmail`-compatible executable. (''since 0.12'')
-{{{#!th
-type
-}}}
-{{{#!th
-section
-}}}
-{{{#!th
-option name
-}}}
-{{{#!th
-default value
-}}}
-{{{#!th
-doc-string/notes
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_enabled
-}}}
-{{{#!td
-false
-}}}
-{{{#!td
-Enable email notification.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_from
-}}}
-{{{#!td
-'trac@localhost'
-}}}
-{{{#!td
-Sender address to use in notification emails.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_from_name
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Sender name to use in notification emails.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_replyto
-}}}
-{{{#!td
-'trac@localhost'
-}}}
-{{{#!td
-Reply-To address to use in notification emails.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_always_cc
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Email address(es) to always send notifications to, addresses can be seen by all recipients (Cc:).
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_always_bcc
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Email address(es) to always send notifications to, addresses do not appear publicly (Bcc:). (''since 0.10'').
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_default_domain
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Default host/domain to append to address that do not specify one.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-ignore_domains
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Comma-separated list of domains that should not be considered part of email addresses (for usernames with Kerberos domains).
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-admit_domains
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Comma-separated list of domains that should be considered as valid for email addresses (such as localdomain).
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-mime_encoding
-}}}
-{{{#!td
-none
-}}}
-{{{#!td
-Specifies the MIME encoding scheme for emails.[[BR]]
-Valid options are 'base64' for Base64 encoding, 'qp' for Quoted-Printable, and 'none' for no encoding, in which case mails will be sent as 7bit if the content is all ASCII, or 8bit otherwise. (''since 0.10'')
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-use_public_cc
-}}}
-{{{#!td
-false
-}}}
-{{{#!td
-Recipients can see email addresses of other CC'ed recipients.[[BR]]
-If this option is disabled (the default), recipients are put on BCC. (''since 0.10'')
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-use_short_addr
-}}}
-{{{#!td
-false
-}}}
-{{{#!td
-Permit email address without a host/domain (i.e. username only).[[BR]]
-The SMTP server should accept those addresses, and either append a FQDN or use local delivery. (''since 0.10'')
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_subject_prefix
-}}}
-{{{#!td
-{{{'__default__'}}}
-}}}
-{{{#!td
-Text to prepend to subject line of notification emails.[[BR]]
-If the setting is not defined, then the [$project_name] prefix. If no prefix is desired, then specifying an empty option will disable it. (''since 0.10.1'').
-}}}
+== New API
+''(since Trac 1.1.3)''
 
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send_email
-}}}
-{{{#!td
-Send message to recipients via e-mail.
-}}}
-|----------------
-{{{#!td colspan="3"
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-!SmtpEmailSender(Component)
-}}}
-{{{#!td
-'''implements IEmailSender'''[[BR]]
-E-mail sender connecting to an SMTP server.
+The new API keeps the `IEmailSender` extension point and the `NotificationSystem` component almost unchanged from the [#OldAPI old API], but deprecates the entire `Notify` hierarchy.
 
-{{{#!th
-type
-}}}
-{{{#!th
-section
-}}}
-{{{#!th
-option name
-}}}
-{{{#!th
-default value
-}}}
-{{{#!th
-doc-string/notes
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_server
-}}}
-{{{#!td
-'localhost'
-}}}
-{{{#!td
-SMTP server hostname to use for email notifications.
-}}}
-|----------------
-{{{#!td
-!IntOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_port
-}}}
-{{{#!td
-25
-}}}
-{{{#!td
-SMTP server port to use for email notification.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_user
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Username for SMTP server. (''since 0.9'')
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-smtp_password
-}}}
-{{{#!td
-{{{''}}}
-}}}
-{{{#!td
-Password for SMTP server. (''since 0.9'')
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-use_tls
-}}}
-{{{#!td
-false
-}}}
-{{{#!td
-Use SSL/TLS to send notifications over SMTP. (''since 0.10'')
-}}}
+It is replaced by a new class hierarchy. An instance of such a class contains all known data about an event that requires sending notifications:
+* [#NotificationEvent] (common properties shared among all events)
+  * [#TicketChangeEvent] (properties specific to ticket change events)
+  * [#BatchTicketChangeEvent] (properties specific to ticket batch modification events)
 
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td colspan="3"
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-!SendmailEmailSender(Component)
-}}}
-{{{#!td
-'''implements IEmailSender'''[[BR]]
-E-mail sender using a locally-installed sendmail program.
+The `NotificationSystem` gains some simple methods to process such events. Also several new extension points are introduced that allow plugins to hook into that processing.
 
-{{{#!th
-type
-}}}
-{{{#!th
-section
-}}}
-{{{#!th
-option name
-}}}
-{{{#!th
-default value
-}}}
-{{{#!th
-doc-string/notes
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-sendmail_path
-}}}
-{{{#!td
-'sendmail'
-}}}
-{{{#!td
-Path to the sendmail executable.[[BR]]
-The sendmail program must accept the `-i` and `-f` options. (''since 0.12'')
-}}}
+=== !NotificationEvent
+Contains the following properties:
+* `realm`: a string of the affected resource realm (e.g. `'ticket'` or `'wiki'`)
+* `category`: a string to identify the category of event (e.g. `'created'`, `'changed'` or `'deleted'`)
+* `target`: the resource [wiki:TracDev/DataModels model] (e.g. an instance of `Ticket` or `WikiPage`) or `None`
+* `time`: the `datetime` when the event happened
+* `author`: the [wiki:TracDev/TracSession session id] of the user responsible for the event
 
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td colspan="3"
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-Notify(object)
-}}}
-{{{#!td
-Generic notification class for Trac.[[BR]]
-Subclass this to implement different methods.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-{{{__init__}}}
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-notify
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-get_recipients
-}}}
-{{{#!td
-Return a pair of list of subscribers to the resource 'resid'.[[BR]]
-First list represents the direct recipients (To:), second list represents the recipients in carbon copy (Cc:).
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-begin_send
-}}}
-{{{#!td
-Prepare to send messages.[[BR]]
-Called before sending begins.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-Send message to recipients.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-finish_send
-}}}
-{{{#!td
-Clean up after sending all messages.[[BR]]
-Called after sending all messages.
-}}}
-|----------------
-{{{#!td colspan="3"
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-!NotifyEmail(Notify)
-}}}
-{{{#!td
-Baseclass for notification by email.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-{{{__init__}}}
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-_init_pref_encoding
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-notify
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-format_header
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-add_headers
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-get_smtp_address
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-encode_header
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-includes methods {{{build_addresses}}} and {{{remove_dup}}}
-}}}
+=== !TicketChangeEvent
+* `realm` is 'ticket'.
+* Known values for `category` are `'created'`, `'changed'`, `'attachment added'` and `'attachment deleted'`.
+* `target` is an instance of `Ticket`.
+* Additional properties:
+  * `comment`: a string containing the user's comment (or `None`)
+  * `changes`: an empty dictionary for now
+  * `attachment`: `None` for now
 
-Source: [source:trunk/trac/notification.py trac/notification.py]
+=== !BatchTicketChangeEvent
+* `realm` is 'ticket'.
+* `category` is 'batchmodify'.
+* `target` is a list of ticket ids(!)
+* Additional properties:
+  * `comment`: a string containing the user's comment
+  * `new_values`: a dictionary with property names as keys and new property values as values.
+  * `action`: a ticket action controller action
 
-{{{#!th
-type
-}}}
-{{{#!th
-name
-}}}
-{{{#!th
-doc-string/notes
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-!TicketNotificationSystem(Component)
-}}}
-{{{#!td
+== Old API
+''(since Trac 0.7, deprecated since Trac 1.1.3)''
 
-{{{#!th
-type
-}}}
-{{{#!th
-section
-}}}
-{{{#!th
-option name
-}}}
-{{{#!th
-default value
-}}}
-{{{#!th
-doc-string/notes
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-always_notify_owner
-}}}
-{{{#!td
-false
-}}}
-{{{#!td
-Always send notifications to the ticket owner (''since 0.9'').
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-always_notify_reporter
-}}}
-{{{#!td
-false
-}}}
-{{{#!td
-Always send notifications to any address in the ''reporter'' field.
-}}}
-|----------------
-{{{#!td
-!BoolOption
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-always_notify_updater
-}}}
-{{{#!td
-true
-}}}
-{{{#!td
-Always send notifications to the person who causes the ticket property change and to any previous updater of that ticket.
-}}}
-|----------------
-{{{#!td
-Option
-}}}
-{{{#!td
-notification
-}}}
-{{{#!td
-ticket_subject_template
-}}}
-{{{#!td
-'$prefix #$ticket.id: $summary'
-}}}
-{{{#!td
-A Genshi text template snippet used to get the notification subject.[[BR]]
-By default, the subject template is `$prefix #$ticket.id: $summary`. `$prefix` being the value of the `smtp_subject_prefix` option. ''(since 0.11)''
-}}}
+The original notification API consisted mainly of a class hierarchy:
+* `Notify` (abstract base class for notifications based on a plain text template)
+  * `NotifyEmail` (abstract base class for notifications via plain text email)
+    * `TicketNotifyEmail` (concrete class for ticket notification emails)
+    * `BatchTicketNotifyEmail` (concrete class for ticket batch modification notification emails)
 
-}}}
-|----------------
-{{{#!td colspan="3"
-}}}
-|----------------
-{{{#!td style="background: #efe"
-class
-}}}
-{{{#!td style="background: #efe"
-!TicketNotifyEmail(NotifyEmail)
-}}}
-{{{#!td
-Notification of ticket changes.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-{{{__init__}}}
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-notify
-}}}
-{{{#!td
-Send ticket change notification e-mail (untranslated)
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-_notify
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-format_props
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-parse_cc
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-diff_cc
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-format_hdr
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-format_subj
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-get_recipients
-}}}
-{{{#!td
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-get_message_id
-}}}
-{{{#!td
-Generate a predictable, but sufficiently unique message ID.
-}}}
-|----------------
-{{{#!td
-method
-}}}
-{{{#!td
-send
-}}}
-{{{#!td
-}}}
+In any situation that required sending notifications, a new instance of such a class was created, invoked once, and discarded. When invoked the object was responsible for finding the recipients, formatting the message and sending the email, all according to various configuration options.
 
-== Related information ==
-Trac plugins using '''!NotifyEmail''' (as of 25-Jul-2010)
- * [th:wiki:AccountManagerPlugin AccountManagerPlugin]
- * [th:wiki:DiscussionPlugin DiscussionPlugin]
- * ''[th:source:tracblplugin TracBLPlugin] looks unmaintained'', no wiki page
- * [th:wiki:ExoWebCodeReviewPlugin ExoWebCodeReviewPlugin]
- * [th:wiki:FullBlogNotificationPlugin]
- * [th:wiki:PrivateCommentPlugin PrivateCommentPlugin]
- * [th:wiki:WikiNotificationPlugin WikiNotificationPlugin]
+This API turned out to be too inflexible. There are too few extension points that would allow plugins to hook into this process. New subclasses could be defined to handle new situations, but existing code would still explicitly use the original `TicketNotifyEmail`. Strong inter-dependencies between the multiple levels of inheritance also make overriding certain things unexpectedly difficult.
 
-Trac plugins using '''!TicketNotifyEmail''' (as of 25-Jul-2010)
- * [th:wiki:AutoTracPlugin AutoTracPlugin]
- * [th:wiki:BasicFieldValidationPatch BasicFieldValidationPatch]
- * [th:wiki:EmailtoTracScript EmailtoTracScript]
- * [th:wiki:FlexibleReporterNotificationPlugin FlexibleReporterNotificationPlugin]
- * [th:wiki:GridModifyPlugin GridModifyPlugin]
- * [th:wiki:NeverNotifyUpdaterPlugin NeverNotifyUpdaterPlugin]
- * [th:wiki:PendingTicketPlugin PendingTicketPlugin]
- * [th:wiki:PerforceJobScript PerforceJobScript]
- * ''[th:wiki:PublishRevertPlugin PublishRevertPlugin] looks unmaintained''
- * [th:wiki:RepositoryHookSystemPlugin RepositoryHookSystemPlugin]
- * [th:wiki:RevtreePlugin RevtreePlugin]
- * ''[th:wiki:SvnCcHelpersScript SvnCcHelpersScript] unsupported''
- * ''[th:wiki:SvnChangeListenerPlugin SvnChangeListenerPlugin] depreciated''
- * [th:wiki:TaskListPlugin TaskListPlugin]
- * [th:wiki:TimingAndEstimationPlugin TimingAndEstimationPlugin]
- * [th:wiki:TracForgePlugin TracForgePlugin]
- * [th:wiki:WorkLogPlugin WorkLogPlugin]
- * [th:wiki:XmlRpcPlugin XmlRpcPlugin]
- * [th:wiki:AwesomeAttachmentsPlugin AwesomeAttachmentsPlugin]
- * [th:wiki:GridFlowPlugin GridFlowPlugin]
- * [th:wiki:InterTracCommitPatch InterTracCommitPatch]
- * [th:wiki:JiraToTracIntegration JiraToTracIntegration]
- * [th:wiki:MailToTracPlugin MailToTracPlugin]
- * [th:wiki:MilestoneTeamsPlugin MilestoneTeamsPlugin]
- * [th:wiki:TicketTeamDispatcherPlugin TicketTeamDispatcherPlugin]
- * [th:wiki:TracTicketChangesetsPlugin TracTicketChangesetsPlugin]
+The only extension point was `IEmailSender`, a low-level backend for sending an already finalized email. ''(Since Trac 0.12)''
+
+There was also a `NotificationSystem` component, mainly containing the various configuration option definitions.