...
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.
...
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 |
---|---|
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.
...