JIRA: Creating issues from TLS-encrypted mail

As you know I'm extensively using Atlassian JIRA and one of the features my current client uses most is automatically creating issues from received email. The ability of automatically parsing an email and creating an issue is a nice built-in JIRA feature which sometimes can spare you a lot of work.

Configuring this service is straightforward:

• Configure a mail server.
• Configure the mail service.

Configuring a Mail Server

The mail server configuration screen, that you can access from your JIRA Administration section, is a simple screen where you can configure the basic properties of your mail server:

• Name.
• Default From: address.
• Email Subject: prefix.
• SMTP configuration:
• Host.
• Port.
• (Optional) User credentials.
• JNDI location of a JavaMail Session, in case you're running JIRA on a Java EE Application Server.

Once you've set up a mail server, you can proceed and configure the service that will read your mail box and create issues for you.

Configuring a "Create Issues From Mail" Service

The Services configuration tab lets you define JIRA services, which are the JIRA equivalent of an UNIX cron job. JIRA ships with some predefined services two of which are:

• Create Issues from POP.
• Create Issues from IMAP.

Depending on the protocol you're accessing you mail server with, you'll choose the appropriate service. In my case, I always choose IMAP if available. The following screenshot is the configuration screen of the "Create Issues from POP/IMAP" service:

There are different handlers you can choose from: you can find detailed information in the JIRA Documentation. The "Create issue or comment" is probably what you're looking for. The handler parameters lets you fine tune your handler with parameters such as:

• project: the project new issues will be created for.
• issuetype: the type of issues that will be created.
• createusers: a boolean flag that sets whether JIRA will create new users when a mail is received from an unknown address. Generally, you want this to be false.
• reporterusername: the name of the issue reporter when the address of the email doesn't match the address of any of the configured JIRA users.

Usually I set this parameter to something like: project=myProjId,issuetype=1,createusers=false,bulk=forward,reporteruserame=myuser

The Uses SSL combo box lets you choose whether you mailbox will be accessed using an encrypted connection. If you're planning to use SSL to access you mailbox you will probably need to import your mail server certificate into your certificate file, as explained later.

The Forward Email parameter lets you specify the address where errors or email that could not be processed will be forwarded to.

The Server and Port parameters lets you choose the mail server this service will connect to. The Delay parameter lets you specify the interval between every service execution.

Connecting to an SSL Service

If you're going to access your mail server using SSL, you will probably need to import the mail server public key into your certificate file, otherwise you'll receive some javax.net.ssl.SSLHandshakeException. In a previous post I explained how you can retrieve a server public key using OpenSSL. Once you have got the public key, you can add it to your key store by using the keytool program. The location of your key store may depend on your environment or application server configuration. The default location of the system-wide key store is $JAVA_HOME/jre/lib/security/cacerts. To add a key to your key store you can run the following command:

# keytool -import -alias your.certificate.alias -keystore path/to/keystore -file key-file

Additional Considerations for Solaris Sparse Zones

I'm often using Solaris 10 Sparse Zones to quickly deploy instances of software such as JIRA. In this case, please note that the system wide Java key store won't be writable in a zone. Instead of polluting the global zone key store, I ended up installing Java SE on every zone I deploy to avoid ending up with application trusting some certificates just because other applications do.

GMail with Evolution and the trash bin: how to organize mails and delete GMail messages

In part I of this series of posts (well, what meant to be just one post but it's going to explode...) I explored the basic configuration you need to setup Evolution as your GMail client. I also told you about GMail labels. labels are a mechanism to extend the concept of folders (in this case, IMAP folders): GMail servers indeed store just one copy of a message and if a message is labeled multiple times, the message will appear in all the corresponding folders. Label work just like UNIX hard links.

Folder names and GMail internal folders

GMail will provide one IMAP folder per label whose name will be the label's name. So far, so good. Now: GMail also uses some special folders to operate internally and you'll see them in the IMAP tree. These folders are:

• [GMail]/All Mail
• [GMail]/Drafts
• [GMail]/Sent Mail
  
• [GMail]/Spam
• [GMail]/Starred
• [GMail]/Trash

You really shouldn't use them but believe me, they just do what they say. Is it clearer why on part I we modified the default settings for some folders?

• The [GMail]/Drafts folder is visible in GMail web interface, so it's very handy to have Evolution save drafts directly there: you could start a message on Evolution, save it, and then sending it from you mobile device. You should be aware of a gotcha: if you're editing a message with a large attachment beware that when the mail client saves it, it will indeed send the attachment to the server! In such cases, I just attach the file at last.
• The [GMail]/All Mail folder contains a link to every single message in your account. That's why you should never store messages directly here unless you know what to do. We'll get into this later.
• The [GMail]/Sent folder contains a link to every message you sent. GMail does this automatically for you: the message will be stored on the server and labeled accordingly. That's why you don't have to save sent messages on the server. You would simply waste bandwith!
• The [GMail]/Starred folder contains a reference to starred messages. One more time you realize that everything's built around labels.
• The [GMail]/Trash label is very special. We'll get into this later.

Copying and moving messages

The file metaphor still applies:

• Copying a mail from a folder to another is equivalent to label a message with the destination folder's label.
• Moving a mail from a folder to another means removing the origin folder's label and applying the destination folder's label.

In the introduction, I said that labels are similar to UNIX hard links. Yes, but there's an important difference: a mail isn't unlinked when its label counter is 0 and a mail can be unlinked even if its label counter is greater than 0.

Deleting messages

This is where things may not be so intuitive. I'll try to make it clera with an example: when you receive a message (and you don't have any auto-labeling filter triggered by such message), that email goes into the Inbox. Moreover, that message will automagically appear into the [GMail]/All Mails folder. Now: what's the IMAP gesture that corresponds to archiving such message? A valid answer would be: moving it to the [GMail]/All Mails folder. This would indeed translate to:

1. Removing the GMail internal Inbox label.
2. Applying the [GMail]/All Mails label (which is already applied to every message).

Thus, the only action you could perform would be removing the Inbox label and you could do it in a bunch of ways including:

• Moving the message to a local (non-GMail) folder: this folder could also be the Evolution local Trash folder.

What has happened, then? Well: you think you deleted a message whereas you simply archived it. This is also true when multiple labels are applied. You can remove one label, but the same message could still be appearing in another n IMAP folders because of the remaining labels! How can you remove a message, then? Think about GMail web interface: when you delete a message, no matter the number of labels applied, what happens is that GMail is labeling it with the magic [GMail]/Trash label!

No matter how many labels a message has, labeling it with the [GMail]/Trash label effectively tell GMail to delete it in 30 days.

If you want to delete a message, then, just move it to the corresponding [GMail]/Trash folder of your account.

Is there a better way to do it?

I recognize that renouncing to the comfortable Delete button and having to move a message into the [GMail]/Trash folder is neither intuitive (semantically) nor easy: one click is addictive, a (right-click, move, choose folder) sequence is just a pain.

I had to cope with the same issue in Thunderbird but, fortunately, Thunderbird was easy enough to tweak in order to map the Delete action into the corresponding GMail action. It basically reduced to mapping the local Trash folder into the remote [GMail]/Trash folder and it could be easily accomplished manually editing the trash_folder_name property of each account.

I haven't (yet) found a way to do it with Evolution and I'll spend a couple of hours more to investigate it.

Configuring Evolution for GMail

Introduction

As many Evolution users may have noticed, Google does not include this mail client into the supported clients' list. If you, like me, are a UNIX user, you're probably wondering about which mail client to use between Evolution and Thunderbird. I'm not entering in such a war: I've been a Thunderbird user for a long time but I switched to Evolution mainly because:

• It's an Exchange mail client out of the box.
• PGP signing and encryption as well as S/MIME signing and encryption are supported out of the box.
• It better suits my enterprise-class needs such as calendaring.

Platform independence, as far as it concerns myself, it's not an issue: I'm a Solaris user and both Thunderbird and Evolutions ship with SXCE (and Indiana as well).

Because there's no how to about how to set it up, I decided to share my configuration with you in a series of posts. Here's how I configured my Evolution mail client on Solaris.

Enabling POP/IMAP in GMail

The first thing you've got to do to be able to use a stand-alone mail client with your GMail account is enabling POP and/or IMAP in your account. This is a topic covered in GMail help documentation. Resuming it, citing the guide:

1. Sign in to Gmail.
2. Click Settings at the top of any Gmail page.
3. Click Forwarding and POP/IMAP.
4. Select Enable IMAP.

I'd personally recommend IMAP over POP. As explained in GMail FAQs, IMAP is a more flexible protocol which offer two-way communication between client and server. This means two-way syncing capabilities and it's ideal when you access your mail from more than one device.

Creating the account

Once your Google account has been set up, you can open Evolution and create your account(s). The connection parameters can be consulted here.

Receiving email

That's how Evolution calls the Incoming server configuration tab. There are a couple of things you should be aware of. Google documentation is adamant about the ports where its services are exposed: neither IMAP nor SMTP are published on the standard ports and so a customized setup is required. In the case of Evolution, this means you're going to modify the account you created in order to adjust the port number. Incoming mail server runs on port 993 and Evolution, unlike Thunderbird (if that's what you're thinking about...), doesn't allow you to introduce a port number. That's not a problem: just introduce the server address in the classic hostname:port notation. That is: imap.gmail.com:993. Please notice, also, that the Use Secure Connection configuration parameter is set to SSL encryption.

Receiving options

Well, these is really a question of taste, but a couple of settings are important. The check for new messages in all folders may be relevant to you because of the flexibility of GMail. Indeed, if you configured a filter to automatically label and move emails, you'd want to check this because, otherwise, only the Inbox folder would be checked for new mail.

Sending email

This configuration dialog is similar to the previously described Receiving email dialog.



Notice the following:

• Outgoing server is smtp.gmail.com:587.
• The Use Secure Connection parameter is set to TLS encryption.

Use it!

Now, the account you just configured should be operational. Evolution is going to ask you for your account's password and then folders and emails header will be fetched.

Better user experience

Evolution is a pretty, straight forward email client inspired to Microsoft Outlook. Even if you're completely new to it, you'll quickly find your way through options and menus. Nevertheless I'm going to share a couple of suggestions.

Labels

GMail is not the typical mail service you may have used in the past. It has its own idiosyncrasies you should be aware of before tweaking your profile. GMail extends the concepts of directory through the concept of labels. Labels are like directories is that they're a mean to hierarchically organize emails but with a subtle difference: an email is usually owned by just one directory while an email can be labeled with as many labels you want. This means that in a given point in time an email could be owned by many folders, each for every label you labeled the message with. Removing a message from a folder means removing that label. On the other hand, copying a message into a folder is the GMail-equivalent of labeling a message.

Dos and don'ts

As documented, here's what you should do (quoting Google):

• DO save draft messages on the server. If you want your drafts in your mail client to sync correctly with Gmail's web interface, set your client to save drafts to the [Gmail]/Drafts folder.

and here's what you shouldn't (quoting Google):

• Do NOT save sent messages on the server. If your client is sending mail through Gmail's SMTP server, your sent messages will be automatically copied to the [Gmail]/Sent Mail folder.
• Do NOT save deleted messages on the server. Messages that are deleted from an IMAP folder (except for those in [Gmail]/Spam or [Gmail]/Trash) only have that label removed and still exist in All Mail. Hence, your client doesn't need to store an extra copy of a deleted message.
• Do NOT save deleted messages to your [Gmail]/Trash folder because this will delete a message in all folders.
• Do NOT save deleted messages to your [Gmail]/All Mail folder as some clients will try to empty this folder and ultimately fail. This can lead to delayed mail access or excessive battery consumption on a mobile device.
• Do NOT enable your client's junk mail filters. Gmail's spam filters also work in your IMAP client, and we recommend turning off any additional anti-spam or junk mail filters within your client. Your client's filter will attempt to download and classify all of your existing messages, which may slow down your client until the process is complete.

They're quite intuitive, once you grasp the labels' functionality but if you never wondered about it, they're indeed gotchas. Here's my default configuration:

Security

Do you mind about security and confidentiality, don't you? And if you don't, you should. Evolution let's you sign and encrypt your messages by means of PGP and S/MIME technologies. You can set your security preferences for your accounts and be sure to sign the messages you send:

And if you don't have a PGP or GPG key, I'll tell you how to create one and set up GPG on your Solaris box! ;)

Follow ups

In Part II of this series I will tell you more about some GMail idiosyncrasy and how to cope with message deletion.