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
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.
Allow Anonymous Commenting - Allows anyone who uses the issue key in the email subject to comment on a issue.
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.
Treat Unprivileged users as non-Jira - This will treat users with no issue permission or right to use as a “email user” with the reporter being the “default reporter”.
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.
Comment Visibility Optional - This will set the comment as non-restricted when the commenter does not have the group or role set in Comment Visibility.
Jira Service Desk
External Customer Comments Enabled - This will allow customers to comment on an issue even if they are not an issue participant
Project
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
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.
User Directory - Defines the User Directory to add the newly create to. Use the DEFAULT (first available writable directory in the Jira User Directories list) OR pick a specific directory.
Require Sign-up Email - If enabled, Users passing the user creation checks will be required to click an acknowledgement link in order to have the account created.
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)
Alternate ID Provider - Defines the ID provider that should be used when creating the user Id.
Create from Email condition - This defines when the user should be created from an email. The two options are:
Always
Exist in alternate only
Allowlist 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).
Blocklist 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.
Auto Join Group Condition - Controls when auto-joining groups occur. The three options are:
On User Creation
For All Jira Users
On Creation or For users Without Groups
Force userId Case - This will force the userId to be created either in lower or upper case.
Selected LDAP Config - Defines the LDAP configuration that should be used when creating new users.
Issue
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).
Comment - A fallback comment that is used in place of an empty one.
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.
3rd Party CF Support - If enabled, JEMH will attempt to initialize 3rd party Custom Fields with String (text) values supplied. Problems with such initialization will be logged at INFO level only.
Add Issue Entity Properties - This feature helps mail clients thread Jira notifications in the conversation that drove their creation. It enables JEMH to store the incoming message Message-ID, References and In-Reply-To headers during issue creation
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
Truncate
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
Operating Mode - This indicates the mode that the Profile will run as.
Catch Email Address - This is a specific address that should be found within the email. If this is not found then this Profile will not process that email.
Catch Email Headers - This is a CSV list of headers that the Profile should check when attempting find a matching Catch Email Address.
Message Filtering
Non Catchmail Match Action - This identifies the outcome that should happen with the email when there is no matching Catch Email Address within the email.
No Issue referred in CommentOnly mode Action - This is the outcome that should happen when the email is not related to an existing issue. This option will only run when the Profile is in the Comment Only mode.
Pre-processing
HTML
Labels
Attachments
Addresses
Sender address Processing
Jira User
Jira user sender to User Picker custom field - This is a User Picker Custom Field that the sender Jira user should be placed into when creating a new issue.
Jira user sender address to Text custom field - A Text Custom Field that the sender Jira user Address will be placed into when creating a new issue.
Jira Service Management
Add Organization member as Request Participant - Adds Sender who is part of Organization as a Request Participant.
Non-Jira user
Non-Jira user sender name to Text custom field - The text Custom Field that the Email sender name will be added into.
Non-Jira user sender address to Text custom field - The text Custom Field that the Email sender address will be added into.
Addressee Processing
Assignee
Use first valid user as assignee - During initial issue creation, addressees are checked for ability to become assignee in the issue, starting with TO: then CC:
Templates
Queue
Auto Flush Queue - As soon as processing is complete, flush the queue for immediate delivery
Allowlist
Allowlist
Sender Must Have Account - This will only allow sender who have an account to create new issues.
Allowlist Senders - This is a Regex configuration that will only allow matching users to create new issues.
Blocklist
Blocklist Senders - Regex configuration that will stop matching senders from creating new issues.
Blocklist Recipients - A Regex configuration that will stop matching recipients/participants from being added to the issues.
Blocklist Match Handling - This identifies what should happen with the email if the sender has been Blocklisted
Notifications
Forward User
Project Lead as Forward User - This identifies that the Project Lead should be notified of a email processing failure.
Forward Users - This is a CSV list of Jira users that should receive forward notifications when they occur.
Hint Notifications
Hint Notifications enabled - When enabled this will send notifications back to the original sender when their emails did not result in a issue/comment being created. These notifications will identify why the email was not successfully processed.
Override Hint Notification email address - This allows you to override the recipient of Hint Notifications so that only one specific email recipient receives these notifications.
Notify Sender of Forward - When JEMH's processing results in a Forward outcome, a Hint Notification email will be sent to the sender (or nominated override account) to aid in fixing the problem
Issue Events
On Comment Event Behaviour - This is used to identify the event that should be triggered when a comment has been added.
On Create Custom Event - The Custom event that should be triggered when a issue has been created.
On Comment Custom Event - The Custom event that should be triggered when a comment has been added to an issue.
Directives
Directive Processing Behaviour - This identifies when Directives should be applied. The options are:
On Create or Comment
On Create
On Comment
Disabled
Use Translated Field Names - When enabled, will also scan Custom Field name Translations for a match with Directives.
Field Processors
Defaults
Field Processor Enablement
Basic - no-op mail processor, no directives possible.
At(@) Prefix - Keys are prefixed with @, eg @key = value.
Colon Suffix (Mailform) - Keys are suffixed with :, eg Some Key: value.
Subject - Subject content keys are prefixed with #, eg #key ="some long value".
Regexp - Allows regexps to identify 'values' in emails to be used in Jira issue queries, for locating issues to comment on.
XML - Body content follows XML structure (defined on wiki).
CSV - email containing an attachment with CSV values identifying issues (defined in wiki).
X-JEMH Header - The X-JEMH Header Field Processor allows a text payload to be solely concerned with content.
Nagios Notifications - Nagios generated emails, specific content extracted from subject and body.
Script (Advanced) - Allows custom email processing behaviour via scripts.
Third Party Field Processor Enablement
Enabled third party Field Processors - This is a list of Third Party Field Processors that have been added to JEMH/Jira. To select/deselect the relevant processor you will have to use Ctrl + Click.
Indicate active Field Processor/Profile - This will prefix the description/comment with text identifying the Field Processor that was used and from what Profile.
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.
