Summary

JEMH is an Enterprise mail handler for JIRA and provides enterprise features like security, auditing as well as advanced issue routing.

Why was it written

Back in the day (~2008 when Jira 3.x roamed the earth) inbound mail to JIRA was broken for 60% of the LDAP based users of the day thanks to strange email aliases (you only get to register one in crowd/atlassian-user/os-user). After fixing inbound email I was keen to figure out a way of NOT having to create per-Project mailboxes. The use of virtual mailboxes fits the bill perfectly. Then, I looked at Confluence integration, or rather lack of, for issue creation. Sure scratchy HTTP URL link will get you to a page, but its just not good enough. Initially I tried just using the Confluence MailFormNg plugin, but found it lacking in features on the handler end. So I ended up writing this, a hopefully fully feature email issue creation handler with pluggable support for alternate user ID provision and a much simplified 'guts' to what is essentially a mail field processor, responsible for just extracting needed fields in whatever way is appropriate. By chaining numerous implementations together, this handler can support single issue creation via the provided MailFormNg processor, or a multi-issue creating CSV processor, just providing a common MAP of keys to values.

Orientation

This section assumes no knowledge of JIRA email handling. Its designed to answer the common questions that first time users have.

Where do emails come from	a) When users work on issues, that action creates an event, this event is caught by the JEMH Event Listener which generates notifications. b) JEMH also generates notifications from the Profile in response to inbound email (which is the name given to a JEMH configuration, talked of later).
How do replies get associated with issues	a) JIRA email has historically included issue KEYS in the subject, if this is found to refer to an existing issue, it will drive a commenting behaviour b) JEMH has features that drive how an email can be associated with issues, so called Field Processors in JEMH can be configured to extract information from formatted or unformatted emails, that can override what issue is used for commenting, or updating
Can I update an issue field by email	JEMH supports several flavours of email format that can be used to update all JIRA default custom fields, manipulate workflow, log work, etc.
Who gets the mail?	JIRA has inbound mail connections, you configure JIRA with credentials for accessing remote mail severs. When mail is found, JIRA will hand that mail off to a Mail Handler such as JEMH that you have configured in JIRA. For JEMH, when you create a JEMH Mail Handler, you will also select a JEMH Profile, which is where all the configuration is.
Who deletes the mail?	After JEMH has finished processing the message, JEMH returns a true value to indicate JIRA should signal the remote mail server to remove the message. The remote mailserver is responsible for interpreting this, e.g. Gmail interprets this via server side configuration, eg marking the message read, and unpicking the 'inbox' label.
All mail stopped!	a) Usually, your mail credentials have expired, enable protocol debugging in JIRA to see this. b) When using IMAP, a large email could be present in the mailbox, that cannot be downloaded, you will see timeout and FolderClosed type errors in atlassian-jira.log . See Download performance of POP vs IMAP for how to increase the ‘block’ size of downloads via IMAP. We have seen some mails take many minutes, some customers have presented Report info showing over an hour !
What is needed to create issues?	JEMH requires some basic information to create issues: a) target Project, b) Issue Type, c) Reporter, d) Summary. All these can be configured through defaults in the Profile, but when selecting them, be aware that different projects have different issue type schemes, so a default issue type may not always be valid. JEMH Profiles have lots more flexibility through Project Mappings to help.
Post Functions and issue creation	Postfunctions requiring access to custom fields initialised or set through JEMH will just not work during the issue created transition. This relates to an architectural issue in JEMH, see JEMH-280 that needs work to fix, usually there are workarounds, log a support ticket with specific requirements.

What does JEMH need?

It is possible to use JEMH defaults to provide key issue information (project, components, issueType, reporter). That configuration, combined with user provided values must meet a minimum criteria for issue creation, which are:

A subject
A project
A reporter

Description/Features

Component	Features provided

Component	Features provided
JEMH : Jira Extendable Mail Handler	Create issues in Jira by email, simple inline email content, e.g. issueType: bug. All standard Jira fields can be set during creation, including Custom Fields (inc Select and Cascade Select). Multiple formats are supported including CSV for multi-issue creation. Update issues in Jira by email, most fields are supported, using the same syntax as for creation. Emails that fail to create issues or fail to set some fields generate Hint-o-gram emails back to the initiator, describing what went wrong and why, including the original email. HTML delivery is available to registered Jira users if that is their set preference. Seamless integration with Confluence via the MailFormNg plugins forms (this project was initially written just for that) Reduce admin overhead for email account management by supporting n project per inbox, using the to: address as a project key. Enable advanced userID lookup during user creation, handy when you have a corporate Exchange box which insists on using different aliases for different clients (web/outlook/other) Fully flexible block/allow-listing by email address, as well as grey-listing on topic, enabling 'problem' emails to be dropped silently rather than clogging up your inbox Ability to create users on the fly, with several options for created userid format, eg userid@domain rather that userid@domain Ability to configure customized aliases for JEMH directives, enabling shortcuts such as @close instead of @workflow=close
JEMH Field Processors	This set of classes are dynamically identified, enabling users to plugin their own to support some custom format. Several formats are provided: Subject based #key=value Body based @key=value Body based key: value _(specifically written to enable interfacing with Confluence Mail Form Ng Plugin CSV tab or comma delimited attachments for yet another way to auto load data Nagios , funnel notifications from this popular Infrastructure Monitoring tool into Jira
JIMI : Jira Instant Messenger Interface	An additional component that allows users to interact with Jira via IM: configurable Jira user authentication, including captcha interactive shell to work in easily command framework making new commands trivial to add, currently providing ability to test system info, and also see who is online via IM watch projects and issues, eg 'watch conf' or 'watch CONF-123' TODO: add watch support, eg project, components, issues, reporters etc, all subject to Jira security add issue create/update support
Jira Poker	If speed of delivery matters to you, an optional remote agent can be installed to monitor file-based mailboxes (Eg Postfix) for new mail. The Agent is deployed separately to JEMH as of Poker 1.2, as JEMH needs to be plugins 1, and REST services only work with plugins 2, sigh. The Jira Service deployed in Jira receives a poke from the Poker Agent, and triggers the mail retrieval service for the JEMH configured Pop/Imap service
User ID alias resolver	an extension point is provided enabling the customisation of email address to registered Jira user lookup, needed when a user may for example have email coming from user@someplace.com and user@someplace.de, both of which need to map to user. The provided implementation is suitable for LDAP with a single primary mail account and multiple aliases.

JEMH Usage Scenarios

To see how JEMH can help you make the most out of your JIRA instance, see the following scenarios. If you have a scenario that's different, drop me a line on the support site and I'll see if I can help.

Scalability for incoming email handling

Once you have a non-trivial number of projects, you will have found that this doesn't scale (btw, this was one of the reasons JEMH came to be). Adding a specific mail handler for each project will do bad things to your mail server and queue flush timings, delays in fetching mail etc. JEMH Addresses this in a number of ways:

Scenario 1 - you can support n addressees in a mailbox (e.g. have a Postfix virtual mailbox)

JEMH allows dynamic routing to a project based on the addressee of an email. This means that one JEMH configuration can support n projects with one connection to one mailbox.

Scenario 2 - you don't want to open up all projects

JEMH allows mapping of projects based on addressee. If your mailbox can receive mail addressed to different recipients, JEMH provides Project Mapping that can use the addressee to route email to a specific project. Again, one JEMH configuration, multiple mappings supporting multiple projects with just one mailbox and just one connection.

Support Desk - lots of external users

This is becoming quite common. You have a JIRA instance for your team, but want to engage with your customers. Creating JIRA user accounts for all your customers is one option, but it might work out a little pricey, and for occasional use, perhaps doesn't make the most of that investment. JEMH can help by providing an email interface for JIRA, routing traffic to projects through customisable mappings.

Scenario 1 - Create Users with interactive logon

By enabling full JIRA user membership, your remote users have the flexibility to logon or use email. The thing that JEMH brings over the default handlers here is that issues can be routed to projects, categories, have priorities set, labelled, all based on incoming domain, saving lots of ticket management. If you receive a lot of traffic, this automated routing of traffic should help greatly!

Scenario 2 - Create Users but do not enable interactive logon

By creating a JIRA user account that doesn't allow interactive logon, that account can be used within JIRA but does not count as a seat. The additional advantage of this setup is that notification schemes will work, using that users email address. The downside is of course, that those users will receive enticing JIRA ticket id's and might expect to be able to logon to JIRA.

Scenario 3 - Don't create users

If you just don't like the idea of creating users in your JIRA period, then its also possible to support that but there are consequences. By not creating an account, there is no way to include them in notification schemes, however, coming in 1.1 is an integrated EventListener that will enable per related project customised notifications, enabling you to remove specific JIRA logon references and transform JIRA into a more email-friendly helpdesk system.

System Integration

Scenario 1 - integrate Nagios monitoring system X with JIRA

Sure you could write a REST client etc etc, however, many systems provide email alerts, routing those to JIRA for management can be a time saver. JEMH supports Nagios notifications and is able to automatically close out open tickets if an 'OK' message is subsequently received. This association with a previously existing issue is something that will be coming to generic issue processing at some point in the future.

Scenario 2 - integrate system X with JIRA

JEMH Is pretty flexible and offers many ways to handle incoming mail, including manipulating the issue that would be created through Directives. Directives can be supplied in a variety of formats (but can't be mixed in the same message as all Directive Field Processors go through an initial selection, there can be only one...), for example, a message can be supplied with a modified subject #issueType=bug there is even Alias support, so #bug could be made to have the same effect.

Confluence integration

Scenario 1 - integrate JIRA with confluence via e-mail

The awesome Adaptavist MailFormNg plugin allows you to setup a form in Confluence that emails JIRA. JEMH has a Directive Field Processor that caters to this format, and can route the email accordingly.

Ad hoc usage

Scenario 1 - influence issue creation

JEMH can, through the use of Directives, help more appropriate issue creation, for instance, when receiving an email, you can forward to jira, but set a specific project, issueType, priority etc.

Enterprise Mail Handler for Jira Data Center (JEMH)

1 - What is JEMH