1 - What is JEMH
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 https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/57606174 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 |
|---|---|
JEMH : Jira Extendable Mail Handler |
|
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:
|
JIMI : Jira Instant Messenger Interface | An additional component that allows users to interact with Jira via IM:
|
Jira Poker |
|
User ID alias resolver |
|
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.