wiki:Email2tracParse

Version 17 (modified by anonymous, 7 years ago) (diff)

--

How an email is being parsed

An email has a header and a body. The email header fields are used to set the ticket fields and the body is used for the description and attachments. See section below how the header and body are parsed.

Delivered-To Fiels

This is the preferred way. With this configuration each ticket get its own reply-to address. This can only work if the AnnouncerPlugin is installed with rewrite replyto patch or download surfsara patched AnnouncerPlugin

Your MTA must support this. Currently we support two methods in email2trac.conf:

  1. notify_replyto_rewrite: use_mail_domain
  2. notify_replyto_rewrite: use_trac_smtp_replyto

Each option has its own settings. The options are described below.

use_mail_domain

When this option is used you have setup your own MTA for this domain. After that you have to set 3 options:

  1. email2trac.conf (cfengine3/data/bundles/email2trac/<server>)
    notify_replyto_rewrite: use_mail_domain
    of
    notify_replyto_rewrite: use_trac_smtp_replyto
    
  2. trac.ini (/data/trac/subtrac/project/<tracproject>)
    [announcer]
    ticket_email_replyto = $(ticket.id)@email2trac.surfsara.nl
    

use_trac_smtp_replyto

Your MTA must support this format email2trac+<id>@surfsara.nl. For postfix this can be set in the configuration file (main.conf):

# The recipient_delimiter parameter specifies the separator between
# user names and address extensions (user+foo). See canonical(5),
# local(8), relocated(5) and virtual(5) for the effects this has on
# aliases, canonical, virtual, relocated and .forward file lookups.
# Basically, the software tries user+foo and .forward+foo before
# trying user and .forward.
#
recipient_delimiter = +

After this change we have to set some options in:

  1. email2trac.conf
    notify_replyto_rewrite: use_trac_smtp_replyto
    recipient_delimiter: + (default value is +)
    
  2. trac.ini
    ticket_email_replyto = email2trac+${ticket.id}@surfsara.nl 
    

Subject field

Versions greater or equal then 1.1.0 can set the subject field separator. The default value is &. Versions prior to 1.1.0 used , as subject field separator. The examples below are for versions 1.1.0 and higher.

The subject field determines if we must create/update:

  1. ticket (default action)
  2. blog, Only if the FullBlogPlugin is installed. If not then a ticket will be created.
  3. discussion, Only if the DiscussionPlugin is installed. If not then a ticket will be created.

tickets

How is the 'Subject' line parsed for tickets:

  • Subject: Bas
    • will Create a ticket with Summary : Bas
  • Subject: Bas #?owner=bas&version=0.80
    • will create a ticket with Summary : Bas and owner set to bas and version set to 0.80
  • Subject: #4: Bas
    • will update ticket #4
  • Subject: #4?owner=jaap: Bas
    • will update ticket #4 and set owner to jaap

blog

  • Subject: blog:bas
    • Will create a blog entry, with its short name derived from the email's date, and title 'Bas'. only if the FullBlogPlugin is installed
  • Subject: blog?categories=foo,bar&author=joe: Bas
    • Will create a new blog entry and set categories to 'foo' and 'bar',and author to 'joe'. Categories can be separated by comma, semicolon or space, and they cannot contain ampersand or colon.
  • Subject: blog:test Bas
    • Will create a new blog entry with name 'test' or add a comment to that blog entry if it already exists. Note that the subject of the email is not preserved when a comment is added to a blog entry.

Body

If a message's body is broken up into several pieces (by attachments in the middle of the message), the ticket's description is set to the entire body, not just the first part

For example, from an email like this:

some text
<some binary>
more text

the ticket that is created will have "some text" and "more text" in its description and <some_binary> as attachment

Links to attachments inside the ticket description

[attachment:filename] links are automatically placed inside the ticket description, so that message text can clearly refer to them.

For example, an email like

I opened this file in your app:
<my file>
and I got the following error dialog:
<image>

will generate a ticket like this:

I opened this file in your app:

[attachment:"my file"]

and I got the following error dialog:

[attachment:"image"]

Inline image attachments

If an attachment is of type image/* and its Content-Disposition is inline, then a Trac Image macro is placed inside the ticket description in the appropriate place, so that the resulting ticket has the image inline where it belongs in the text.

The same email as in the previous example, if the image is inline, will result in:

I opened this file in your app

[attachment:"my file"]

and I got the following error dialog:

[[Image(image)]]

Inline properties

If the inline_properties is set in email2trac.conf then we can update ticket or blog fields within the body text.

ticket

To update ticket field within the body text: eg:

This is a Test1234
@owner : bas
@type: task

Will create ticket with body text:

This is a Test1234

and the owner field set to bas and type ticket field to task. Note the keywords will be stripped from the body text. This feature can be used for a new ticket and ticket updates.

The format is:

@<ticket field name> : <value>

blog

If inline_properties are enabled, @categories , @author and @update can be used in the mail body. Inline properties take precedence over parameters given in the 'Subject:' header.