| 4 | | Trac supports notification of ticket changes via email. |
| 5 | | |
| 6 | | Email notification is useful to keep users up-to-date on tickets/issues of interest, and also provides a convenient way to post all ticket changes to a dedicated mailing list. For example, this is how the [http://lists.edgewall.com/archive/trac-tickets/ Trac-tickets] mailing list is set up. |
| 7 | | |
| 8 | | Disabled by default, notification can be activated and configured in [wiki:TracIni trac.ini]. |
| 9 | | |
| 10 | | == Receiving Notification Mails == |
| 11 | | When 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 will automatically send you an email when changes are made to the ticket, depending on how notification is configured. |
| 12 | | |
| 13 | | === How to use your username to receive notification mails === |
| 14 | | |
| 15 | | To 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 the ''Preferences'' page. |
| | 4 | Trac supports notification of ticket changes via email. |
| | 5 | |
| | 6 | Email 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. |
| | 7 | |
| | 8 | Disabled by default, notification can be activated and configured in [TracIni trac.ini]. |
| | 9 | |
| | 10 | == Receiving Notification Mails |
| | 11 | When 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. |
| | 12 | |
| | 13 | Permission groups can also be entered in the CC field, |
| | 14 | to notify all members of the group. |
| | 15 | |
| | 16 | === How to use your username to receive notification mails |
| | 17 | |
| | 18 | To 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]. |
| 59 | | === Customizing the e-mail subject === |
| 60 | | The e-mail subject can be customized with the `ticket_subject_template` option, which contains a [http://genshi.edgewall.org/wiki/Documentation/text-templates.html Genshi text template] snippet. The default value is: |
| 61 | | {{{ |
| 62 | | $prefix #$ticket.id: $summary |
| | 62 | === Subscriber Configuration |
| | 63 | The default subscriptions are configured in the [TracIni#notification-subscriber-section "[notification-subscriber]"] section. |
| | 64 | |
| | 65 | [[TracIni(section=notification-subscriber)]] |
| | 66 | |
| | 67 | Each user can override these defaults in their ''Notifications'' preferences. |
| | 68 | |
| | 69 | For 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. |
| | 70 | |
| | 71 | The 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. |
| | 72 | |
| | 73 | The following attributes of default subscriptions can be configured: |
| | 74 | * `.distributor` (Default: `email`) |
| | 75 | * Other values require plugins. For example `on-site` requires th:OnSiteNotificationsPlugin. |
| | 76 | * `.priority` (Default: `100`) |
| | 77 | * Smaller values override larger values. |
| | 78 | * If you use `0`, then users will not be able to override this rule. |
| | 79 | * `.adverb` (Default: `always`) |
| | 80 | * `never` can be used to silence other subscription rules with higher values. |
| | 81 | * `.format` (Default: `text/plain`) |
| | 82 | * Other values require plugins. For example `text/html` requires th:TracHtmlNotificationPlugin. |
| | 83 | |
| | 84 | === Example Configuration (default subscriptions) |
| | 85 | {{{#!ini |
| | 86 | [notification-subscriber] |
| | 87 | always_notify_owner = TicketOwnerSubscriber |
| | 88 | always_notify_owner.distributor = email |
| | 89 | always_notify_owner.priority = 100 |
| | 90 | always_notify_owner.adverb = always |
| | 91 | always_notify_owner.format = text/plain |
| | 92 | |
| | 93 | always_notify_previous_updater = TicketPreviousUpdatersSubscriber |
| | 94 | |
| | 95 | never_notify_updater = TicketUpdaterSubscriber |
| | 96 | never_notify_updater.adverb = never |
| | 97 | never_notify_updater.priority = 0 |
| | 98 | |
| | 99 | notify_cc_html = CarbonCopySubscriber |
| | 100 | notify_cc_html.format = text/html |
| | 101 | }}} |
| | 102 | |
| | 103 | === Customizing the email subject |
| | 104 | The 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: |
| | 105 | {{{#!genshi |
| | 106 | ${prefix} #${ticket.id}: ${summary} |
| 136 | | == Customizing e-mail content for MS Outlook == |
| 137 | | |
| 138 | | MS Outlook normally presents plain text e-mails with a variable-width font, and as a result the ticket properties table will most certainly look like a mess in MS Outlook. This can be fixed with some customization of the [#Customizingthee-mailcontent e-mail template]. |
| 139 | | |
| 140 | | Replace the following second row in the template: |
| 141 | | {{{ |
| 142 | | $ticket_props |
| 143 | | }}} |
| 144 | | |
| 145 | | with this (requires Python 2.6 or later): |
| 146 | | {{{ |
| 147 | | -------------------------------------------------------------------------- |
| 148 | | {% with |
| 149 | | pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in |
| 150 | | [c.strip() for c in |
| 151 | | ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]]; |
| 152 | | sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone', |
| 153 | | 'Component', 'Severity', 'Resolution', 'Keywords'] %}\ |
| 154 | | ${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)} |
| 155 | | {% end %}\ |
| 156 | | -------------------------------------------------------------------------- |
| 157 | | }}} |
| 158 | | |
| 159 | | The table of ticket properties is replaced with a list of a selection of the properties. A tab character separates the name and value in such a way that most people should find this more pleasing than the default table when using MS Outlook. |
| 160 | | {{{#!div style="margin: 1em 1.75em; border:1px dotted" |
| 161 | | {{{#!html |
| 162 | | #42: testing<br /> |
| 163 | | --------------------------------------------------------------------------<br /> |
| 164 | | <table cellpadding=0> |
| 165 | | <tr><td>Reporter:</td><td>[email protected]</td></tr> |
| 166 | | <tr><td>Owner:</td><td>anonymous</td></tr> |
| 167 | | <tr><td>Type:</td><td>defect</td></tr> |
| 168 | | <tr><td>Status:</td><td>assigned</td></tr> |
| 169 | | <tr><td>Priority:</td><td>lowest</td></tr> |
| 170 | | <tr><td>Milestone:</td><td>0.9</td></tr> |
| 171 | | <tr><td>Component:</td><td>report system</td></tr> |
| 172 | | <tr><td>Severity:</td><td>major</td></tr> |
| 173 | | <tr><td>Resolution:</td><td> </td></tr> |
| 174 | | <tr><td>Keywords:</td><td> </td></tr> |
| 175 | | </table> |
| 176 | | --------------------------------------------------------------------------<br /> |
| 177 | | Changes:<br /> |
| 178 | | <br /> |
| 179 | | * component: changeset view => search system<br /> |
| 180 | | * priority: low => highest<br /> |
| 181 | | * owner: jonas => anonymous<br /> |
| 182 | | * cc: [email protected] =><br /> |
| 183 | | [email protected], [email protected]<br /> |
| 184 | | * status: new => assigned<br /> |
| 185 | | <br /> |
| 186 | | Comment:<br /> |
| 187 | | I'm interested too!<br /> |
| 188 | | <br /> |
| 189 | | --<br /> |
| 190 | | Ticket URL: <http://example.com/trac/ticket/42><br /> |
| 191 | | My Project <http://myproj.example.com/><br /> |
| 192 | | }}} |
| 193 | | }}} |
| 194 | | |
| 195 | | **Important**: Only those ticket fields that are listed in `sel` are part of the HTML mail. If you have defined custom ticket fields which are to be part of the mail, then they have to be added to `sel`. Example: |
| 196 | | {{{ |
| 197 | | sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2'] |
| 198 | | }}} |
| 199 | | |
| 200 | | However, the solution is still a workaround to an automatically HTML-formatted e-mail. |
| 201 | | |
| 202 | | == Using GMail as the SMTP relay host == |
| | 180 | == Using GMail as the SMTP relay host |
| 220 | | |
| 221 | | == Filtering notifications for one's own changes and comments == |
| 222 | | In Gmail, use the filter: |
| 223 | | {{{ |
| 224 | | from:(<smtp_from>) (("Reporter: <username>" -Changes -Comment) OR "Changes (by <username>)" OR "Comment (by <username>)") |
| 225 | | }}} |
| 226 | | |
| 227 | | to delete these notifications. |
| 228 | | |
| 229 | | In Thunderbird, there is no such solution if you use IMAP, see http://kb.mozillazine.org/Filters_(Thunderbird)#Filtering_the_message_body. |
| 230 | | |
| 231 | | You can also add this plugin: |
| 232 | | http://trac-hacks.org/wiki/NeverNotifyUpdaterPlugin, or vote for [trac:#2247] to be fixed. |
| 233 | | |
| 234 | | == Troubleshooting == |
| 235 | | |
| 236 | | If you cannot get the notification working, first make sure the log is activated and have a look at the log to find if an error message has been logged. See TracLogging for help about the log feature. |
| 237 | | |
| 238 | | Notification errors are not reported through the web interface, so the user who submits a change or a new ticket never gets notified about a notification failure. The Trac administrator needs to look at the log to find the error trace. |
| 239 | | |
| 240 | | === ''Permission denied'' error === |
| | 198 | |
| | 199 | == Troubleshooting |
| | 200 | |
| | 201 | If notifications are not working, inspect the [TracLogging log] for error messages. |
| | 202 | |
| | 203 | Notification 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. |
| | 204 | |
| | 205 | === ''Permission denied'' error |
