Overview

JEMH is getting pretty complex, sometimes its tricky to understand how bits of configuration relate to processing. This page will describe the processing flow of messages through this handler.

Initialization, configuration loading

A precursor requirement for JEMH to be initialized is that a POP or IMAP service has to have been configured, and JEMH has been selected as the appropriate Mail Handler for that service. Once correctly setup, JEMH will be initialised on successful retrieval of a message from a message source. JEMH is currently driven mainly by a configuration file, but can have specific values overridden through the Jira POP/IMap service parameters.

Filtering

Whilst filtering messages at the server end is certainly doable, sometimes its easier to just do it locally. JEMH allows regexp matching in a variety of ways (blacklisting and whitelisting) against sender address and subject to silently drop specific emails, for example, because Jira insists on sending email to users even if their LDAP account is disabled, outbound mail gets bounced by postmaster back to Jira, which would otherwise be sent on to the forward email address (i.e. you, the admin will get it).

The following filters are currently implemented:

• Catchmail

• Whitelisting/Blacklisting

• GPG Signing

Field Processor Identification

The field processors are responsible for parsing email content and generating maps of Directives that JEMH uses to manipulate issues. They are identified by their source code package, and implementing classes are dynamically discovered at runtime. This is very versatile, allowing alternate sets of processors to be plugged in, but I've not heard of anyone writing their own Field Processor yet. Likely this will be simplified in time. Each Field Processor has a 'parsePriority' attribute hard coded in it. This allows configuration to drive the inclusion of specific Field Processors only, or exclusion of the more exotic handlers.

Field Processor Selection

Once Field Processors have been identified, they are each asked to extract a field map from the message. The Field Processor with the highest field count wins the election. Usually this will result in the right Field Processor being selected. If no 'tell tales' of a given Field Processor format are found, a fallback is used to simply take the email content as-is.

Fixing up

'Fixing up' is a loose term to cover the provision of default information, or massaging of provided data into more usable data. The fixing up process is done by the Field Processor winning the election. For example, if creating users is enabled, the CC: part of the address will be used in someway to generate a User, a list of which which will then be used by JEMH for 'watchers'.

Initial Issue Creation/Update

If the issue is found to have the minimum amount of information (project, summary and reporter (if mandated)) it will be created, once created, a second phase of processing occurs to perform operations that require a persisted issue - post-create operations. If the update relates to an already existing issue, then that issue is updated.

HintOgrams

If during any of the processing, a situation occurs where a directive has been provided with an illegal value, or a situation has arisen whereby required information be be missing (eg missing defaultProject configuration option with no other email Directive indicating where it should go), then JEMH will collate such information and inform the initiating user. There are Html and text templates available, selected based on user mail notification preferences.

Example hint-o-gram email processing response

Open

Post create actions

With the recent changes in Jira licensing there is interest in notifying users of created issues who create issues by email.