Quickstart

This quickstart shows the bare minimum that needs to be done to get issues created in a project via JEMH.

Step 1 - Install

Search for and install JEMH through the Jira Universal Plugin Manager (see how).

Step 2 - Install an Evaluation license

Once installed, you would need to get an license from Atlassian in order to use and configure JEMH. You can get and install an Evaluation license from Atlassian by:

Pressing Free Trial on the JEMH app with Jira > Manage Apps and this will then take you to Atlassian billing website to generate license.
Once the Evaluation license is generated, you can then install Evaluation License in the License Key in the JEMH App list within Jira > Manage Apps.

Once installed, JEMH is now usable and configurable and can be accessed JEMH by either:
- Pressing full stop
  on your keyboard followed by jemh and pressing Enter/Return,
- Or going to Jira Administration > Manage apps and choose Configure when JEMH is selected.

Step 3 - Create a Profile

Create Via Welcome Wizard

When the JEMH configuration screen is first opened, and no existing profile is defined, JEMH will display a Start-up wizard, which will walk you through creating a new Profile, with a Catch Email Address, Project Mapping and with Non Jira Users Support.

See Wizard Configuration heading below for more information about the wizard.

Create Via JEMH > Profile > Create Profile

If you do not see the Start-up wizard then you can create a new Profile by going to JEMH > Profiles and then press the Create Profile button (highlighted in red on below image) and this will trigger the Wizard to appear at the step of creating a Profile and will also go through the following steps to create a Project Mapping and configure Email Only Users support.

See Wizard Configuration heading below for more information about the wizard.

Wizard Configuration

The Wizard is used to create a Profile with default configuration that will immediately allow issues to created within the configured Project and to also allows comments to be made on existing issues. The steps shown within the Wizard will create a Profile with a Default Project Mapping and with Email Only Users Support.

Create Profile step

The first step within the Wizard is to create a Profile. Here you will specify the Profile name, a Catch Email Address (mailbox Address) and if you would like the profile to be part of a Profile Group.

What is a Catch Email Address?

A catch email address is an email address that your JEMH profile is configured to receive emails to (the address of the mailbox that JEMH is connected to). You should always specify a list of catch email addresses for mailbox address that you have configured JEMH to handle email from.

JEMH automatically filters catch email addresses from email notifications by not adding the matching addresses to the issue. JEMH does this so that you do not notify your own JEMH incoming mailbox of issue notifications, not specifying a catch email address can cause the JEMH mailbox to be notified of issue events that can then lead to a mail loop.

Create Project Mapping

This step will create a default Project Mapping, this allows all emails processed by this profile to create issues within this Project. At this step it allows you to select the Project, Issue Type and Priority.

If you select a JSM Project then you would be able to select a Request Type that is scoped to the selected Issue Type.

Configure Email Only Users

If you wish to allow Email Only Users (sender/recipients with no Jira Account) to create and comment on issues, then this step allows you to select Custom Fields to store these email addresses within to allow them to comment on the issue. If you do not already have Custom Fields created, then you can press the Auto create Custom Fields to allow JEMH to automatically create these Custom Fields for you.

For more information about Email Only Users see: Enable non-Jira Account holders to receive issue updates and create/comment on Issues

Default Reporter

This feature requires a Default Reporter to be set within the profile, as this would be the user to create issues and comments on behalf of the Email Only Users. See Update the profile configuration with a Default Reporter heading on this page.

Wizard Summary step

The last screen is to highlight the next steps to allow this profile to be used for processing incoming emails, which also covered within the Configure Inbound Mail Handler heading on this page.

Update Configuration Manually after Creation

Updating catch email address within Profile

After the Profile is created the Catch Email Address can be modified within Profile > Email > Email Selection and then you can either Edit an existing Catch Email Address or add an additional Catch Email Address

These Catch Email Address are also compatible with Regular Expressions

Update the profile configuration with a Default Reporter

The Default Reporter is used to create issues on behalf of users who either lack application access or the right to create issues, the Default Reporter is also the reporter for issues created by Non-Jira users. Fore more information about situations when the Default Reporter is used see: Create Issues (from Jira 7.0).

The Default Reporter will require issue permissions in the associated projects that your JEMH profile will be interacting with.

Legacy configuration

Click Configure next to your created profile to access the profile configuration screen.
Locate the User section and press the Edit icon
to modify the configuration.
Define the username of your desired Default Reporter within the Default reporter user name field. In this example the username of my Default Reporter is admin.

Current Configuration

Go to JEMH > Profile > Configure > Project Mappings > Edit
Under the “Issue Attributes” heading, find the Reporter field and add the username of your desired Default Reporter.

Updating Default Project Mapping

JEMH Issue Creation is driven by Project Mapping's. A Project Mapping contains project specific JEMH configuration to be used when processing emails for the project defined in the Project Mapping. When processing an email JEMH will evaluate all Project Mappings defined in a profile to try and locate a Project Mapping with rules that match the email being processed. If a matching Project Mapping is found, an issue will be created in the project linked to the Project Mapping. If no Project Mapping matches via a rule, an issue will be created in the Default Project Mapping if one is defined. For this quick tutorial we have configured JEMH with a Default Project Mapping so that all incoming emails that do not result in an issue comment will result in issue creation inside the project defined in the Default Project Mapping.

The Default Project mapping can be updated by doing the following:

Click Configure next to your created profile to access the profile configuration screen.
Locate the Project Mappings section
Press the Pen icon on the Project Mapping that has the Default Lozenge
Within the Project Mapping you would then be able to modify the configuration that will apply for this Project Mapping, e.g. Issue Type and Priority

Step 4 - Enable JEMH Auditing

JEMH Auditing is used to keep a record of all emails that are processed and will also has a Report that describes the processing that has occurred, allowing you to review if emails resulted in an unexpected outcome. For more info about auditing see: Use Auditing

Got to the Auditing Tab within JEMH and press Settings
Enable the required Auditing types. We recommend enabling Inbound Auditing as this will allow you to review the processing for inbound emails.
Set the relevant Retention Settings. This is used to set how long you would like to keep these audits for.

Step 5 - Create and run a Test Case

Go to the Test Cases Tab within JEMH and click Create
The Test Case editor will load with some example content pre-populated, your profile should already be selected in the Profile field.
The Content field contains the raw content of an email, think of it as the source code of an email.
Modify the From: line in the Content field to contain the email address of a Jira user who has permission to create issues in the project defined in your Project Mapping. In the below example I have modified the from address to be the address of a Jira user named Bob.

Modify the To: line to match the address of your catch email address that you defined in the earlier step. My catch email address was support@test.com so I will use that.

Press Create after modifying the from address with the address of a valid Jira user and modifying the to address to match your profile defined catch email address.
The Test Case is now shown in a view of all Test Cases, press Run to run the test case.

The result screen will show you some basic information about the processing outcome, including a link to your first issue. Click the issue key to see the issue that JEMH has created!

Step 6 - Create an inbound mail handler

If you have yet to setup inbound email, do so now. Once an inbound mail configuration has been setup (files/POP/IMAP):

Go to Jira Administration > System > Incoming Mail and click 'Add incoming mail handler'
Give the handler a name, select an appropriate Server, and be sure to pick Jira Enterprise Mail Handler, then click 'Next'

Read emails as read option can only be enabled when using IMAP as the connection protocol. If this is not enabled then Jira will delete the mails after they are processed. If enabled then Jira will only mark these as read, allowing the mailbox copy of the email to be kept.

In this screen, just select your Profile from the list and press Submit.
Once this is configured you will then see the newly created Mail Handler with JEMH set as the handler

Forward email?

Unlike Jira mail handlers, JEMH owns all functionality within the mail handler space, including error management and notification. A dummy value is provided to satisfy Jira error checking, to modify the 'forward' user, go to the JEMH Profile/Configuration/Notifications section. JEMH allows both users and static email addresses for forward notifications and there must be at least one user or email address for JEMH to process forward notifications.

What next?

Now that the basics are covered there are a number of features which are still basic, but more specific to your own specific use cases, specifically Project Mappings, and Project Mapping Rules. We recommend the following pages for a more robust configuration:

Send Notifications through JEMH

JEMH has a broad set of features related to Inbound Mail Processing, and Outbound Notifications. Where you go next depends on what your specific requirements are. As an example, JEMH enables full trip Notifications for Jira Users and Email Only Users (Non-Jira Users), as well as Ad-Hoc Notifications send directly from the Jira Issue View. For more info please see:

Extract data from emails to add to the Issue

JEMH has a range of Email to Issue data processing methods (Field Processors), from simple key value pairs, to fully custom scripting. The following pages detail how these can be used:

Two minute JEMH quickstart