| 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]. |
| | 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]. |
| 63 | | === Customizing the e-mail subject |
| 64 | | |
| 65 | | 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: |
| 66 | | {{{ |
| 67 | | $prefix #$ticket.id: $summary |
| 68 | | }}} |
| 69 | | |
| | 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 [https://trac-hacks.org/wiki/OnSiteNotificationsPlugin 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 [https://trac-hacks.org/wiki/TracHtmlNotificationPlugin TracHtmlNotificationPlugin]. |
| | 83 | |
| | 84 | === Example Configuration (default subscriptions) |
| | 85 | |
| | 86 | This example implements the often desired |
| | 87 | //Never Notify Updater// behavior by setting |
| | 88 | the priority of that rule to the highest value, |
| | 89 | thereby taking precedence over other rules. |
| | 90 | |
| | 91 | {{{#!ini |
| | 92 | [notification-subscriber] |
| | 93 | always_notify_owner = TicketOwnerSubscriber |
| | 94 | always_notify_owner.distributor = email |
| | 95 | always_notify_owner.priority = 100 |
| | 96 | always_notify_owner.adverb = always |
| | 97 | always_notify_owner.format = text/plain |
| | 98 | |
| | 99 | always_notify_previous_updater = TicketPreviousUpdatersSubscriber |
| | 100 | |
| | 101 | never_notify_updater = TicketUpdaterSubscriber |
| | 102 | never_notify_updater.adverb = never |
| | 103 | never_notify_updater.priority = 0 |
| | 104 | |
| | 105 | notify_cc_html = CarbonCopySubscriber |
| | 106 | notify_cc_html.format = text/html |
| | 107 | }}} |
| | 108 | |
| | 109 | === Customizing the email subject |
| | 110 | 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: |
| | 111 | {{{#!genshi |
| | 112 | ${prefix} #${ticket.id}: ${summary} |
| | 113 | }}} |
| 75 | | * `ticket`: The ticket model object (see [trac:source:/trunk/trac/ticket/model.py model.py]). Individual ticket fields can be addressed by appending the field name separated by a dot, eg `$ticket.milestone`. |
| 76 | | |
| 77 | | === Customizing the e-mail content |
| 78 | | |
| 79 | | The notification e-mail 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 looks like this: |
| 80 | | |
| 81 | | {{{ |
| 82 | | $ticket_body_hdr |
| 83 | | $ticket_props |
| 84 | | {% choose ticket.new %}\ |
| 85 | | {% when True %}\ |
| 86 | | $ticket.description |
| 87 | | {% end %}\ |
| 88 | | {% otherwise %}\ |
| 89 | | {% if changes_body %}\ |
| | 120 | * `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}`. |
| | 121 | |
| | 122 | === Customizing the email content #CustomizingContent |
| | 123 | |
| | 124 | The 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: |
| | 125 | |
| | 126 | {{{#!jinja |
| | 127 | ${ticket_body_hdr} |
| | 128 | ${ticket_props} |
| | 129 | # if ticket.new: |
| | 130 | ${ticket.description} |
| | 131 | # else: |
| | 132 | # if changes_body: |
| 143 | | == Customizing e-mail content for MS Outlook |
| 144 | | |
| 145 | | 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]. |
| 146 | | |
| 147 | | Replace the following second row in the template: |
| 148 | | {{{ |
| 149 | | $ticket_props |
| 150 | | }}} |
| 151 | | |
| 152 | | with this (requires Python 2.6 or later): |
| 153 | | {{{ |
| 154 | | -------------------------------------------------------------------------- |
| 155 | | {% with |
| 156 | | pv = [(a[0].strip(), a[1].strip()) for a in [b.split(':') for b in |
| 157 | | [c.strip() for c in |
| 158 | | ticket_props.replace('|', '\n').splitlines()[1:-1]] if ':' in b]]; |
| 159 | | sel = ['Reporter', 'Owner', 'Type', 'Status', 'Priority', 'Milestone', |
| 160 | | 'Component', 'Severity', 'Resolution', 'Keywords'] %}\ |
| 161 | | ${'\n'.join('%s\t%s' % (format(p[0]+':', ' <12'), p[1]) for p in pv if p[0] in sel)} |
| 162 | | {% end %}\ |
| 163 | | -------------------------------------------------------------------------- |
| 164 | | }}} |
| 165 | | |
| 166 | | 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. |
| 167 | | {{{#!div style="margin: 1em 1.75em; border:1px dotted" |
| 168 | | {{{#!html |
| 169 | | #42: testing<br /> |
| 170 | | --------------------------------------------------------------------------<br /> |
| 171 | | <table cellpadding=0> |
| 172 | | <tr><td>Reporter:</td><td>jonas@example.com</td></tr> |
| 173 | | <tr><td>Owner:</td><td>anonymous</td></tr> |
| 174 | | <tr><td>Type:</td><td>defect</td></tr> |
| 175 | | <tr><td>Status:</td><td>assigned</td></tr> |
| 176 | | <tr><td>Priority:</td><td>lowest</td></tr> |
| 177 | | <tr><td>Milestone:</td><td>0.9</td></tr> |
| 178 | | <tr><td>Component:</td><td>report system</td></tr> |
| 179 | | <tr><td>Severity:</td><td>major</td></tr> |
| 180 | | <tr><td>Resolution:</td><td> </td></tr> |
| 181 | | <tr><td>Keywords:</td><td> </td></tr> |
| 182 | | </table> |
| 183 | | --------------------------------------------------------------------------<br /> |
| 184 | | Changes:<br /> |
| 185 | | <br /> |
| 186 | | * component: changeset view => search system<br /> |
| 187 | | * priority: low => highest<br /> |
| 188 | | * owner: jonas => anonymous<br /> |
| 189 | | * cc: daniel@example.com =><br /> |
| 190 | | daniel@example.com, jonas@example.com<br /> |
| 191 | | * status: new => assigned<br /> |
| 192 | | <br /> |
| 193 | | Comment:<br /> |
| 194 | | I'm interested too!<br /> |
| 195 | | <br /> |
| 196 | | --<br /> |
| 197 | | Ticket URL: <http://example.com/trac/ticket/42><br /> |
| 198 | | My Project <http://myproj.example.com/><br /> |
| 199 | | }}} |
| 200 | | }}} |
| 201 | | |
| 202 | | **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: |
| 203 | | {{{ |
| 204 | | sel = ['Reporter', ..., 'Keywords', 'Custom1', 'Custom2'] |
| 205 | | }}} |
| 206 | | |
| 207 | | However, the solution is still a workaround to an automatically HTML-formatted e-mail. |
| 208 | | |
| 242 | | 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. |
| 243 | | |
| 244 | | 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. |
| 245 | | |
| 246 | | === ''Permission denied'' error |
| | 207 | If notifications are not working, inspect the [TracLogging log] for error messages. |
| | 208 | |
| | 209 | 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. |
| | 210 | |
| | 211 | === Permission denied error |
