Changes between Version 9 and Version 10 of MailToTracPlugin


Ignore:
Timestamp:
Nov 2, 2011 5:15:48 PM (3 years ago)
Author:
zitune
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]]