Sunday, May 2, 2010

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.

No comments: