22 | | === Processing mail from a third-party mailserver === |
23 | | If your Trac server lacks postfix and you want mail2trac to handle e-mail from a distinct server, you could use [http://fetchmail.berlios.de/ Fetchmail] to download the e-mails and process them with mail2trac. |
24 | | |
25 | | Example fetchmail command: |
26 | | |
27 | | {{{ |
28 | | fetchmail --protocol POP3 --port 110 --user [mailaccount] --mda "mail2trac -p /path/to/trac/environment" mailhost.domain.com |
29 | | }}} |
30 | | |
31 | | == Why not email2trac? == |
32 | | |
33 | | EmailtoTracScript is a more mature solution for converting email to Trac tickets. When building the GeoTicketPlugin, I was originally hoping to make use of the EmailtoTracScript to allow emails to specify a location in the subject header (see: source:geoticketplugin/0.11/geoticket/mail.py). When I realized the architecture would not easily support this, I thought of forking it, then realized that an implementation from scratch would actually better serve my needs. |
34 | | |
35 | | MailToTracPlugin offers: |
36 | | |
37 | | * a real pluggable architecture that allows arbitrary email handlers to be plugged in |
38 | | * POSTing to a URL to avoid complicated setuid issues with MTAs |
39 | | * outside of configuring postfix and MX records (always fun!) an easy installation |
40 | | |
41 | | While mail2trac is less mature, to the front-end user there shouldn't be considerable difference for the case of creating and responding to tickets. From a development point of view, I would recommend mail2trac over email2trac as a point to build on since a pluggable architecture was the point since the beginning. |
| 21 | == Use == |
| 22 | |
| 23 | === Permission === |
| 24 | mail2trac declare 4 permissions : |
| 25 | * MAIL2TICKET_COMMENT : user authorized to comment, |
| 26 | * MAIL2TICKET_PROPERTIES : user authorized to change properties (like 'owner', 'cc', etc ...), |
| 27 | * MAIL2TICKET_CREATE : user authorized to create a ticket |
| 28 | * MAIL2TICKET_ADMIN : all the above |
| 29 | |
| 30 | |
| 31 | In order to post ticket : |
| 32 | * the trac address must be correctly configured (Mr Obvious) |
| 33 | * you must have declared your mail address in your user preferences. |
| 34 | * have the correct permission according what you intend to do. |
| 35 | |
| 36 | === mail parsing === |
| 37 | |
| 38 | An email is parsed by mail2trac as following : |
| 39 | |
| 40 | * Header |
| 41 | * Subject field : |
| 42 | * if it begins by '''create :''' , mail2trac will create a ticket with the subject as summary (minus`create :`) |
| 43 | * if it contains '''#id_of_ticket''' (#42 for example), mail to trac will comment (and possibly update ticket fields) with the mail |
| 44 | * else it will be ignored |
| 45 | |
| 46 | * Body : |
| 47 | * any line begining with '''#field''' with field one of these : ''type'', ''priority'', ''milestone'', ''component'', ''version'', ''resolution'', ''keywords'', ''cc'', will be treated as request to change the 'field' property (work only with the MAIL2TICKET_PROPERTIES permission) |
| 48 | * mail2trac understand classic actions : resolve, reassign, accept and reopen(as in the classical web UI): |
| 49 | * '''#reassign : user''' , reassign to user |
| 50 | * '''#resolve : resolution''', The resolution will be set to resolution. Next status will be 'closed' |
| 51 | * '''#accept''' : Next status will be 'accepted' and owner fixe to yourself |
| 52 | * '''reopen''' : The resolution will be deleted. Next status will be 'reopened' |
| 53 | * for usability, few actions have an alias : |
| 54 | * '''#fixed''' is interpreted as '''#resolve:fixed''', |
| 55 | * '''#duplicate''' is interpreted as '''#resolve:duplicate'''', |
| 56 | * '''#wontfix''' is interpreted as '''#resolve:wontfix''', |
| 57 | * '''#invalid''' is interpreted as '''#resolve:invalid''', |
| 58 | * parsing will stop at the '''#end''' tag (meaning everything after #end will be ignore by mail2trac) |
| 59 | * any '''#field''' or '''#end''' will be ignore, and what's left is the ticket's description if you create, or the comment if you comment. |
| 60 | |
| 61 | |
| 62 | === An exemple === |
| 63 | |
| 64 | |
| 65 | |
| 66 | Creation : |
| 67 | |
| 68 | {{{ |
| 69 | From: Sender <sender@bearstech.com> |
| 70 | To: marvin_trac |
| 71 | Subject: create : exemple for mail2trac |
| 72 | |
| 73 | This ticket is an exemple for mail2trac. |
| 74 | (this is in fact the description of the ticket) |
| 75 | |
| 76 | we want a cc to jblondon, a component to component2 and a priority to |
| 77 | trivial. |
| 78 | |
| 79 | we can do that with #cc:jblondon, #component: component2 and #priority : |
| 80 | trivial . |
| 81 | (note that this instruction are not on the begining of a line and will |
| 82 | be seen as part of the description) |
| 83 | |
| 84 | #cc:jblondon |
| 85 | #component: component2 |
| 86 | #priority: trivial |
| 87 | |
| 88 | #end |
| 89 | the parsing stop here, this sentence will not be in the description |
| 90 | (note that instruction like #cc can have space anywhere) |
| 91 | }}} |
| 92 | |
| 93 | Trac answer : |
| 94 | |
| 95 | {{{ |
| 96 | |
| 97 | #42: exemple for mail2trac |
| 98 | -------------------------+---------------------- |
| 99 | Reporter: sender | Owner: somebody |
| 100 | Type: defect | Status: new |
| 101 | Priority: trivial | Milestone: |
| 102 | Component: component2 | Version: |
| 103 | Resolution: | Keywords: |
| 104 | -------------------------+---------------------- |
| 105 | This ticket is an exemple for mail2trac. |
| 106 | (this is in fact the description of the ticket) |
| 107 | |
| 108 | we want a cc to jdoe, a component to component2 and a priority to |
| 109 | trivial. |
| 110 | |
| 111 | we can do that with #cc:jdoe, #component: component2 and #priority : |
| 112 | trivial . |
| 113 | (note that this instruction are not on the begining of a line and will |
| 114 | be seen as part of the description) |
| 115 | |
| 116 | }}} |
| 117 | |
| 118 | we send : |
| 119 | |
| 120 | {{{ |
| 121 | From: Sender <sender@bearstech.com> |
| 122 | To: test <marvin_trac> |
| 123 | Subject: Re: [test] #42: exemple for mail2trac |
| 124 | |
| 125 | we reassign it to jdoe and change it's cc to nothing |
| 126 | |
| 127 | #reassign: jdoe |
| 128 | #cc: '' |
| 129 | |
| 130 | |
| 131 | #end |
| 132 | On 26/10/2011 15:03, test wrote: |
| 133 | > Date: Wed, 26 Oct 2011 15:03:57 -0000 |
| 134 | > From: test <marvin_trac> |
| 135 | > To: undisclosed-recipients: ; |
| 136 | > Subject: [test] #42: exemple for mail2trac |
| 137 | > X-Mailer: Trac 0.12.2, by Edgewall Software |
| 138 | > |
| 139 | > #42: exemple for mail2trac |
| 140 | > -------------------------+---------------------- |
| 141 | > Reporter: sender | Owner: somebody |
| 142 | > Type: defect | Status: new |
| 143 | > Priority: trivial | Milestone: |
| 144 | > Component: component2 | Version: |
| 145 | > Resolution: | Keywords: |
| 146 | > -------------------------+---------------------- |
| 147 | > This ticket is an exemple for mail2trac. |
| 148 | > (this is in fact the description of the ticket) |
| 149 | > |
| 150 | > we want a cc to jdoe, a component to component2 and a priority to |
| 151 | > trivial. |
| 152 | > |
| 153 | > we can do that with #cc:jdoe, #component: component2 and #priority : |
| 154 | > trivial . |
| 155 | > (note that this instruction are not on the begining of a line and will |
| 156 | > be seen as part of the description) |
| 157 | > |
| 158 | }}} |
| 159 | |
| 160 | |
| 161 | answer : |
| 162 | |
| 163 | {{{ |
| 164 | |
| 165 | |
| 166 | #42: exemple for mail2trac |
| 167 | -------------------------+---------------------- |
| 168 | Reporter: sender | Owner: jdoe |
| 169 | Type: defect | Status: assigned |
| 170 | Priority: trivial | Milestone: |
| 171 | Component: component2 | Version: |
| 172 | Resolution: | Keywords: |
| 173 | -------------------------+---------------------- |
| 174 | Changes (by sender): |
| 175 | |
| 176 | * cc: jdoe (removed) |
| 177 | * cc: '' (added) |
| 178 | * owner: somebody => jdoe |
| 179 | * status: new => assigned |
| 180 | |
| 181 | |
| 182 | Comment: |
| 183 | |
| 184 | we reassign it to jdoe and change it's cc to nothing |
| 185 | |
| 186 | }}} |
| 187 | |
| 188 | |
| 189 | we accept the ticket : |
| 190 | |
| 191 | {{{ |
| 192 | From: Sender <sender@bearstech.com> |
| 193 | To: test <marvin_trac> |
| 194 | Subject: Re: [test] #42: exemple for mail2trac |
| 195 | |
| 196 | in fact we want the ticket |
| 197 | #accept |
| 198 | |
| 199 | }}} |
| 200 | (note that end is not mandatory) |
| 201 | |
| 202 | answer : |
| 203 | |
| 204 | {{{ |
| 205 | #42: exemple for mail2trac |
| 206 | -------------------------+---------------------- |
| 207 | Reporter: sender | Owner: sender |
| 208 | Type: defect | Status: accepted |
| 209 | Priority: trivial | Milestone: |
| 210 | Component: component2 | Version: |
| 211 | Resolution: | Keywords: |
| 212 | -------------------------+---------------------- |
| 213 | Changes (by sender): |
| 214 | |
| 215 | * status: assigned => accepted |
| 216 | * owner: jdoe => sender |
| 217 | |
| 218 | |
| 219 | Comment: |
| 220 | |
| 221 | in fact we want the ticket |
| 222 | |
| 223 | }}} |
| 224 | |
| 225 | we close it : |
| 226 | |
| 227 | {{{ |
| 228 | From: Sender <sender@bearstech.com> |
| 229 | To: test <marvin_trac> |
| 230 | Subject: Re: [test] #42: exemple for mail2trac |
| 231 | |
| 232 | we close as fixed |
| 233 | #resolve: fixed |
| 234 | |
| 235 | #end |
| 236 | On 26/10/2011 15:14, test wrote: |
| 237 | > Date: Wed, 26 Oct 2011 15:14:31 -0000 |
| 238 | > From: test <marvin_trac> |
| 239 | > To: undisclosed-recipients: ; |
| 240 | > Subject: Re: [test] #42: exemple for mail2trac |
| 241 | > X-Mailer: Trac 0.12.2, by Edgewall Software |
| 242 | |
| 243 | |
| 244 | }}} |
| 245 | |
| 246 | trac say : |
| 247 | |
| 248 | {{{ |
| 249 | #42: exemple for mail2trac |
| 250 | -------------------------+-------------------- |
| 251 | Reporter: sender | Owner: sender |
| 252 | Type: defect | Status: closed |
| 253 | Priority: trivial | Milestone: |
| 254 | Component: component2 | Version: |
| 255 | Resolution: | Keywords: |
| 256 | -------------------------+-------------------- |
| 257 | Changes (by sender): |
| 258 | |
| 259 | * status: accepted => closed |
| 260 | |
| 261 | |
| 262 | Comment: |
| 263 | |
| 264 | we close as fixed |
| 265 | }}} |
| 266 | |
| 267 | |
| 268 | we reopen : |
| 269 | {{{ |
| 270 | From: Sender <sender@bearstech.com> |
| 271 | To: test <marvin_trac> |
| 272 | Subject: Re: [test] #42: exemple for mail2trac |
| 273 | |
| 274 | Arf, no it's not done, i reopen |
| 275 | #reopen |
| 276 | |
| 277 | }}} |
| 278 | |
| 279 | we get : |
| 280 | |
| 281 | {{{ |
| 282 | #42: exemple for mail2trac |
| 283 | -------------------------+---------------------- |
| 284 | Reporter: sender | Owner: sender |
| 285 | Type: defect | Status: reopened |
| 286 | Priority: trivial | Milestone: |
| 287 | Component: component2 | Version: |
| 288 | Resolution: | Keywords: |
| 289 | -------------------------+---------------------- |
| 290 | Changes (by sender): |
| 291 | |
| 292 | * status: closed => reopened |
| 293 | |
| 294 | |
| 295 | Comment: |
| 296 | |
| 297 | Arf, no it's not done, i reopen |
| 298 | |
| 299 | }}} |
| 300 | |
| 301 | |
| 302 | |
| 303 | |
| 304 | we close it again |
| 305 | |
| 306 | {{{ |
| 307 | From: Sender <sender@bearstech.com> |
| 308 | To: test <marvin_trac> |
| 309 | Subject: Re: [test] #42: exemple for mail2trac |
| 310 | |
| 311 | resolve as invalid, but instead of #resolve: invalid we use the alias #invalid |
| 312 | #invalid |
| 313 | }}} |
| 314 | |
| 315 | and finally this very usefull ticket is closed : |
| 316 | |
| 317 | {{{ |
| 318 | #42: exemple for mail2trac |
| 319 | -------------------------+-------------------- |
| 320 | Reporter: sender | Owner: sender |
| 321 | Type: defect | Status: closed |
| 322 | Priority: trivial | Milestone: |
| 323 | Component: component2 | Version: |
| 324 | Resolution: | Keywords: |
| 325 | -------------------------+-------------------- |
| 326 | Changes (by sender): |
| 327 | |
| 328 | * status: reopened => closed |
| 329 | |
| 330 | |
| 331 | Comment: |
| 332 | |
| 333 | resolve as invalid, but instead of #resolve: invalid we use the alias |
| 334 | #invalid |
| 335 | |
| 336 | }}} |
| 337 | |
| 338 | |