Enterprise Mail Handler for Jira Cloud (JEMHC)

This wiki is for the Cloud based app. There is separate documentation for JEMH for Jira Server.

Overview

Enterprise Mail Handler for Jira Cloud (abbreviated to JEMH Cloud or JEMHC) is a next generation Software as a Service (SaaS) offering that provides extended email integration with Atlassian's Jira Cloud. It is the cloud based version of the established Enterprise Mail Handler for Jira Server. Like its counterpart, it's primary purpose is to:

  1. Integrate external users and external systems

  2. Automate the routing of messages to Jira projects

  3. Enable remote creation and manipulation of issues through email

  4. Allow complete control of outbound notifications (email or otherwise)

Email user support

Map remote users (by sender address) to specific Jira projects/assignees automatically

Jira user support

At this time, there are technical issues preventing a usable integration for remote users who's email addresses are associated with Jira accounts.  

  1. Looking up users as a remote add on is not possible right now - https://ecosystem.atlassian.net/browse/AC-1014

  2. Creating issues and commenting 'as' the user associated with an email address is not possible right now - https://ecosystem.atlassian.net/browse/AC-1080 the current workaround is to have issues and comments created by JEMHC and apply the 'comment header prefix' indicating sender email address.

System integrations

JEMH Cloud can be used to route remote server application exceptions to Jira projects without point-point firewall connectivity.

Prerequisites

  • At this time JEMH Cloud cannot be used with stand-alone Jira Server installation.  A Jira Cloud instance is required.

  • JEMH Cloud requires an external mailbox to retrieve mail from and send mail through. The mailbox provisioned by Atlassian used by your Jira Cloud cannot be used by JEMHC. Atlassian don't support 3rd party app use like this, and neither do we, as the password is periodically changed by Atlassian, which would break connections to JEMHC.  Consider using a mail host like Gmail, Office365 (or your own, so long as standard outbound SMTP and inbound POP/IMAP protocols are supported)

Pricing

More information on JEMH Cloud pricing can be found on the Licensing page.

Privacy

For Google OAuth app validation, we are required to statically host copies of our Privacy Policy and EULA under a top level domain. This can be found at http://thepluginpeople.com. Our Confluence wiki also contains the Privacy Policy and Cloud Software Product EULA.

JEMHC integrates with Atlassian to support right-to-be forgotten. Additionally, many notifications have additional unsubscribe features.

Security

See Technical Details related to data usage where a breakdown of the kinds of data that is stored in JEMH(Server) and JEMHC(Cloud) is given.

Message retention

JEMH Cloud stores every incoming message, in encrypted form in the database.  At most 50 messages are retained, old ones are removed as new ones are added.

Users wanting a 'mail archive' should consider using their mail server for this purpose, by auto-forwarding copies to an archive mailbox.

Credential storage

JEMH encrypts all user credentials in the database.

Differences between server and cloud

Please note the following difference between JEMH for Cloud and JEMH for Server/DC of configuration for Inbound Mailbox

In the JEMH for Server, you have to configure the Incoming mail connection in Jira > System > Incoming mail because JEMH does not communicates directly with the mailbox in order to retrieve the email and process them. However, in JEMH Cloud, you do not need to configure any connections in Jira > System > Incoming Mail as all configurations with your mailbox is done in JEMHC > Messaging.

JEMH Server wrapped up all configuration into a Profile. The addition of per-project Mappings and related Rules to drive selection of that project for issue creation were limited in the 'fields' that could be set. This results in scenarios where multiple profiles are necessary.  In JEMH Cloud, the Profile does not contain email processing configuration and all configuration is available through Project Mappings.

Terminology

Message Sources

Defines the connectivity details for message sources:

  • remote mail servers via POP/IMAP

  • FTP servers

Message Handlers

Association between a Message Source and a Profile (this is the same concept as Mail Handlers in Jira Server)

Message Outbound

Defines the connectivity details for a mail-host responsible fro outbound message notification.

Profiles

A Profile contains at least a Default Project Mapping and optionally many additional Project Mappings. The Project Mappings describe how emails should be manipulated and interpreted to create issues.

Project Mappings

Project Mappings allow processing configuration to be specified on a per-project basis. In order for a project mapping to be selected during email processing, it must have a valid Mapping Rule attached to it. A rule defines a condition that an email (or data derived from it) must pass, and is considered valid if its conditions are passed. A Default Project Mapping is always present, has no rules, and will be used if no other mappings apply.

Project Mapping Rules

Mapping rules allow specific criteria to be defined that an incoming email must meet to be considered a match for a Project Mapping. They can only be added to non-default Project Mappings, as the default mapping applies when no rule matches. Configuration is inherited from the parent Project Mapping, but optionally overwritten at the Rule level.

Directives

Directives are user supplied values found in an email with a particular format. They can be interpreted and used to affect how issues are created, or to make changes to a given issue, e.g. changing priority, summary etc.

Email Custom Field

JEMH Cloud Profiles define the custom field that will be used to store remote users email addresses. This custom field is a TEXT (multiline) custom field that is valid for the given issue. It has a simple comma separated format of user@place.com,user2@place.com,user3@place.com, no 'personal' parts are supported. When a Jira user makes changes or adds a comment to an issue, JEMH Cloud gets notified through webhooks:

Webhooks

Webhooks are the events that Jira generates in response to user activities on an issue. These changes drive JEMH Cloud notifications, but can also be stored as Preview Contexts. Unlike Jira Server, the webhooks have a much reduced event model (Created, Updated, Deleted)

Preview Context

Webhook data for a given issue ABC-123 can be stored, enabling Notification Templates to be previewed with real data

Notification Template

Notification Templates contain the Velocity markup that drives notifications, they can be TEXT or include HTML markup. Velocity Macros (Velocimacros) are also supported with a system macros and user definable macros.

Velocimacros

A set of JEMH Cloud system velocimacros provide a way to simplify markup, and, conveniently, enabling user to customise the presentation of specific fields and sections by overriding them through custom-specific macro content.

Themes

A Theme composes not only a Notification Template that is specific to Create/Update/Delete issue events but a common related Cascading Style Sheet (CSS). Themes can be customized! JEMH Cloud has two current themes, Jira and Generic. The Jira theme looks very similar to the standard Jira notifications that are already generated, the Generic theme has 'less', making it more suitable for a remote email only support desk solution. Themes can also incorporate images.

Images

Specific to HTML emails, images can be uploaded into JEMH Cloud, stored in the cloud, and referred by 'alias' within Notification Templates using a custom velocimacro. When HTML email content is rendered, URL's to those images are injected, resolving to The Plugin People's Content Delivery Network (CDN)

Test Cases

Test Cases are emails in their raw format. They are ideal for validation of Profile configuration. Received emails can be converted to a Test Case, or created from scratch, and are 'run' against a given profile.

Creation v.s. Comment

Emails with no issue key in the subject are treated as candidates for new issue creation.  Emails with a valid issue key in the subject are candidates for commenting.  JEMH Project Mappings apply during Creation of Issues only.

Data categories

JEMHC tracks resource use through Message Count and Data metrics.  Messages are split into 4 categories grouping the operations JEMH Cloud performs around inbound/outbound messages.  The JEMHC licensing screen allows administrators to monitor their usage!

  • Traffic In: Inbound messages processed in the 'normal' traffic flow (email->issue->webhook->notification)

    • Issue Created: An inbound inbound email creates an issue

    • Issue Commented: An inbound email generates a comment in an issue

  • Traffic Out: Outbound notifications JEMH Cloud creates in the 'normal' traffic flow

    • Notification Sent: The Email sent after receiving a webhook Event from Jira (e.g a user or JEMH Cloud created/commented an issue)

  • Maintenance In: Inbound messages that couldn't been processed in the 'normal' flow

    • Message Blacklisted: An processed inbound email has been blacklisted

    • Message Processing Error: An processed inbound email couldn't be processed due to an error

    • Limit Exceeded: An email cannot be processed as a limit has been reached (like Issue Comment Limit or Issue Comment Max Size)

    • Message Not Catch: An email cannot be processed as it didn't match any of the profile's catch email addresses

  • Maintenance Out: Outbound messages JEMH Cloud creates for maintenance reasons

    • Ping Sent: JEMH Cloud sends an email as result of the user testing Message Outbound configuration

    • Message Forwarded: JEMH Cloud forwards an email that cannot be processed (due to error, blacklisting, etc.)

On this page

On this space

Recent space activity

Space contributors