Introduction

since 1.9.10

Sending mail from a common mailbox to multiple profiles previously required using a mail handler for each profile. This approach has its drawbacks - as the number of mail handlers increases, the amount of mail server traffic increases. This leads to performance drops at both ends and mail contention issues. Profile Groups solve this problem by enabling a group of profiles to be linked to a single mail handler, through one group member which nominated as the default.

Operation

Issue creation

Profiles in a group should not define 'default projects' and 'default reporters' but tailor these values inside Project Mappings based on Rules.  When all Profile Group Members have run and failed to create an issue, the Default Profile is expected to be capable of routing the email appropriately, normally this would be done by setting a Default Project, and a Default Reporter, so ensure the message is not lost.  If the decision is made to not have a Default Project/Reporter, then messages will not be processed and be rejected.  Where messages pass through to be processed by the Default Profile, only that Profiles final determination of processing status matters, and drives subsequent forward notifications.

Commenting

During commenting, issue keys are identified from the email subject. If no valid one is found, mail threading headers (In-reply-to, References) can be used identify the target issue.  The first Profile that matches the catchemail will process the message.

Outcomes

The current implementation of this feature has some simple rules, when any Profile Runs the following outcomes are implemented:

Outcomes

The current implementation of this feature has some simple rules, when any Profile Runs the following outcomes are implemented:

Since version 3.3.40

Default Profile or Not resulting from a Filter Action

Filter Action Outcomes (non default profile)

Since version 3.4.0 and 4.0.10

Default Profile or Not resulting from a Filter Action

Filter Action Outcomes (non default profile)

Creating a profile group

When a profile is edited or created, there are a few settings specific to profile groups.

Open

Here, we set the Group Key and check the Default Profile check-box. Now the Profile screen shows a new section, where the Profile Group Key is used as a heading, with Profile Group Members listed beneath:

Open

Adding a profile to the group

Is as simple as creating a new profile, then editing it and setting the group key to be the same as the groups default profile:

Upon creation, the new profile is added into the group. , indicating processing order (ps when Group Orders are the same, the entity ID is used).

Note that the profiles are presented in the order they will be tested in (highest order first, default last). In the example below, "Alpha" will be the first profile to be tested. The default profile, "Group Default", will be tested last.

Group operations

Pressing the triple dots(…) on a single Profile will show the actions available: Configure Profile, Export Profile, Edit Profile, Copy Profile, Delete Profile and Update From XML.

When pressing the triple dots (…) on the Default Group Member Profile the actions available are:

• Configure Profile

• Export Profile

• Edit Profile

• Export Group

• Copy Group (this will create a duplicate of the entire group with -copy appended to the groupKey)

• Delete Group

• Update Group from XML

Note that exporting single profiles or profile groups does not export any notification templates that may be associated.

Selecting a Profile Group in a JEMH Mail Handler

In the JIRA Admin > System > Mail > Incoming Mail section, Mail Handler entries are added to associate an Incoming Mail Server with a handler.  Here we choose JEMH (of course!)

When Next is selected, you're taken to the JEMH Profile selection screen, where some new changes have been made, Profile Groups are represented by their Default Profile, member Profiles are not shown.  Single Profiles continue to be listed:

Selecting the group, and then submitting the form:

Will result in a new Mail Handler entry:

Going back to the JEMH Profile screen, the default Profile is shown as associated, indicating the group is hooked up to a Mail Handler in JIRA:

Processing reports

New in this release is the start of a flexible and readily expandable logging system that will allow per-issue processing logging to be made available. Its initially been added to support profile selection debugging but will in time absorb the existing Summary and Hint mechanisms.

Report Outcome

Auditing drill down

Accessed via JEMH Admin > Auditing (when enabled):

leading to:

Performance

IMAP

IMAP does not send the message in its entirety to JEMH. Instead, a basic outline is given, and subsequent calls are made to obtain content like body parts or attachments. These calls to the mail server are a common source of protocol-specific problems like FolderClosedException or IndexOutOfBounds errors. If multiple profiles are grouped together, this will naturally increase chatter and could potentially make processing more susceptible to errors.  Time of processing may also become a factor at scale.  A common solution is to enable auditing (with a sensible retention window) and within each Profile enable the 'Use PreProcessed Message' feature. This stops the IMAP related problems from occurring at arbitrary points in processing, and ensures that if things are going to fail, they fail early and consistently.

Use of POP

Where POP is used, the problems related to communication are pretty much resolved, however, many scenarios of invalid email formats can be resolved by still using the same 'Use PreProcessed Message' feature.  In all cases, the use of 'Use PreProcessed Message' is per-profile, so large messages, could potentially be read many times, https://thepluginpeople.atlassian.net/browse/JEMH-4440 is open for that.

Requirements for group Profiles

Members of a Profile Group should not be in a position to always process a message, that role is for the default Profile in the group.  If a group member has (a) no catchemail address / jemhAddresseeRegexp, and (b) a  default project OR a default Project Mapping, then issues could always be created through this path, the group would be broken, the default Profile would not be used.  JEMH will issue a Profile Advisory in this scenario:

Example usage scenario

With the following configuration mail 'to' email mailbox has been delivered to a common pickup point.  It means that one profile can pick all mail by an address match, then differentiate on how the are processed, perhaps based on the sender in a Domain Mapping rule (see Use Project Mappings):

Example given will show how Profile processing outcomes affect group processing with the following scenarios.  For simplicity, we'll use a default email Test Case for this example (see Use a Test Case) in the coming examples, 

Example for Alpha (catchemail match with default Project)

This test case can be run against the single Alpha Profile individually to confirm expected result, or the group, which should also result in the same outcome (issue creation in the ALPHA project).  The Profile uses the Default Project and Default reporter to create issues.

Here is the report (requires Auditing to be enabled):

Example for Beta (catchemail + default Project Mapping)

This test case can be run against the single Beta Profile individually to confirm expected result, or the group, which should also result in the same outcome (issue creation in the BETA project).  

If a Project Mapping is created and is created as the default, then it will be used to customize the issue creation, not only the Project, but many other fields  too (all those in project mappings).  No messages should be rejected to the beta@thiswontwork.com address.

Here is the report showing that the Default Project Mapping applied from Profile Beta:

Example for Gamma (catchemail + Domain Mapping rule based on sender)

This example Profile uses a Project Mapping rule, matching the sender of the message andy@localhost to the GAMMA project.  There is no Profile default project, so other senders to this mailbox will not be created through this profile.  Non-mapped senders would result in a reject outcome, which would trigger a hand-over to the other remaining profiles in the group.  Lastly if none can handle the email, it will go to the default profile.  This clearly demonstrates hand off to other group members for processing.

The report for the email sent by mike@localhost shows that the Gamma Profile Mapping rule did not match.  With no project determined, that fails to create an issue, and so is passed along the chain to the Default Profile, which (having a default project) creates an issue in that project:

Example for Default

See mike@localhost example above.

Related articles