Two minute JEMH quickstart

Owned by Andy Brook [Plugin People] (Unlicensed)
Last updated: Feb 14, 2024 by Ryan Clifton
7 min read

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, access 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.

  • Go to the Licensing Tab and from the Shop Form, select 'Free 30 day evaluation' for now.  Follow the prompts and enter a valid email address - this is where the license KEY will be sent.

  • Check your email inbox, the KEY should be delivered nearly immediately.  If you don't receive anything after 30 minutes, its possible there is a problem - use the manual 'by Email' link instead.  You will then need to wait for us to get in contact.

  • Highlight the license key in the received email, ensuring that the leading <JEMHLicense> and trailing </JEMHLicense> tags are also present.  Copy the selected text.

  • Paste the license key into the License Entry form and hit submit.  The response should be affirmative, and more of JEMH's navigation menus will be visible.

Step 3 - Create a Profile

  • Go to the Profiles Tab and click Create a Profile.  Enter a name for reference, e.g. Test.  Then, click Submit.

Step 4 - Update the profile configuration with 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 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.

  • Click Configure next to your created profile to access the profile configuration screen.

  • Locate the Email section and press the Edit icon 

     to modify the configuration.

  • Within the Email Selection tab modify the Catch Email Address field and insert the email address of the mailbox where JEMH will be receiving email. In this example emails are being sent to support@test.com. Multiple addresses can be added to this field.The Catch Email Address field is also compatible with Regular Expressions

Step 5 - 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. 

  • 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.

Step 6 - Create a 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 are going to configure 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.

  • Click Configure next to your created profile to access the profile configuration screen.

  • Locate the Project Mappings section and click New Project Mapping to create a new Project Mapping.

  • Define the mapped project for the Project Mapping via the Mapped Project field.

  • Check the Is Default Mapping checkbox to make this Project Mapping the default.

  • Scroll to the bottom of the page and press Save.

  • Within the Project Mapping select Issue and select a valid issue type via the Issue Type field. (Make sure that the selected issue type does not require fields for issue creation, if a field is required for issue creation and a value is not specified, issue creation will fail.)

  • Scroll to the bottom of the page and press Save

Step 7 - 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:

  • 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 8 - 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 9 - 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'

  • In this screen, just select your Profile from the list and apply.

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.

Related Articles