1 What are Directives?
2 Issue fields
3 Custom fields
4 Issue association
5 Issue links
6 Workflow transitions
7 Logging work on issues
8 Special Processing
9 Blocklisting and Allowlisting
10 Customizing the Hint/Reject Emails
11 Trouble Shooting
12 Related Articles

What are Directives?

Directives allow emails to direct JEMH on what issue attributes should be used during issue creation or update. Along with Project Mappings, they are one of the main ways to ensure that Jira is given all the information it requires to perform issue creation or modification.

By default, Jira requires at least a project, reporter and assignee to be defined. Additional fields may also have been made required for creation of issues. Directives allow this information to be specified by users.

Remember to enable Directive Processing Behaviour under Profile>Directives, if you wish to make use of email-based directives.

Field Processors

Directives in an email are found by Field Processors that are currently enabled in a profile. When an email is processed, each enabled field processor looks for directives. The one that finds the most is used for that email.

Security and global settings

The intention in JEMH is that the Jira security model is followed, and that Global Settings are adhered to. For example, you will not be able to comment on an issue if the reporter does not have comment permission. Similarly you won't be able to add an Attachment if Attachments are disabled via profile configuration.

Directives are flexible

Directive keys and values are not case sensitive, for example "bug" and "Bug" are both acceptable
If a value is a JIRA constant (issue type, priority etc.) then either its ID or name will work

Issue fields

Project

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`project`	`@project = support`	`#project=support`

Reporter

Allows overriding the reporter that would be determined via profile configuration for the email. The value must identify an actual user by their username, and not their email address.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`reporter`	`@reporter = auser`	`#reporter=auser`

Assignee

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`assignee`	`@assignee = auser`	`#assignee=auser`

Issue Type

The value can either be a name or ID number.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`issueType`	`@issueType = bug`	`#issueType=risk`

Priority

The value can either be a name or ID number.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`priority`	`@priority = critical`	`#priority=1`

Components

The value can either be a name or ID number.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`components`	`@components = Component One,Component Two`	`#components=12345`

Watchers

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`watchers`	`@watchers = auser`	`#watchers=auser,buser,cuser`

Due date

Note that from JEMH 2.5.1 date values supplied by email directives are locale sensitive. This means that for example, a Jira user who's profile is set to Spanish should send date values such as 3/ene/19 instead of 3/jan/19. In earlier versions date values should be sent using the system default locale.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`dueDate`	`@dueDate = 1-May-2009`	`#dueDate=1-May-2009`

The due date value format must match one of the following:

Format specified through the dueDateFormat directive (e.g. dd-MMM-yyyy, see SimpleDateFormat).
Jira system date format setting jira.date.picker.java.format found via Jira Administration > System > General configuration > Advanced Settings.

Due date format

Used in combination with the due date directive. This is only required if using a format other than the Jira system format (see due date section for more information).

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`dueDateFormat`	`@dueDateFormat = dd-MMM-yyyy`	`#dueDateFormat=dd-MMM-yyyy`

Original Estimate

The original estimate for work can only be set during issue creation. The directive value must follow the standard Jira duration mark-up.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`workEstimate`	`@workEstimate = 1w6d3h2m`	`#workEstimate=1w6d3h2m`

Affects Versions

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`affectsVersions`	`@affectsVersions = 1337`	`#affectsVersions=1337`

Votes

The ability to vote on an issue can be done through an email Directive (as long as the related issue is somehow identified):

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`vote`	`@vote = true`	`#vote=true`

Security level

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`securityLevel`	`@securityLevel = 1234`	`#securityLevel=1234`

Custom fields

Custom fields using any the standard custom field types can be set via email. Non-standard custom field types may also be supported, if they can take String values of a known format.

The directive key identifies the custom field. This can be the field’s name, or its ID in String form. The directive value needs to be in a valid format for the given custom field.

Lists and arrays of values are supported as Comma Separated Values (no additional white-space)
Cascade Selects are supported through the format Your Custom Field Name=First Selection,Second Selection

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
Name or ID of field e.g. `My Custom Field`	`@My Custom Field = value for my field`	`#customfield_10105=value for my field`

Using Directives with different Custom Field Types

When using different field types you must follow the supported format as if a different format is used it will mean that JEMH will not be able to set the value within the Custom Field.

Below are some examples using the At(@) Prefix Field Processor. For more info the At(@) Prefix Field Processor see: JEMH Mail Field Processors | JEMHMailFieldProcessors At(@)PrefixFieldProcessor

Field Type	Additional information	Example using At Prefix Field Processor (in email body)

Field Type	Additional information	Example using At Prefix Field Processor (in email body)
Checkboxes	Value must already exist as an option within the Custom Field Configuration.	`@Custom Field = value`
Date Picker	Dates must follow the `dd/MMM/yy` format.	`@Custom Field = 24/nov/22`
Date Time Picker	Date Time values must follow the `dd/MMM/yy h:mm AM/PM` format.	`@Custom Field = 28/nov/22 9:30 AM`
Labels	Value does not have to already exist as JEMH can create new labels.	`@Custom Field = value`
Number Field	Largest value is 100000000000000	`@Custom Field = number value`
Radio Buttons	Value must already exist as an option with the Custom Field Configuration.	`@Custom Field = value`
Select List (cascading)	Value must already exist as an option with the Custom Field Configuration.	`@Custom Field = First value, Second value`
Select List (Multiple Choice)	Value must already exist as an option	`@Custom Field = First value, Second value`
Text Field (multi-line)	Multiple line values can be used with this Custom Field.	`@Custom Field = value`
Text Field (single line)		`@Custom Field = value`
URL Field		`@Custom Field = value`
User Picker (single user)		`@Custom Field = Username`

Issue association

Issue key

Used to comment/update pre-existing issues. This overrides any issue key found in the subject. Additionally, the target issue can be identified through a simple custom field query:

Example	Description

Example	Description
`issueKey=ABC-123`	The issue ABC-123 is used for operations within the email and for commenting. If the issue is not found, the email will be rejected with hintOgram messages
`issueKey=Some Custom Field=2378434`	When the directive value is found to not be an issue key, its treated as a JQL query. The first matching issue with the given Custom Field (e.g. 'Some Custom Field') with a specific value would be used as the target.

Sub-tasks

Sub-tasks can be created by telling JEMH what the parent issue is. This parent issue can be specified with an issue key or a simple custom field query.

Example	Description

Example	Description
`parentIssueKey=ABC-123`	The issue ABC-123 is used for operations within the email and for commenting. If the issue is not found, the email will be rejected with hintOgram messages
`parentIssueKey=Some Custom Field=2378434`	For example, when the value of the parentIssueKey does not resolve to an issue, its treated as a query, such that the fist matching issue with the given Custom Field (e.g. 'Some Custom Field') with a specific value would be used as the target.

Currently only the 'Sub-task' issue type is supported (it must exist). HintOgram notifications will be issued if the 'Sub-task' issue type doesn't exist or if Jira has not got 'sub-tasks' enabled.

Issue links

Used to link one issue to another. It is possible to indicate direction of the created link, for example: CONF-1/relates,to:JIRA-3/relates,from:JIRA-4/duplicate.

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`linkto`	`@linkto = CONF-1/duplicate`	`#linkto=CONF-1/duplicate`

Workflow transitions

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`workflow`	`@workflow = resolve`	`#workflow=resolve`

Some workflow transitions need additional parameters. For example, when resolving an issue a resolution is often required. Parameters can be provided by prefixing the parameter directive with workflow. (see resolution example below).

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`workflow.resolution`	`@workflow.resolution = fixed`	`#workflow.resolution=fixed`

If parameters are required but no value can be determined, the transition will fail.

Logging work on issues

Worklog additions can only be made to a pre-existing issue, to qualify, the issue key just needs to be in the Subject to be matched and processed.

For inbound emails that contain worklog directives, the email body is taken as the worklog comment. It will not be added to the issue.
If no wl.startDate directive is provided the date at which the email is processed will be used
To differentiate worklog directives from any other directives/fields, they are all prefixed with wl.
If there is a default set for worklog comment visibility, users can override with wl.viewable.role or wl.viewable.role directives. If a public worklog entry is wanted, the default can be overridden with wl.viewable=true.
Defaults are checked for in the following order, first non null value is used
- Role
- Group
Date format is the system default

Logging time spent

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Directive key	Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`wl.timeSpent`	`@wl.timeSpent = 1h 35m`	`#wl.timeSpent=1h 35m`

Logging time spent and updating remaining estimate

Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`@wl.timeSpent = 1h 35m @wl.startDate=4/10/09 @wl.newEstimate=2w 3d 4h 5m`	`#wl.timeSpent=1h35m #wl.startDate=4/10/09 #wl.newEstimate=2w3d4h5m`

Logging time spent and overriding visibility

Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`@wl.timeSpent = 1h 35m @wl.startDate=4/10/09 @wl.viewable=true`	`#wl.timeSpent=1h35m #wl.startDate=4/10/09 #wl.viewable=true`

Logging time spent, updating estimate and restricting visibility to a role

Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)

Example using At Prefix Field Processor (in email body)	Example using Subject Field Processor (in subject)
`@wl.timeSpent = 1h @wl.startDate=4/10/09 @wl.newEstimate=2w 3d @wl.viewable.role=Developers`	`#wl.timeSpent=1h #wl.startDate=4/10/09 #wl.newEstimate=2w3d #wl.viewable.role:Developers`

Special Processing

Event Type

As inbound mail can contain a variety of fields, content could trigger any of the stock event templates (e.g. issuecommented.vm). By default the issueupdated.vm template is used. By enabling the following option, the event type will be automatically selected as appropriate. The rule of thumb is that if a single type of information is provided (e.g. a comment, a worklog), that event would be used, combined input will result in a standard IssueUpdated event being used.

dynamicEventTypeSelection=true

Sender Email Address

The sender email address can be redirected into a nominated Custom Field:

assignJiraUsersOriginalEmailAddressToCustomField=Some Field

CC:

Users can be created through CC:

If the create user Options allow, each CC: will be auto-created as well, if they don't resolve to a known Jira user.

There are several Options for CC: handling, if enabled, can be:

ccHandling=toWatcher, which will trigger the identification of Jira users through given email addresses and add those with valid Jira accounts as watchers
ccHandling=toCustomField, which will trigger the identification of Jira users through the given email addresses and also add those users to a Custom Field, which is nominated through ccHandlingTargetCustomFieldName (which must be a CF of type MultiUserCF). Additionally, its possible to route non-Jira associated emails to a different simple text CF, with ccHandlingNonJiraUserTargetCustomFieldName.

These options are not mutually exclusive, e.g. ccHandling=toWatcher,toCustomField

Attachments

If any attachments are present in either initial creation or comments, they will be added to the issue.

IssueType

The issueType can be determined in several ways:

If the defaultIssueType Option is set, it will be used if no other issueType Directive is found
If the issueType Directive is set in an email (can be ID or Name) , e.g.:
- (in the body) @issueType = bug
- (in the body) issueType: task
- (in the subject) #issueType=risk

Field Processors

JEMH has several 'Field Processors' who's job it is to process inbound email and generate from it a map of key/value pairs.
The Configuration option emailFieldProcessorPackageList is mandatory and specifies a package within which are Field Processors. If this key is missing, the package is wrong, or for some reason the classes cannot be found, then JEMH will not do much.

There are many known keys for emails which are covered on the main add-on page. JEMH has been written with extension and customization in mind. The existing Configuration includes the following Options:

emailFieldProcessorPackageList - specifies a list of packages to search for FieldProcessor implementations, either extensions of the superclass AbstractFieldProcessorHelper or direct implementations of IMessageFieldProcessor.
emailFieldProcessorPriorityLowerLimit - each Field Processor has a 'priority' value, this is the lower inclusion limit (an integer)
emailFieldProcessorPriorityUpperLimit - as above, this is the upper inclusion limit (an integer)

Initial issue creation notifications for all

If the Option notifyUsersOnIssueCreation is set, (values are none,nonjira,jira,all), it is possible to trigger notifications of issue creation, separate to the Jira notification scheme. The purpose of this is to enable users who send email into Jira (when auto-creation is not on, or they don't qualify) to get some kind of notification that the issue got created. This currently only applies to the original email sender.

Customisation of from: address for JEMH sourced notifications

The following options, if either is specified, will override whatever Jira defaults have been setup on the default mail server:

customEmailFromAddress , eg: jemh@myco.net
customEmailFromName, eg: JEMH Mail Handler

Stripping Quotes

The Option stripQuotes enables inbound emails to be automatically stripped of indented content indicative of the reply-to-jira-mail scenario. This stops ever longer duplicate content additions.

Overriding stripQuotes

Sometimes you actually do want an email to be kept intact, say, forwarding in a Thread that didn't involve Jira. To override this behaviour, use the stripComments Directive (eg @stripComments=true)

Notify users without eating Jira license seats

A problem with the Jira license model is that sometimes you want to enable customers to send emails to Jira, to create tickets, those users don't need to be able to login to Jira but do need to receive related issue update notifications. JEMH can do this, if you set it up as follows:

Gutting the example configuration file does more than just remove fields you don’t care about (right now), it removes the related documentation. My advice is to keep the example, just comment out what you don't need.

Required configuration fields

Incomplete configuration options

The fields specified below are just in relation to this function, do not consider it complete and usable, it wont work, see the example and docs above.

Issue Creation

In order to create issues, that user must have 'Jira User' global privilege, normally this is given to jira-users. In order to create issues you must provide a userid that has such membership, and privileges in the project (perhaps identified through the defaultProject configuration option:

#set a default project (there are other ways, see config file for details)
defaultProject=someproject

#pick a default (fallback) user that will be used if the from: email acct does not correlate to a known Jira user
defaultReporterUsername=someuserid

This now enables issues to be created by anyone, but is not attributed to them directly.

Creating users without taking Jira seats

In order to support the notification of users, the approach is to create users without giving them 'Jira User' global privilege. Given that you must provide access to users without knowing their ID, you must also nominate a group, which is likely given 'User' privilege in your project (specifically, the Browse Project permission). The exact nature of the userId is configurable and is extendable, but is not required:

#trigger user creation
createUsers=true

#join a specific group with privilege to your project
autoJoinGroup=email-accounts

#dont notify users when they get an account created automatically (as they can't log in anyway)
notifyUsers=false

#get JEMH to send a manual issue created notification to non jira users (see docs for other options)
notifyUsersOnIssueCreation=nonjira

Overall function

When the issue has been created, the issue creator is set to the defaultReporterUsername, the remote email user that has been created, is added as a watcher, and will now receive subsequent notifications.

Blocklisting and Allowlisting

There are several reasons you may want to block certain emails, for example:

As Jira doesn't allow easy 'disablement' of users, it will happily continue to send emails to their account with status updates, filter output etc. If that user has left the company and has been disabled, your mailserver may reject Jiras mail, right back to the inbox of JEMH. You don't want that.
Even valid users email accounts can get hijacked and generate bot-spam

JEMH provides pretty comprehensive filtering behaviour to nail the annoying emails that you cant get filtered some other way:

Allowlisting

allowlistSenders - identifies regexps for email addresses that are valid and should be processed

Blocklisting

blocklistSenders - identifies regexps for email addresses that should not be processed
blocklistRecipients - for example, stop people emailing replies to noreply-dummo@jira.myco.net
silentlyDropBlocklistMatches - if you get a blocklist match, drop it? saves one delete click per email!

Greylisting

greylistSenders - identifies regexps for email addresses that, after allow/block listing, should be further checked
greylistSendersSubjectRegexps - identifies subject regexps (comma separated) allowing specific mail content to be added to be blocked from further processing
greylistRelatedUserBodyRegexp - an advanced feature, this will allow a body content to be regexp'd to extract the email address of a user that the email relates. The scenario here is your mailserver rejecting an email due to the user being disabled, receiving the bounce (from a allowlisted domain, but greylisted sender) that sometimes gives you useful information (ie doesn't warrant being on the blocklistRecipients list). The value is used to check that the user is disabled, and if so, its a greylist match.
silentlyDropGreylistMatches - if you get a greylist match, drop it? saves one delete click per email!

Customizing the Hint/Reject Emails

The Hints generated during processing are rendered through two sets of template files, HTML and plain text. If an inbound email from: address is found to relate to a Jira user, that users email format preferences are used, plain text otherwise.

Hint template files

The locations of the templates are in the JAR under /templates/email/jemh/html and /templates/email/jemh/text. To customize, just take copies and add to the WEB-INF/classes/templates tree.

Hint ID's

Some hints have numeric ID's associate with them to allow custom .vm level content provision over the perhaps verbose techno-babble message. These can be added on request.

Trouble Shooting

Email Errors

Fields on long lines are not found or truncated in Jira

This can happen when custom fields or description fields contain more than trivial information, e.g. > ~80 characters:

If you happen to use Outlook, go to _Options/Mail Format/Internet Format/Plain text options. Increase the wrap length to accommodate your maximum line length, the max is apparently 132 chars.
The linux 'mail' command line utility has been tested and does not suffer from this problem.

Problems with WYSIWYG Rendering of description field.

See JEMH-55. Workaround for now is use wiki-renderer.

Problems with email subject truncation using # character?

This is because the SubjectBasedFieldProcessor is trying to process those values. To stop that you can either change the emailFieldProcessorPriorityLowerLimit and emailFieldProcessorPriorityUpperLimit to select the range (only) of processors to employ according to the table below:

# MailFormNg format priority: 1000
# Subject priority: 2000
# AtPrefix format priority: 1100
# XML : 5000
# CSV format priority : 10000
# Nagios priority : 20000

If that isn't good enough (or if you just want to reduce 'noise' of handlers that aren't ever going to be used) it's also possible to open the Jar an remove the appropriate class with no side-effects.
Leave at least the basic handler there, or there will be a lot of rejects

package: com.javahollic.jira.emh.processor
AtPrefixedFieldProcessor
BasicMailProcessor
ConfluenceMailFormNgFieldProcessor
CSVFieldProcessor
NagiosFieldProcessor
SubjectBasedFieldProcessor
XMLFieldProcessor

Directives

What are Directives?

Field Processors

Security and global settings

Directives are flexible

Issue fields

Project

Reporter

Assignee

Issue Type

Priority

Components

Watchers

Due date

Due date format

Original Estimate

Affects Versions

Votes

Security level

Custom fields

Using Directives with different Custom Field Types

Issue association

Issue key

Sub-tasks

Issue links

Workflow transitions

Logging work on issues

Logging time spent

Logging time spent and updating remaining estimate

Logging time spent and overriding visibility

Logging time spent, updating estimate and restricting visibility to a role

Special Processing

Event Type

Sender Email Address

CC:

Users can be created through CC:

Attachments

IssueType

Field Processors

Initial issue creation notifications for all

Customisation of from: address for JEMH sourced notifications

Stripping Quotes

Overriding stripQuotes

Notify users without eating Jira license seats

Required configuration fields

Incomplete configuration options

Issue Creation

Creating users without taking Jira seats

Overall function

Blocklisting and Allowlisting

Customizing the Hint/Reject Emails

Hint template files

Hint ID's

Trouble Shooting

Email Errors

Fields on long lines are not found or truncated in Jira

Problems with WYSIWYG Rendering of description field.

Problems with email subject truncation using # character?

Related Articles