JEMH Features
Profiles
Profiles are top level containers for configuration. When a JEMH inbound mail handler is configured, a Profile will be selected from a list (so a Profile will need to be created before the mail handler can be configured).
A single Profile can route mails from one mailbox to multiple projects, thereby addressing a major scalability issue with the default mail handlers. Multiple Profiles can be configured if required.
Profiles and all their related configuration (with the exception of custom template references) can be exported as XML, for easy migration between environments as well as for support purposes.
Profiles contain a Configuration, that defines how JEMH processes emails, these are broken down into various categories:
Work in progress
This area will be the focus of further expansion!
Security
Defaults
Privileged User In order to perform some low level operations, normally done under a human user context, a user with sufficient privilege to perform that action is required. This field specifies that user, which defaults to the person who created the Profile.
Places where Privileged User is required:
Issue Commenting - used to perform a search and locate the existing issue.
JQL Thread Match Rejection - used to perform custom JQL query searches on existing issues to validate commenting
Regex Field Processor - used for issue association. In order to perform a search and locate the existing issue.
Email Participant Processing - in order to add the sender and email addressees to the request participants field.
Sender Processing - in order to add the sender who is a member of the organization as a request participant.
Issue Security - in order to retrieve security levels and set issue security on an issue.
Project Mapping - in order to add a group to a given project role.
Project Mapping - in order to set Epic Link custom field with the value.
User - in order to auto-create new Jira users and create Groups, typically auto-joining users to them.
Strict JIRA permissions By default JEMH will enforce strict JIRA permissions regarding updates. This means that any issue operation must pass valid authorisation (i.e., auto adding watchers requires EDIT_ISSUE). Disabling Strict permissions reduces some of these rules.
Default reporter overrides derived If enabled, will always use the Default Reporter in the User section. This could be used to ensure users are not created.
Use email sender for security checks A convenience feature, for example, an project lead wants to forward a user email into JIRA for issue creation, the project lead has permission in the project, but the user the email belongs to and who is being nominated as @reporter does not (perhaps STRICT security is enabled). With this enabled, JEMH will run under the senders associated JIRA user account for the purposes of security checks.
Issue Security
Issue security level If set, will apply a default issue security level to all created issues, applying some basic security by default.
Comment Visibility
Comment Level Security for groups Enables matching of groups for security level checks
Comment Visibility Selects a project role or group. Naturally, these must be valid for whatever project an issue resolves to
Project
Defaults
Fallback Project Setting this as the KEY of a fallback project will mean that with no other information forthcoming (e.g. due to Project Mappings or Directives) that this will be used. Without this, when no project has been configured, the message will be rejected.
Fallback Component When the fallback project is used, if set, this value defines the CSV names of components that the issue will be assigned.
Project Auto Assign If your mail server is capable of delivering multiple addressed email to a single inbox, eg abc@place.com and def@place.com, that if a project KEY exists that matches 'ABC' or 'DEF' then it will be used. This is the most efficient and scalable routing solution, allowing JEMH to support n Projects with just one configuration and mailbox.
Auto Assign from Sub Addresses With an RFC5233 format addressee (user+KEY@place.com), used to still support the above for KEY matching.
Project Mappings
... lots to do
User
Defaults
Default reporter user name By default, JEMH will attempt to locate the JIRA user related to a given email, if that lookup fails, and user creation is not enabled, then this value can be used to provide a 'fallback' reporter. The Default reporter must still have the correct project authorisation in order to create issues.
Enable automatic assignee If enabled, will look to Component, then Lead for an assignee, if a default is not set in the project.
User Creation
Create users If enabled, will, on receipt of email addresses in FROM:, TO:, CC: create JIRA users and set with the relevant address.
Notify Users If enabled, will email auto-created users, enabling them to change passwords etc.
Create User ID from Provides control over how the user ID in JIRA is defined. At the moment, limited to:
Name
Email
Alternate (future LDAP re-integration)
Whitelist user creation by email domains A CSV list of regular expressions for email addresses that will be valid for JIRA user creation purposes (e.g.: .*@yourco.net).
Blacklist user creation by email domain Inverse of above, giving choice of pick valid domains or invalid domains.
Auto-join group(s) A CSV list of names of groups that an auto created user will join. This list is absolute, so if jira-users is not included, the user will not have that group, have right-to-user JIRA, or count toward JIRA license.
Issue
Defaults
Issue Type Sets an Issue Type that will be used by JEMH in absences of any other value set through Project Mappings and Directives. If no default is set, the System default would be used.
Priority Sets a Priority that will be used by JEMH in absences of any other value set through Project Mappings and Directives. If no default is set, the System default would be used.
Summary A fallback summary that will be used in place of an empty one (give that an empty subject will cause a rejection).
Label CSV list of no-space-values used as labels on created issues, used by JEMH in absence of any other value set through Project Mappings and Directives.
IssueLink type Allows a default issue relationship to be defined, e.g. Relates, allowing reduced typing to link issues with Directives.
Worklog security Role - Sets a default security Role applied to worklog notes delivered through JEMH.
Worklog security Group - Sets a default security Group applied to worklog notes delivered through JEMH.
Add Sender As Watcher - Automatically adds the sender as a watcher to created issues, not necessarily with right-to-use.
Dates
Due Date Format - Allows an email specific format for DueDate. This may be overridden through Directives, if left undefined, must match the system default.
Loop Detection
Issue comment limit - Restricts comments by email on any one issue to be no more than this value. Useful to put a block on runaway notifications!
Issue comment max size (Kb) - Limits inbound emails to a specific size, note that this relates to the COMMENT size only. Useful to stop runaway bot-generated chatter between JEMH/other.
Limit exceeded action - Determines action to take when set limits are exceeded, eg:
Forward to the Forward User (Notification section)
Reject
Workflow
Auto Advance
Use first word only workflow name match - With Workflow Steps such as 'Resolve the darned Issue already', enabling this flag allows 'resolve' to match the first word.
onCreated Workflow advance action - If set with 'Start Progress' or just 'start' if the above is set, will attempt to advance issues on creation (silently fails if not applicable).
onComment Workflow advance action - If set with 'Biz Thinking' or just 'Biz' if the above is set, will attempt to advance the workflow of an issue with the given step.
onComment advance from States - In order to apply the onComment workflow advance, a CSV list of valid FROM states must be provided, e.g. 'Customer Thinking'.
Workflow Defaults
TODO (actually, to even implement)
Custom Field Defaults
Custom Field Defaults allow arbitrary Custom Fields to have default values specified.
Aliases
Aliases are versatile mechanisms for providing short cuts to common directives, e.g. an Alias bug with value issueType=bug allows a Directive of @bug to be used. Additionally, Aliases can be used to provide a mapping from some other source that happens to match a supported JEMH Field Processor format, for example, if a remote system created a value:
Related Systems: this,that,the other
This value could be mapped to components by setting up an Alias components with a value of Related Systems.
Email Selection
Pre-processing
Attachments
Addresses
Sender address Processing
CC address Processing
Templates
Queue
Whitelist
Defaults
Greylist
Blacklist
Notifications
Defaults
Directives
Defaults
Field Processors
Defaults
Field Processor Enablement
Development
Defaults
Blacklisting
@Since 1.2
Blacklisting is where global blacklist configuration can be made. These settings allows, for example, 'Out of office' emails to be explicitly blocked for all configurations (over and above what is defined within a Configuration.
Template Sets
Template Sets allow configuration of all JEMH injected text and/or notification content, providing Subject, and Text/HTML content template editing as applicable.
JEMH Template Sets and 'normal' JIRA notifications
To be clear, JEMH Templates are not replacements for JIRA email templates and do not change them, primarily this is due to a 'bug' that the default Atlassian Issue Event Listener cannot be removed/replaced JRA-19957.
JEMH contains velocity templates for its notifications within the plugin. TemplateSets provide a means for the end user to customize the content of emails sent by JEMH without requiring unpacking /repacking/ redeploying of the plugin. JEMH allows customization to vary, so that different projects can receive different styles (though at this time, JEMH does not help you design those emails).
Template Set: JEMH Comment Header
This is a simple comment header that prefixes inbound email descriptions/comments indicating that the value came via email, and who it was supposedly sent from:
Template Set: Issue Event Template Set
@Since 1.2
Issue Event templates are also included, specifically for use with non JIRA account holder notifications.
Issue Event Templates, unlike JEMH Templates are not bundled with JEMH, they are read from JIRA. When an Issue Event Template Set is created, a snapshot of the current JIRA Template is made, allowing that particular template to be customized for one particular project, or shared across several. Future changes in JIRA may require maintenance to these templates, that work must be accepted as part of upgrade testing!
The Issue Event templates are located in JIRA under $JIRA_INSTALL/atlassian-jira/WEB-INF/classes/templates/email/...
JEMH Issue Event Template Sets provide a means to not only customize the Text and HTML content, but also the subject, to a point. Rendered templates are the same as JIRA users receive.
Template Set: HintOgram Template Set
The HintOgram optional mechanism is JEMH's way of communicating processing failure. Due to the noise that this can create, these notifications can be routed to an admin (who could perhaps fix the problem or communicate to the user that priority: broken is not valid).
HintOgram emails look like:
HTML | Text |
|---|---|
 |  |
Template Set: Forward Template Set
Forwarded mail is sent on by JEMH to a nominated user email address, in the format selected as preferred by that user. The templates are currently 'functional' but can be customized.
Template Sets - how are they 'used'
JEMH Profiles define how most TemplateSets are used, if the 'Default' is selected, the uncustomized 'internal' default JEMH template is used.
why are 'Create Issue' notifications in JEMH Profiles?
Due to JEMH heritage, the issue created event was the first created, and is driven by JEMH after it has finished doing everything. Currently JEMH does issue creation in two stages, 1) creation, and 2) setting various custom fields. At this time, the Issue Event notification can't send out notifications to non JIRA account holders in response to emails because the custom fields are not populated at the time that (1) occurs.
The Issue Event listener config does list issue created, as it is possible that a JIRA user may create an issue, and manually include non-jira user email addresses.
This will be fixed at some point after all key features are in place.
Test Cases
Test Cases allow rapid testing of email content against configurations and completely bypasses inbound mail handlers, so a configuration can be validated before being hooked up to the outside world. A TestCase email is the native raw text email content that travels over the wire, not just content. Test Cases can be generated from Audit log information for problem diagnosis.
Notifications
Notifications are configured on a per project basis to notify users by email addresses found in a custom field (that JEMH can be configured to populate on the way in). Notifications can use default templates, or make use of customised content through the Issue Event Template Sets.
Certificates
An initial implementation of GPG Security for signed email validation. This implementation natively executes GPG binaries, and has been validated on Linux only, other platforms should work.
Auditing
Auditing allows a historic view over processed data, enabling tracing of an email to an issue.
An audit log for the processing is available that @Since 1.2 contains any Hints that were generated as part of processing that may have caused the processing to fail for some reason (e.g. reporter doesn't have correct permissions for action).
All inbound mail is captured and stored (on the file system under JIRA_HOME/data/jemh) irrespective of processing status
Audit mail can be exported (for support/diagnostic purposes) as well as being converted into a Test Case for local configuration testing.
Credits
@Since 1.2
As the application grows, various libraries and third party components are being pulled in. The credits section provides attribution to the author(s) of those works and indicates the license under which they are used.
Licensing
Always available, provides access to current license status, as well as the online shop.
