Scenario

As an email user you want to update an issue without logging in, it could be to advance workflow, set a custom field or re-prioritise or assign an issue.  You may also want to consume an email from a remote system and populate a Jira issue with that.

Directives

JEMH supports the concept of a Directive, which is a user supplied key + value, where the key is a supported Field for use with a Directive, and the value is appropriate for that field.  

Enabling directives

These Directives must be specifically enabled (e.g. Profile > Directives > Directive Processing Behaviour : Create/Comment).  

Open

Translating directives

Where keys and values do not match Jira custom fields or appropriate values, JEMH Aliases allow a) complete key+value conversion into different key+values, b) key replacement, c) value replacement, this feature allows translation of external values into 'internal' values suitable for use.

Directive formats

Directives are processed by JEMH through Field Processors that understand specific email payload content.  There are several internal Field Processors bundled with JEMH, they all use a public API extension point, so third party Field Processors can also be written if the mood takes!  Formats are set, and not variable, if you vary from the exact format presented, expect Directives to be missing.

Directive security

Directives require no specific Jira permission, but the user under which an activity is performed needs have appropriate permissions. For example, adding email CC header participants as watchers of that issue will require “Manage watchers” permission.

It is possible to limit what users can do with Directives by setting a whitelist, perhaps just with 'priority' or even specific Alias keys that have been defined.  Directives can be limited by Allowlist or Blocklist, using both is a little nonsensical, but will mean within the set of Allowlisted directives. Those that are Blocklisted are then discounted.  

Open

Directive Groups

Directive Groups are used to define the User groups that the sender must be part of. If they do not have one of the groups defined then the matched directives will not be processed.

Parsing and outcome for content

JEMH Field Processors normally remove fields considered as matching their respective format.  For body content, usually an empty line separates the lead-in block of Directives from the content that remains, which would be used for the 'description' (during create) or the 'comment' (during commenting!).

Date/Date Time

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.

Prior to 2.5.1, date values should be sent using the system default locale.

HTML and TEXT email content

For Directives supplied by email content, the way an email is sent can cause complete failure to process directives, using text/plain content type with no special formatting is best for Directive processing.  If you really must use HTML, further steps are likely to be needed.

If JEMH is configured to prefer HTML (Profile > Email > Pre-Processing > Body Format Preference : HTML / any), or perhaps HTML is the only content provided, then, in order to get usable TEXT, a conversion takes place.  JEMH has lots of specific white-space configuration to make HTML Directives possible at all, they need tailoring for whatever format a particular mail client has decided to use.  

Unfortunately, HTML settings are global to a JEMH Profile, so, they will apply to any user sending HTML, this can have interesting outcomes, and is one possible reason for having more than one Profile.

 Problems with HTML email are to be expected. If you don't like manipulating low level HTML Tag newline conversion, don't send emails in HTML with Directives, or use the limited Subject Based Field Processor which does not have this problem.

Multi-line values

JEMH can support fields with multi-line values but there are problems, as email is unstructured, lines starting with what is 'potentially' a match for a directive can cause false positives.  The Colon Suffix Field Processor format is more problematic than most, e.g. "I saw this problem at 8:30 pm" will, in the the Colon Suffix Field Processor be converted to a key of "I saw this problem at 8" and value of "30 pm".   Profile > Email > Pre-processing > Pre-validate Custom Field values : ON can be used to reduce false positives and only add such fields if they really match an existing Custom Field or known Directive, its not enabled by default as it adds to overhead.

Multi-line values must be 'in the block' of directives, so that the Field Processor can locate the 'last' Directive that delimits the multi-line content.

Description or comment

When creating, the email payload wants to be set as the description, during commenting, to be set as the comment.  With Directives this gets more complex, as during creation, @description will match to the description, but during comment @description will also map to the description, and during create @comment will map to a non-existent comment, but during comment will map to the comment!  So?  JEMH will accept comment as a valid directive during both create and comment, and will do the right thing with that content.

Validating HTML to text conversion

Always use a JEMH Test Case to validate Directives have the desired effect, the Field Processor that 'owned' the processing will be identified (e.g. Basic Field Processor means no special field processor was selected) in the post execution results (the same results that real emails generate in the Auditing section of JEMH, accessed via the detail drill down operation).

To validate that HTML conversion settings are working as expected, the target type Field Processor should be disabled, this causes the Basic Field Processor to run, and any formatting issues will become evident, e.g. you will see many rows on one line, breaking the format, or lots of white space - also breaking the format.  

Where to set white-space?

HTML Tag Newline Injection is located in the Profile Email settings:

Examples

Here is an example of the AtFormat showing common sources of this problem.

Exporting from Audit History

In order to 'see' the HTML, it will be necessary to open the JEMH Audit History export of a given email:

Converting Audit History to a Test Case

Audit History can auto create a JEMH Test Case, associated with the right profile.  Test Cases allow you to quickly re-run the same email, immediately, to validate expected outcome.

Decoding email content

Email content is sometimes encoded as base64 (a big block of text):

There is a base64 decode editor action that is found within the Test Case editor, highlight the content and press Base64 Decode Selection:

Raising a support case

The tools are available to help you solve these problems yourself (faster). If you cannot do so, raise a support case, including:

1. Your Profile XML (there is an export operation on the Profile list page for each profile)

2. The email content from the JEMH Audit History or Test Case, attached as a file NOT PASTED!

Related articles