Edgewall Software

Changes between Initial Version and Version 108 of TracNotification


Ignore:
Timestamp:
(multiple changes)
Author:
(multiple changes)
Comment:
(multiple changes)

Legend:

Unmodified
Added
Removed
Modified
  • TracNotification

    v1 v108  
     1= Email Notification of Ticket Changes
     2[[TracGuideToc]]
     3[[TranslatedPages]]
     4
     5Trac supports notification of ticket changes via email.
     6
     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.
     8
     9Disabled by default, notification can be activated and configured in [TracIni trac.ini].
     10
     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.
     13
     14Permission groups can also be entered in the CC field,
     15to notify all members of the group.
     16
     17=== How to use your username to receive notification mails
     18
     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].
     20
     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.
     22
     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`''').
     24
     25=== Ticket attachment notifications
     26
     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:
     28{{{#!ini
     29[components]
     30trac.ticket.notification.TicketAttachmentNotifier = disabled
     31}}}
     32
     33== Configuring SMTP Notification
     34
     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.
     36
     37=== Configuration Options
     38These are the available options for the `[notification]` section in trac.ini:
     39
     40[[TracIni(section=notification)]]
     41
     42=== Example Configuration (SMTP)
     43{{{#!ini
     44[notification]
     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
     50}}}
     51
     52=== Example Configuration (`sendmail`)
     53{{{#!ini
     54[notification]
     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
     61}}}
     62
     63=== Subscriber Configuration
     64The default subscriptions are configured in the [TracIni#notification-subscriber-section "[notification-subscriber]"] section.
     65
     66[[TracIni(section=notification-subscriber)]]
     67
     68Each user can override these defaults in their ''Notifications'' preferences.
     69
     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.
     71
     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.
     73
     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.
     84
     85=== Example Configuration (default subscriptions)
     86
     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.
     91
     92{{{#!ini
     93[notification-subscriber]
     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
     99
     100always_notify_previous_updater = TicketPreviousUpdatersSubscriber
     101
     102never_notify_updater = TicketUpdaterSubscriber
     103never_notify_updater.adverb = never
     104never_notify_updater.priority = 0
     105
     106notify_cc_html = CarbonCopySubscriber
     107notify_cc_html.format = text/html
     108}}}
     109
     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:
     112{{{#!genshi
     113${prefix} #${ticket.id}: ${summary}
     114}}}
     115The following variables are available in the template:
     116
     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}`.
     122
     123=== Customizing the email content #CustomizingContent
     124
     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:
     126
     127{{{#!jinja
     128${ticket_body_hdr}
     129${ticket_props}
     130# if ticket.new:
     131${ticket.description}
     132# else:
     133#   if changes_body:
     134${_('Changes (by %(author)s):', author=change.author)}
     135
     136${changes_body}
     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
     142${changes_descr}
     143--
     144#   endif
     145#   if change.comment:
     146
     147${_('Comment:') if changes_body else
     148  _('Comment (by %(author)s):', author=change.author)}
     149
     150${change.comment}
     151#   endif
     152# endif
     153${'-- '}
     154${_('Ticket URL: <%(link)s>', link=ticket.link)}
     155${project.name} <${project.url or abs_href()}>
     156${project.descr}
     157}}}
     158
     159See the [trac:CookBook/Notification/Templates cookbook] for additional template customization recipes.
     160
     161== Sample Email
     162{{{
     163#42: testing
     164---------------------------+------------------------------------------------
     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
     170---------------------------+------------------------------------------------
     171Changes:
     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
     178
     179Comment:
     180I'm interested too!
     181
     182--
     183Ticket URL: <http://example.com/trac/ticket/42>
     184My Project <http://myproj.example.com/>
     185}}}
     186
     187== Using GMail as the SMTP relay host
     188
     189Use the following configuration snippet:
     190{{{#!ini
     191[notification]
     192smtp_enabled = true
     193use_tls = true
     194mime_encoding = base64
     195smtp_server = smtp.gmail.com
     196smtp_port = 587
     197smtp_user = user
     198smtp_password = password
     199}}}
     200
     201where ''user'' and ''password'' match an existing GMail account, ie the ones you use to log in on [https://gmail.com].
     202
     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.
     205
     206== Troubleshooting
     207
     208If notifications are not working, inspect the [TracLogging log] for error messages.
     209
     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.
     211
     212=== ''Permission denied'' error
     213
     214Typical error message:
     215{{{#!sh
     216  ...
     217  File ".../smtplib.py", line 303, in connect
     218    raise socket.error, msg
     219  error: (13, 'Permission denied')
     220}}}
     221
     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.
     223
     224Many users get confused when their manual attempts to contact the SMTP server succeed:
     225{{{#!sh
     226telnet localhost 25
     227}}}
     228This is because a regular user may connect to the SMTP server, but the web server cannot:
     229{{{#!sh
     230sudo -u www-data telnet localhost 25
     231}}}
     232
     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.
     234
     235Relevant ML threads:
     236 * SELinux: http://article.gmane.org/gmane.comp.version-control.subversion.trac.general/7518
     237
     238For SELinux in Fedora 10:
     239{{{#!sh
     240$ setsebool -P httpd_can_sendmail 1
     241}}}
     242
     243=== ''Suspected spam'' error
     244
     245Some SMTP servers may reject the notification email sent by Trac.
     246
     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.
     248
     249Quoted printable encoding works better with languages that use one of the Latin charsets. For Asian charsets, stick with the Base64 encoding.
     250
     251----
     252See also: TracTickets, TracIni, TracGuide, [trac:TracDev/NotificationApi]