Introduction

A Project Mapping allows processing configuration to be specified on a per-project basis. This configuration ranges from basic attributes such as issue type, to advanced features such as workflow control.

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.

When you should use Project Mappings

JEMH Profiles can be used individually but, this doesn’t scale. You can save time/effort by using a Master Profile with many Projects supported, using common settings.

When associating an Incoming Mail Server with a JEMH Mail Handler, its perfectly fine to re-select a common Master Profile for processing configuration - unique profiles are not necessary and are an admin overhead!

Too Many Incoming Mail Servers / mailboxes?

Whilst Project Mappings reduce the need for many Profiles, if there are lots of Incoming Mail Servers, then there is still a performance issue (at retrieval time). Where mail comes from a common mail server, and where JEMH is consuming all mail from those mailboxes, consider setting up a Common mailbox for mail pickup (eg issues@blah.com), using Alias addresses for that mailbox such that alternate addresses (eg other@blah.com) are delivered for pickup from the common mailbox. Verify correct behaviour by adding the Alias address to your Profile > Email > Catchemail, and running a test case through, it should create in the Default Project Mapping (discussed later).

Some mailservers do not retain ‘alias’ addresses

If your mailserver does not retain the ‘alias’ address, we can’t help, you need to discuss with your mailserver admin on perhaps adding a Delivered-To header that contains such information, that JEMH can then find (which it does by default).

When separate profiles are needed

you have “a lot” of profiles that seem very similar to each other, with different mailbox addresses.
you want markedly different HTML formatting options, which are currently at the profile top-level
you want to do some script field processor and/or script rules that are applicable to one mailbox only (running script field proc and script rules unnecessarily is a CPU waste)-

Signs that a profile can be collapsed into a common one

you have one profile with a single 'default' Project Mapping, with no special Field Processors and pretty standard HTML options

For the above, you would have a Master Profile and:

update catchemail addresses to include any that are 'new' from the imported profile
add a new Project Mapping for that project, adding a Domain Rule to match the inbound mailbox address

Testing is simple, create a JEMH Test Case and set the to: address to be the mailbox address from the first profile, that was added to the master. Prove when running the Test Case against the master that the Rule matches, and the issue is created in the right Project, with correct issue types etc, and repeat.

Things to remember:

the master profile Default Mapping should be for a 'fallback' project, that is there to give you notice that no rules mapped. Resist the urge to make it the 'same' as a default, it will save you reporting problems about Rules not matching (and related issue params not applying), the outcome is always the same, that the rules don't match. It will be more obvious when this non-match creates issues in the fallback project.
body delimiter expressions are inherited, so put all your comment/reply-to clipping expressions in the Default
Project Mapping, they do not need to be repeated in non-default Mappings.
your default project issue attributes are inherited, this can be awkward if you have a project with say a custom issue type scheme or priority scheme, which is not supported by subordinate projects.

Creating a project mapping

From the main profile configuration page, click the Project Mappings.

You will then be taken to the project configuration home page:

Click the New Project Mapping action to create a blank project mapping. You will then be taken to the project mapping configuration page. The bare minimum required information for a project mapping is a selected project (unless it is a default mapping - more on this later). Select a project from the drop-down list in the Mapped Project field, and then press submit at the bottom of the page.

After Saving:

Project Mappings must have at least one rule attached in order to be valid for use during email processing.

Per Project Mapping customization

The values on the Project Mapping form allow customized issue creation on a per-project basis. These values are used as fall-back values if no other source defines them, for example, through Directives (if enabled) or, as will be covered next, within mapping rules.

Navigate to the Mapping Rules section, where you will be able to choose corresponding rule and configure it.

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.

Sorting

Mappings are sorted by project key, then mapping rules are checked in the following order:

Script rules
Domain rules (Sender then Addressee) - regular expression values are sorted case insensitively
Group rules (Groups are pre-sorted by JIRA)
Keyword rules (CSV value is treated as a single string value, sorted case insensitively)

Script Rule

This rule allows custom logic to be used to determine if a match is made. More information on using the script rule type.

Domain Rule

This rule checks the sender or recipient addresses of an email for a match against the user-defined value. This value is regular expression capable, meaning that a pattern can be defined instead to allow matches to many different addresses.

Addressee / Sender

When using Domain mapping, the regular expressions used can be used against either the incoming email address (the addressee) or the sender. Each state is inferred by the checking (or not) of Match against the addressee. Be sure you check this (or not) as required.

Click on Domain Rules > New Domain Mapping to create a domain based Mapping Rule. You will then see the domain rule edit screen:

After saving and clicking on the Domain Rules at the top

You can view the created Domain Rule:

Addressee Rules function as Catchemails

since JEMH v4.1.12 (Jira 9+ only)

To save duplicate data entry for Profile > Email Catchemail Addresses, Addressee domain rules are now interpreted as a ‘mailbox address’ and are now effectively the same as Profile > Email Catchemail Addresses. Profile advisories will be issued to highlight redundant Profile > Email Catchemail Addresses entries.

Group Rule

Group mapping rules allow routing of mail based on JIRA user group membership. Therefore the user sending the email needs to be associated with a JIRA account for this rule to work.

After saving and clicking on the Group Rules at the top, you can view the created Group Rule:

Keyword Rule

Keyword mapping rules allow routing of mail based on specific keywords that are found in the subject or body content.

After saving and clicking on the Keyword Rules at the top, you can view the created Keyword Rule:

Rule Evaluation Strategies and Rule Priority

It is possible to adjust the strategy that JEMH uses when evaluating rules. As well as the firstMatchWins strategy, it is also possible to evaluate by rulePriority. This selection is made in the Profile > Project Mappings:

First Match Wins

This is the default strategy. The Project Mapping engine will scan rules in each defined Project Mapping, testing each ones Rules in the order Script, Domain, Group, then Keyword. The first rule to match wins, and no other rules are tested. This allows minimal processing overhead relating to rule evaluation.

Rule Priority

With the rulePriority strategy, the Project Mapping engine scans ALL defined Project Mappings, testing each ones Rules in the order Script, Domain, Group, then Keyword. The first matching rule is considered the best. Subsequent rules are then tested, and must have a higher priority in order to become the new leader. For example, a rule with priority 5 will be considered better than a rule with priority 6. A priority of 0 (default priority) can match, but any other rule with any priority will beat it. For example:

1 = highest priority
2 = high priority
3 = lower priority
...
0 = default priority

Changing rule priority

Once the rulePriority strategy has been enabled, editing any rule will display a priority field:

Each rules current priority can be viewed at either the rule level or mapping level:

Viewed at project mapping level	Viewed at project configuration level

Viewed at project mapping level	Viewed at project configuration level

Processing-time feedback

When running Test Cases, and shown in Auditing, some more information is available to help users understand what rule matched and was applied, here is an example relating the the above, the domain of the sender is .*@localhost

MIME-Version: 1.0
Received: by 10.223.112.12 with HTTP; Sat, 18 Jun 2011 22:42:26 -0700 (PDT)
Date: Sun, 19 Jun 2011 17:42:26 +1200
Message-ID: <BANLkTinB1mfSh+GwOXGNWoL4SyDvOpdBoQ@mail.gmail.com>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@localhost>
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8

some text

Running this test case results in a match on domain, the TestCase result / Auditing detail shows the type of Rule that applied (domain) and some related details, in this case, what matched (email sender address), why (rulePriority), what mapping was applied (project), what priority the rule had (0 = default), how many rules were evaluated (illustrating that all rules defined will be scanned, and the overall time taken for that evaluation:

By adding 'testing' to the email subject above, re-execution of the Test Case shows that the higher priority Keyword rule now matches:

Rule Sorting Method

This is the method that is used to order rules for evaluation. This setting is set on a per-project basis. This really only matters when firstMatchWins is selected for the rule evaluation strategy (as with rulePriority all rules are evaluated so order is not relevant). There are currently 2 options. The default, byKey, offers a standard ordering, whereas byIndex allows fine-tuning of the ordering to possibly reduce the time taken to find a match.

The byKey sorting method uses the natural rule value, such as the rule's address, name of a group or its keywords. Essentially, in this case the order shown in the UI is the same order that will apply at run-time.

If the Sort Method is changed to byIndex (and you have submitted the change), upon looking at a mapping rule, a new Sort Index field is visible. This field takes an integer (number) value only.

Adding a few of each kinds of Rule, the effects of the sorting are visible. There are also one-click Up/Down action links that work by switching the position of the two entries (currently the up/down actions page refresh - in future this will be improved with AJAX):

Domain Rules	Group Rules	Keyword Rules

Domain Rules	Group Rules	Keyword Rules

Default project mapping

The Default project mapping applies when no other mapping is found to match. It allows issue attributes to be inherited when they are not defined elsewhere. Unlike a normal project mapping, default mappings do not have any rules associated with it.

To set a mapping as the default, enable the Default Mapping check-box setting and submit the form.

Once Submit has been clicked, re-edit the default mapping. You will see that the words "Default" will appear next to the issue attributes fields to signify that that any values that the user enters here will be used as the default:

Features

Issue attributes are applied from the Default Project Mapping even when projects are defined through Directives or subject-> project addressing (e.g. assignee+project@domain.com)
As the default values are not necessarily specific to any project, they are entered as TEXT and are not validated until runtime against the given project.
Components defined here are a special case. If at runtime the given project does not have nominated components, JEMH will create them dynamically. This is primarily to help with existing workflow validators that require components to be selected.

Field Inheritance

If a project mapping rule matches and is declared the "winner", itself and its parent Project mapping are the entire scope for declaring issue attributes.

As of JEMH 2.0.11, Custom Field Defaults are subject to inheritance in project mappings. If a custom field default is created on the default project mapping, it will be inherited by other project mappings unless they override them. Similarly, custom field defaults created on a non-default project mapping will be inherited by its mapping rules, unless overridden at the rule level.

The following fields can be defined on a Rule, if they are not, then the parent Project Mapping is used, if no values are set, then the Default Project Mappings is used, some caveats are indicated:

priority
issueType
affectsVersion
fixForVersion
labels (additive)
reporter
assignee
watchers (additive)
securityLevel
viewableBy
autoJoinGroups
Custom Field Defaults

Workflow Rules are not current inherited.

Enterprise Mail Handler for Jira Data Center (JEMH)

Use Project Mappings