Edgewall Software

Changes between Initial Version and Version 108 of TracNotification

(multiple changes)
(multiple changes)
(multiple changes)


  • TracNotification

    v1 v108  
     1= Email Notification of Ticket Changes
     5Trac supports notification of ticket changes via email.
     7Email notification is useful to keep users up-to-date on tickets of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list.
     9Disabled by default, notification can be activated and configured in [TracIni trac.ini].
     11== Receiving Notification Mails
     12When reporting a new ticket or adding a comment, enter a valid email address or your Trac username in the ''reporter'', ''assigned to/owner'' or ''cc'' field. Trac may send you an email when changes are made to the ticket, depending on how your notification preferences are configured.
     14Permission groups can also be entered in the CC field,
     15to notify all members of the group.
     17=== How to use your username to receive notification mails
     19To receive notification mails, you can either enter a full email address or your Trac username. To get notified with a simple username or login, you need to specify a valid email address in your [/prefs preferences].
     21Alternatively, a default domain name ('''`smtp_default_domain`''') can be set in the TracIni file, see [#ConfigurationOptions Configuration Options] below. In this case, the default domain will be appended to the username, which can be useful for an "Intranet" kind of installation.
     23When using apache and mod_kerb for authentication against Kerberos / Active Directory, usernames take the form ('''`username@EXAMPLE.LOCAL`'''). To avoid this being interpreted as an email address, add the Kerberos domain to  ('''`ignore_domains`''').
     25=== Ticket attachment notifications
     27Since 1.0.3 Trac will send notifications when a ticket attachment is added or deleted. Usually attachment notifications will be enabled in an environment by default. To disable the attachment notifications for an environment the `TicketAttachmentNotifier` component must be disabled:
     30trac.ticket.notification.TicketAttachmentNotifier = disabled
     33== Configuring SMTP Notification
     35'''Important:''' The [[TracIni#trac-base_url-option|[trac] base_url]] option must be configured for links in the notification message to be correctly generated.
     37=== Configuration Options
     38These are the available options for the `[notification]` section in trac.ini:
     42=== Example Configuration (SMTP)
     45smtp_enabled = true
     46smtp_server = mail.example.com
     47smtp_from = notifier@example.com
     48smtp_replyto = myproj@projects.example.com
     49smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
     52=== Example Configuration (`sendmail`)
     55smtp_enabled = true
     56email_sender = SendmailEmailSender
     57sendmail_path = /usr/sbin/sendmail
     58smtp_from = notifier@example.com
     59smtp_replyto = myproj@projects.example.com
     60smtp_always_cc = ticketmaster@example.com, theboss+myproj@example.com
     63=== Subscriber Configuration
     64The default subscriptions are configured in the [TracIni#notification-subscriber-section "[notification-subscriber]"] section.
     68Each user can override these defaults in their ''Notifications'' preferences.
     70For example to unsubscribe from notifications for one's own changes and comments, the rule "Never notify: I update a ticket" should be added above other subscription rules.
     72The subscription rule name on the left side of the `=` can be anything, it has no meaning outside this configuration file. The subscriber name on the right side of the `=` must be one of the subscribers listed in the above table.
     74The following attributes of default subscriptions can be configured:
     75* `.distributor` (Default: `email`)
     76  * Other values require plugins. For example `on-site` requires th:OnSiteNotificationsPlugin.
     77* `.priority` (Default: `100`)
     78  * Smaller values override larger values.
     79  * If you use `0`, then users will not be able to override this rule.
     80* `.adverb` (Default: `always`)
     81  * `never` can be used to silence other subscription rules with higher values.
     82* `.format` (Default: `text/plain`)
     83  * Other values require plugins. For example `text/html` requires th:TracHtmlNotificationPlugin.
     85=== Example Configuration (default subscriptions)
     87This example implements the often desired
     88//Never Notify Updater// behavior by setting
     89the priority of that rule to the highest value,
     90thereby taking precedence over other rules.
     94always_notify_owner = TicketOwnerSubscriber
     95always_notify_owner.distributor = email
     96always_notify_owner.priority = 100
     97always_notify_owner.adverb = always
     98always_notify_owner.format = text/plain
     100always_notify_previous_updater = TicketPreviousUpdatersSubscriber
     102never_notify_updater = TicketUpdaterSubscriber
     103never_notify_updater.adverb = never
     104never_notify_updater.priority = 0
     106notify_cc_html = CarbonCopySubscriber
     107notify_cc_html.format = text/html
     110=== Customizing the email subject
     111The email subject can be customized with the `ticket_subject_template` option, which contains a [https://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is:
     113${prefix} #${ticket.id}: ${summary}
     115The following variables are available in the template:
     117 * `changes`: The ticket changes (prepared by [trac:source:/branches/1.4-stable/trac/ticket/model.py Ticket.get_change]).
     118 * `env`: The project environment (see [trac:source:/branches/1.4-stable/trac/env.py env.py]).
     119 * `prefix`: The prefix defined in `smtp_subject_prefix`.
     120 * `summary`: The ticket summary, with the old value if the summary was edited.
     121 * `ticket`: The ticket model object (see [trac:source:/branches/1.4-stable/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg `${ticket.milestone}`.
     123=== Customizing the email content #CustomizingContent
     125The notification email content is generated based on `ticket_notify_email.txt` in `trac/ticket/templates`. You can add your own version of this template by adding a `ticket_notify_email.txt` to the templates directory of your environment. The default is:
     130# if ticket.new:
     132# else:
     133#   if changes_body:
     134${_('Changes (by %(author)s):', author=change.author)}
     137#   endif
     138#   if changes_descr:
     139#     if not changes_body and not change.comment and change.author:
     140${_('Description changed by %(author)s:', author=change.author)}
     141#     endif
     144#   endif
     145#   if change.comment:
     147${_('Comment:') if changes_body else
     148  _('Comment (by %(author)s):', author=change.author)}
     151#   endif
     152# endif
     153${'-- '}
     154${_('Ticket URL: <%(link)s>', link=ticket.link)}
     155${project.name} <${project.url or abs_href()}>
     159See the [trac:CookBook/Notification/Templates cookbook] for additional template customization recipes.
     161== Sample Email
     163#42: testing
     165       Id:  42             |      Status:  assigned
     166Component:  report system  |    Modified:  Fri Apr  9 00:04:31 2004
     167 Severity:  major          |   Milestone:  0.9
     168 Priority:  lowest         |     Version:  0.6
     169    Owner:  anonymous      |    Reporter:  jonas@example.com
     172  * component:  changeset view => search system
     173  * priority:  low => highest
     174  * owner:  jonas => anonymous
     175  * cc:  daniel@example.com =>
     176         daniel@example.com, jonas@example.com
     177  * status:  new => assigned
     180I'm interested too!
     183Ticket URL: <http://example.com/trac/ticket/42>
     184My Project <http://myproj.example.com/>
     187== Using GMail as the SMTP relay host
     189Use the following configuration snippet:
     192smtp_enabled = true
     193use_tls = true
     194mime_encoding = base64
     195smtp_server = smtp.gmail.com
     196smtp_port = 587
     197smtp_user = user
     198smtp_password = password
     201where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [https://gmail.com].
     203Alternatively, you can use `smtp_port = 25`.[[br]]
     204You should not use `smtp_port = 465`. Doing so may deadlock your ticket submission. Port 465 is reserved for the SMTPS protocol, which is not supported by Trac. See [trac:comment:2:ticket:7107 #7107] for details.
     206== Troubleshooting
     208If notifications are not working, inspect the [TracLogging log] for error messages.
     210Notification errors are not always reported through the web interface, so the user who submits a change or creates a ticket may not get notified about a notification failure. The Trac administrator needs to look at the log to find the error message and traceback.
     212=== ''Permission denied'' error
     214Typical error message:
     216  ...
     217  File ".../smtplib.py", line 303, in connect
     218    raise socket.error, msg
     219  error: (13, 'Permission denied')
     222This error usually comes from a security settings on the server: many Linux distributions do not allow the web server (Apache, ...) to post email messages to the local SMTP server.
     224Many users get confused when their manual attempts to contact the SMTP server succeed:
     226telnet localhost 25
     228This is because a regular user may connect to the SMTP server, but the web server cannot:
     230sudo -u www-data telnet localhost 25
     233In such a case, you need to configure your server so that the web server is authorized to post to the SMTP server. The actual settings depend on your Linux distribution and current security policy. You may find help in the Trac [trac:MailingList MailingList] archive.
     235Relevant ML threads:
     236 * SELinux: http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/7518
     238For SELinux in Fedora 10:
     240$ setsebool -P httpd_can_sendmail 1
     243=== ''Suspected spam'' error
     245Some SMTP servers may reject the notification email sent by Trac.
     247The default Trac configuration uses Base64 encoding to send emails to the recipients. The whole body of the email is encoded, which sometimes trigger ''false positive'' spam detection on sensitive email servers. In such an event, change the default encoding to "quoted-printable" using the `mime_encoding` option.
     249Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding.
     252See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]