JIRA Advanced Mail Handler

An extension of the default email handler that allows users to define a new issue's project, type, priority, reporter, components... in the email message.

Description and Features

The JIRA Advanced Mail Handler is an extension of the standard JIRA email handler; it allows users to define many fields of the newly created issue (reporter, project key, type, priority, affected components, etc.) directly in the body of the email message. Hence, one of its notable features is that you do not need to repeat the whole process (opening a mail account on your mailserver, creating a mail account in JIRA, associate a handler service to the mail account and configure it) for each project you have in your JIRA installation; you just do the process once, setting a global mail account and handler service that will receive messages for all projects.

License

This software has been developed for CERN needs. It is available "as is" under BSD license and you are welcome to download and use it; however, neither CERN nor the author (I) can guarantee any support. I will however do my best to answer questions and help when I have the time: please write your question or feedback in the Comments section at the end of this wikipage, I will automatically be notified via email. Please also take some time to read the whole wikipage, including the comments – it may provide you the answer you are looking for.

Installation

To install the Advanced Mail Handler, follow these steps:

• Unzip the file archive and copy the compiled .class files into WEB-INF/classes/cern/jira/emailhandler/ (you might need to create the required directories);
• Add the following snippet of code to WEB-INF/classes/services/com/atlassian/jira/service/services/imap/imapservice.xml:

  <value>
          <key>cern.jira.emailhandler.AdvancedCreateOrCommentHandler</key>
          <value>Advanced Mail Handler</value>
  </value>
  

• Restart the JIRA server.

Configuration

Once the Handler is installed, you need to configure and activate it. This is done similarly as for the standard handler, as described in http://www.atlassian.com/software/jira/docs/latest/issue_creation_email.html: please read that page first, here I leave out some details and I describe only the steps that differ.
The procedure is as follows:

• Create an IMAP mail account, for instance issues@yourcompany.com. (The Handler probably works also on a POP account; however, I haven't tested it.)
• Add a new service: for Name, enter "Advanced Mail Handler"; for Class, select "Create issues from IMAP".
• Edit the newly created service: for Handler, select "Advanced Mail Handler"; for Handler Parameters, edit it as follows:
  • The project parameter is the key of the default project. An issue is assigned to this default project if the user did not specify any project key, or specified an inexistent project key, in the email message. This parameter is optional, but I recommend to set it.
  • The issuetype parameter is a number specifying the default issue type, and the association between numbers and issue types are explained in http://www.atlassian.com/software/jira/docs/latest/issue_creation_email.html#handler_params. An issue is assigned to this default type if the user did not specify the issue type in the email message. This parameter is mandatory.
  • The jiraemail parameter must be set to the address of the IMAP account, in our example issues@yourcompany.com. This parameter is mandatory.
  • If an alternate email address for jiraemail exists (for instance in the LDAP database of your company), the jiraalias parameter can be set to this alternate address. This parameter is optional.
  • The other parameters are the same as the ones defined for the default handler.

Now click the Update button and the service will be operative.

Usage

To comment an already existing issue, the usage is the same as the default handler: just mention the issue number in the Subject: of the email message. The body of the email will become the comment on the issue. You can also send attachments with your email, which will become attachments on the issue (if attachments have been enabled in JIRA).

On the other hand, the Advanced Mail Handler allows you to define several fields when creating an issue. This is done by adding one or more tags in the text of the Subject: header, in the format #TAG-NAME=tag-value or #TAG-NAME=tag-value1,tag-value2,tag-value3.... The tag must not contain any space, i.e. there is no space character around the equal sign or the commas.

Project

You can specify the project in two ways:

• by addressing the message to project-key <issues@yourcompany.com>. This address can be put in the To:, Cc:, or Bcc: header at your choice.
• by adding the tag #PROJECT=project-key in the Subject: header. This overrides the project key in the address.

You always send the email to issues@yourcompany.com (or the address defined in the jiraalias parameter as well); what changes is that in the first way you add the project key as the Full Name part of the address.
For your comfort, you can create an entry in your addressbook for each project you're working on, with the project key as the Full Name and issues@yourcompany.com (which will be the same for all projects) as the Email Address.
If you do not specify a valid project, the issue is created in the default project defined as the project parameter.

Some mailclient (as Microsoft Outlook) does not give the user full control concerning the recipient address in the composing mail interface; for instance, if your company uses a LDAP database and issues@yourcompany.com has a record in it, these mailclients will not allow you to choose a Full Name for that email address and stubbornly put the Full Name defined in the database instead, no matter what you write. Also, some mailclient shows only the recipient Full Name and not the real email address, so it is difficult to tell who you are sending mail to. In this case you need to follow the second way and specify the project in the Subject: header. The mailclient might also convert issues@yourcompany.com to the alias defined in the LDAP database, e.g. Jira.Issues@yourcompany.com. In this case, in addition to setting jiraemail to issues@yourcompany.com, you must also set the optional jiraalias parameter to Jira.Issues@yourcompany.com. Nevertheless, to avoid all these hassles, my advice is to switch to a better mailclient – I personally recommend Thunderbird or SeaMonkey.

The jiraemail and jiraalias parameters have the purpose to ensure that a message was addressed to JIRA, so that spam does not go processed or, worse, ends up as an issue to the default project. If you see an ERROR [cern.jira.emailhandler.MessageParser] Jira email address not found amongst recipients in the logs, you specified these parameters incorrectly or you are sending the email message to the wrong address.

Summary

As with the standard handler, you write the summary of the issue in the Subject: of the email.

If you do not write any summary, the issue will be created with a summary text "(no summary)". However, it is recommended that you put a meaningful summary so all JIRA users can identify the issue.

The Subject: header can also contain several tags (as you will learn as you continue reading), which will not be included in the summary. These tags must be separated by spaces, and may be put in any order.

You should not use special characters (letters with acute/grave, diaeresis, tilde, etc.) in the subject line, or it may become corrupted. Please use only ASCII-7 characters.

Description

As with the standard handler, you write the full description of the issue in the body of the email.
You can also send attachments with your email, which will become attachments on the issue (if attachments have been enabled in JIRA).

Reporter

As with the standard handler, the reporter of the issue is identified as the sender of the email (you).

However, you might have more than one JIRA account associated with your email address, you might want to indicate another person as reporter, or you might be sending the email from another email account. In this case, you can explicitly specify the reporter by adding the tag #REPORTER=username in the Subject: header.

Assignee

As with the standard handler, the first Cc'ed person that is also a valid Jira user and a valid assignee for the concerned project becomes the assignee.

As one person can have multiple JIRA usernames associated with his email account, you can explicitly set the assignee's username by adding the tag #ASSIGNEE=username in the Subject: header. This overrides the Cc'ed assignee.

If you do not specify any valid assignee, the issue is assigned to the Default Assignee.

Issue type

You can specify the issue type by adding one of the following tags to the Subject: #BUG, #NEWFEATURE, #IMPROVEMENT, #TASK, or #SUBTASK.

If you do not specify it, the issue will be of the type specified in the issuetype parameter.

Priority

You can specify the priority of the issue by adding one of the following tags to the Subject: #BLOCKER, #CRITICAL, #MAJOR, #MINOR, or #TRIVIAL.

This option was managed by the default handler by looking at the X-Priority: header of the email, but I implemented it as such because many mailclients do not permit to set custom headers easily.

Components

You can associate an issue to one or more components of the project by adding the tag #COMPONENT=component-name to the Subject:. To specify multiple components, separate the components by a comma, as in #COMPONENT=first-component-name,second-component-name,third-component-name. Note that there is no space inside the whole tag.

If a component name contains any space, you must replace the space by two underscore characters. For instance, #COMPONENT=Test__Component associates the issue to Test Component.

If you specify no or invalid component, the issue gets associated by default to No Component.

Examples

Example I The minimal email message you can send is summarized below: To: issues@yourcompany.com Subject: #PROJECT=XYZ Race condition A problem of race condition occurs when... etc. This creates an issue of type specified in issuetype and of default priority (usually Major), on the project that has key XYZ, summarized as "Race condition". You may also write the email in this format if your mailclient allows you to set the Full Name in the address: To: XYZ <issues@yourcompany.com> Subject: Race condition A problem of race condition occurs when... etc.

Example II Let's say you want to issue an improvement request of critical priority on the component core-alarms of project ABC, summarize it as "Alert user when a buffer overflow is reported", and assign it to John Hacker (John.Hacker@cern.ch). You would usually Cc the message to John.Hacker@cern.ch; however, John Hacker has two JIRA accounts, jhacker and admin, associated with his email address, and you'd like to unambiguously assign the issue to the former. Then you have to write an email as follows: To: issues@yourcompany.com Subject: #IMPROVEMENT #CRITICAL #PROJECT=ABC Alert user when a buffer overflow is reported #COMPONENT=core-alarms #ASSIGNEE=jhacker It is crucial to show a visual warning to the user in case of a buffer overflow... etc. Note that you can specify tags in any order and in any position, and they will not be included in the issue's summary.

Example III To comment issue ABC-7, simply write the following email: To: issues@yourcompany.com Subject: ABC-7 My comment on this issue is... etc. This is the usage of the standard JIRA email handler, and is left unmodified in the Advanced Mail Handler.

Troubleshooting

If you cannot get the Advanced Mail Handler to work, try the following:

• Read again this instruction page and the comments; it is easy to miss something the first time.
• Examine the JIRA logs to see what is going wrong.
• Check the incoming email in the IMAP account (where the Advanced Mail Handler fetches the mail from).
• Try to uninstall the Advanced Mail Handler and to use the default mail handler instead. If it fails too, chances are that some of your JIRA components (email server, services, project keys...) are misconfigured. In this case, escalate the problem and ask the general JIRA support for help.

Tips and Tricks

If you prefer to have one email address for each project, like the standard email handler, just proceed as follows.
Create an IMAP email account for the first project, add a new service and associate the Advanced Mail Handler to it, as explained in the Configuration section above. Specify the email address as the jiraemail parameter and the project as the project parameter. Repeat the process for each project.

Third-Party Patches

David Leinbach wrote a patch that allows the user to specify the due date (given as YYYY-MM-DD) and the original estimate of the issue. For instance: #DUE=2008-04-14 #EST=1h.

You'll have to apply the patch on the original source code, then recompile it. Note that the Advanced Mail Handler was compiled on Java 1.4.2_12 for compatibility issues with Tomcat. You can find a Windows version of the patch tool as a part of the GnuWin32 package. (These instructions are given here for your convenience; I haven't tried them.)

Version History

2.3 (June 4, 2007): First public release.

Open Issues

Please see http://developer.atlassian.com/jira/browse/JMH. I do not foresee to release or work on a new version of the software at this moment.