Changes between Version 9 and Version 10 of MailToTracPlugin


Ignore:
Timestamp:
Nov 2, 2011, 4:15:48 PM (12 years ago)
Author:
Olivier ANDRE
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MailToTracPlugin

    v9 v10  
    11= Pluggable email handler for Trac =
    2 
    32== Description ==
    43
    5 provides a command line script and extension point that allows email messages to be handled by Trac plugins.  This ticket provides a command-line script, `mail2trac` which may be called by an [http://en.wikipedia.org/wiki/Mail_transfer_agent MTA] (e.g. [http://www.postfix.org/ postfix]) to open a Trac environment and run through each enabled [source:mailtotracplugin/0.11/mail2trac/interface.py IEmailHandler] and executes its `invoke()` method if its `match()` method returns `True`.  If invoke returns an [http://docs.python.org/library/email email] message, then subsequent `IEmailHandler`s will also process the message.  If `None` is returned, then the message is consumed and execution stops.
     4provides a trac-admin command, a bash script (mail2tracAdmin) calling trac-admin and extension point that allows email messages to be handled by Trac plugins.  The bash script, `mail2tracAdmin` which may be called by an [http://en.wikipedia.org/wiki/Mail_transfer_agent MTA] (e.g. [http://www.postfix.org/ postfix]) to open a Trac environment and run through each enabled [source:mailtotracplugin/0.11/mail2trac/interface.py IEmailHandler] and executes its `invoke()` method if its `match()` method returns `True`.  If invoke returns an [http://docs.python.org/library/email email] message, then subsequent `IEmailHandler`s will also process the message.  If `None` is returned, then the message is consumed and execution stops.
    65
    76To enable the plugin for `postfix`, add an appropriate line to the aliases file (usually `/etc/aliases` or `/etc/postfix/aliases` and then refreshing the aliases database (see [http://www.postfix.org/aliases.5.html man aliases]).  The `mail2trac` script takes a `-p` command line argument for the path to the project environment.  The incoming email address should equal
    … …  
    2019}}}
    2120
    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 ===
     24mail2trac 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
     31In 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
     38An 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
     66Creation :
     67
     68{{{
     69From: Sender <sender@bearstech.com>
     70To: marvin_trac
     71Subject: create : exemple for mail2trac
     72
     73This ticket is an exemple for mail2trac.
     74(this is in fact the description of the ticket)
     75
     76we want a cc to jblondon, a component to component2 and a priority to
     77trivial.
     78
     79we can do that with #cc:jblondon, #component: component2 and #priority :
     80trivial .
     81(note that this instruction are not on the begining of a line and will
     82be seen as part of the description)
     83
     84 #cc:jblondon
     85#component: component2
     86  #priority: trivial
     87
     88#end
     89the parsing stop here, this sentence will not be in the description
     90(note that instruction like #cc can have space anywhere)
     91}}}
     92
     93Trac 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:
     103Resolution:              |   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
     118we send :
     119
     120{{{
     121From: Sender <sender@bearstech.com>
     122To: test <marvin_trac>
     123Subject: Re: [test] #42: exemple for mail2trac
     124
     125we reassign it to jdoe and change it's cc to nothing
     126
     127#reassign: jdoe
     128#cc: ''
     129
     130
     131#end
     132On 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
     161answer :
     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:
     172Resolution:              |   Keywords:
     173-------------------------+----------------------
     174Changes (by sender):
     175
     176 * cc: jdoe (removed)
     177 * cc: '' (added)
     178 * owner:  somebody => jdoe
     179 * status:  new => assigned
     180
     181
     182Comment:
     183
     184 we reassign it to jdoe and change it's cc to nothing
     185
     186}}}
     187
     188
     189we accept the ticket :
     190
     191{{{
     192From: Sender <sender@bearstech.com>
     193To: test <marvin_trac>
     194Subject: Re: [test] #42: exemple for mail2trac
     195
     196in fact we want the ticket
     197#accept
     198
     199}}}
     200(note that end is not mandatory)
     201
     202answer :
     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:
     211Resolution:              |   Keywords:
     212-------------------------+----------------------
     213Changes (by sender):
     214
     215 * status:  assigned => accepted
     216 * owner:  jdoe => sender
     217
     218
     219Comment:
     220
     221 in fact we want the ticket
     222
     223}}}
     224
     225we close it :
     226
     227{{{
     228From: Sender <sender@bearstech.com>
     229To: test <marvin_trac>
     230Subject: Re: [test] #42: exemple for mail2trac
     231
     232we close as fixed
     233#resolve: fixed
     234
     235#end
     236On 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
     246trac 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:
     255Resolution:              |   Keywords:
     256-------------------------+--------------------
     257Changes (by sender):
     258
     259 * status:  accepted => closed
     260
     261
     262Comment:
     263
     264 we close as fixed
     265}}}
     266
     267
     268we reopen :
     269{{{
     270From: Sender <sender@bearstech.com>
     271To: test <marvin_trac>
     272Subject: Re: [test] #42: exemple for mail2trac
     273
     274Arf, no it's not done, i reopen
     275#reopen
     276
     277}}}
     278
     279we 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:
     288Resolution:              |   Keywords:
     289-------------------------+----------------------
     290Changes (by sender):
     291
     292 * status:  closed => reopened
     293
     294
     295Comment:
     296
     297 Arf, no it's not done, i reopen
     298
     299}}}
     300
     301
     302
     303
     304we close it again
     305
     306{{{
     307From: Sender <sender@bearstech.com>
     308To: test <marvin_trac>
     309Subject: Re: [test] #42: exemple for mail2trac
     310
     311resolve as invalid, but instead of #resolve: invalid we use the alias #invalid
     312#invalid
     313}}}
     314
     315and 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:
     324Resolution:              |   Keywords:
     325-------------------------+--------------------
     326Changes (by sender):
     327
     328 * status:  reopened => closed
     329
     330
     331Comment:
     332
     333 resolve as invalid, but instead of #resolve: invalid we use the alias
     334 #invalid
     335
     336}}}
     337
     338
    42339
    43340== Bugs/Feature Requests ==
    … …  
    47344
    48345If you have any issues, create a
    49 [http://trac-hacks.org/newticket?component=MailToTracPlugin&owner=k0s new ticket].
     346[http://trac-hacks.org/newticket?component=MailToTracPlugin&owner=zitune new ticket].
    50347
    51348== Download ==
    … …  
    55352== Source ==
    56353
    57 You can check out MailToTracPlugin from [http://trac-hacks.org/svn/mailtotracplugin/0.11 here] using Subversion, or [source:mailtotracplugin browse the source] with Trac.
    58 
    59 == Example ==
    60 
    61 [source:mailtotracplugin/0.11/mail2trac/email2ticket.py email2ticket] is an example [source:mailtotracplugin/0.11/mail2trac/interface.py IEmailHandler] plugin to convert an email message to a ticket.
     354You can check out MailToTracPlugin from [http://trac-hacks.org/svn/mailtotracplugin/0.12 here] using Subversion, or [source:mailtotracplugin browse the source] with Trac.
     355
    62356
    63357== Recent Changes ==
    … …  
    67361== Author/Contributors ==
    68362
    69 '''Author:''' [wiki:k0s] [[BR]]
    70 '''Contributors:'''
     363'''Author:''' [wiki:zitune] and [wiki:k0s] the initial author (thanks a lot) [[BR]]
     364'''Contributors:''' [[BR]]