JEMH Mail Field Processors
Introduction
Field Processors do nothing more than extract necessary information from an email by any means, in order to populate a Map of specified Keys used to create an Issue. The abstraction hopefully minimises the effort required to support different flavours of email source, without requiring multiple mailboxes or handlers configured. The aim is Low Management Overhead!
JEMH Field Processors that require directives to be supplied in the email body, (such as the Mailform, and @Prefix Field Processor) also require that the directives be supplied at the top of the email body before any other email content. Any directives separated by a new line will not be extracted by the Field Processor, e.g:
Input | Output |
|---|---|
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
Subject: Subject of the email goes here
From: test@example.com
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8
priority: 5
assignee: username
This is the description/comment body of the email. It will not
be considered as a directive!
| Priority = 5 |
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
Subject: Subject of the email goes here
From: test@example.com
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8
assignee: username
priority: 5
This is the description/comment body of the email. It will not
be considered as a directive! | Assignee = "username" Priority = 5 |
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
Subject: Subject of the email goes here
From: test@example.com
To: changeme@thiswontwork.com
Content-Type: text/plain; charset=UTF-8
assignee: username
This is the description/comment body of the email. It will not
be considered as a directive!
priority: 5 | Assignee = "username" |
Enabling a Field Processor
To enable a Field Processor need to toggle the relevant field Processor from a grey toggle to a Green toggle.
Once enabled you will then be able to see the Field Processor within the Summary section of the Profile. Note: Some Field Processors do not have any configuration options. There will be no Edit (Pen icon) button when there is no options.
Once enabled you will then need to go to the Directives section and select a Directive Processing Behaviour. Current options are: On Create, On Comment or On Create or Comment. For more info about Directives see: Use Directives
Standard Field Processors
Colon Suffix (Mailform) Field Processor
The awesome MailFormNg Confluence add-on enables trivial or not so trivial forms to be created, complete with drop down selection etc. Once set-up, the selections are injected into the email body. This Mail Handler scans for these properties and modifies how issues get created.
There are several Example MailFormNg format inbound Emails.
Enabling Confluence mail integration
Confluence Compatibility
FormMailNG was known to work in 2.7, broke in 2.8 and 2.9, but apparently is working again in 2.10m3, so fingers crossed for a release.
Enable the Adaptavist Form Mail add-on through the marketplace.
Macro example
Using the MailMailNG macro, its possible to setup a simple (or not so simple) issue reporting form in Confluence:
Screenshot
Subject Field Processor
This processor allows the subject line to be used as the vehicle issue creation directives. Any and all options can be specified. The Issue Summary will be set to whatever is left on the subject line that is not directives, both in terms of prefix and post-fix. Information in the middle will be lost, in the example below, the summary would end up being This is prefix text This remaining text is also used.
Subject: | This is prefix text #project=jira #priority=trivial #watchers=user1,user2 This remaining text is also used |
|---|
Multiple values can of course be specified with comma delimiters.
Limitations
Specifying values with spaces is not yet supported, eg 'My Component' will come out as trying to match component 'My'.
Specifying the Summary / Description fields in the Subject line is unlikely to lead to any useful outcome, don't bother.
As only one line is available, who knows what limits an email client may pose on overall length.
Regexp Field Processor
This field processor uses regular expressions in order to map values to issue fields. It can also be used to associate emails with issues, when a particular field value is found. For more information on this field processor, see How Do I... Use Regexp Field Processor.
CSV Field Processor
You can use Excel or Open Office to populate a spreadsheet with issue creation information.
CSV Format
Line 1 of body | Must contain all required issue information, one entry per cell, e.g. 'project', 'priority' etc |
|---|---|
Line 2+ of body | Contains the values for each of the issue properties defines in line 1 |
Example
Use of Attachments
Use of a CSV attachment of the above format is supported. In order to 'activate' this feature, the first line of the email body must start with exactly: useAttachmentFilename=true
Using double quotes and commas in field values
Want to use double quotes in the field values? As the CSV field processor is expected these to be used to contain fields and values it gets a little tricky. The solution is to double up quotes that are inside values. For example:
Commas are seen, naturally, as value separators. If you wish to use them in a field such as the description, you can do so by using the ASCII code for a comma:
At (@) Prefix Field Processor
This field processor uses content in the format "@key=value". The key is prefixed with the "at" symbol (@) and the value is placed on the other side of the equals sign. Here is an example email where the @prefix field processor is being used to send an assignee directive. For a list of supported field types, please see this wiki page: Supported fields for use with Directives.
XML Format Field Processor
Issue attributes can be provided in an email with XML formatting if required. It uses XStream to read the data, hence its verbosity. Its parse priority is 5000.
Code to generate the XML
If you don't want to generate the XML code yourself you can make use of the JEMH Jar itself, you'll also need the XStream library to make use of this.
Example code for generating the correct format
Parsing of XML payload
Example email body content to send to JEMH
Default 'Basic' Mail Processor
This processor will attempt to create issues if no other configured handler can. It doesn't have the smarts that other handlers have and is a 'translated' version of the original Atlassian mail processor.
Script Field Processor
When JEMH Processes messages, the content (subject/body) can be subjected to Field Processors, which are specialised parsers. Other examples of Field Processors are the AtPrefix format, which parses out @key=value combinations from the email body lead in. These keys are Supported Fields for use with Directives, and allow Email content to drive issue updated during create and comment, even workflow transitions. The script field processor is the final piece in the puzzle for customisation processing of content, until now, new 'custom' processing could only be achieved with add-ons for JEMH, which are a technology hurdle too far for most. With the new Script Field Processor, basic knowledge of JavaScript and this how to guide will be enough to have you running in no time!
Due to the extensive nature of this Field Processor, there is a full article available about it here: Use Script Field Processor
X-JEMH Header
This field processor will check for headers that use X-JEMH at the begging of the header and will then set the related field with the header value. e.g. “X-JEMH-priority: critical”
Example email:
Specialist Field Processors
Nagios Field Processor
The Nagios Field Processor has been developed to enable JIRA to be a sink for automatic notifications, but not just sink them, to correlate and close them as required. This results in a condensing of notifications onto one JIRA issue, per related notification, with no need to manually go and close them if they resolve themselves/are resolved. For more information on the configuration of this field processor, see Use Nagios Field Processor.
This Field Processor uses JQL to find fuzzy matches, it then further refines this list to an exact Subject match, guaranteeing correct associations. See an example issues life-cycle with appending and closure...
Format
Nagios has templated subject lines as well as body content. This handler only interrogates the Subject, there are a variety of formats, for example, the standard Ubuntu distribution generates:
Format
Nagios has templated subject lines as well as body content. This handler only interrogates the Subject, there are a variety of formats, for example, the standard Ubuntu distribution generates:
Logic
The keywords (e.g. CRITICAL) are used to group related messages (i.e. expectation is that the rest of the information is the same), you can configure (currently limited to 10) related state groups. See the Nagios Configuration of the Usage Guide.
Third Party Field Processor Enablement
Enabled third party Field Processors
This is a list of Third Party Field Processors that have been added to JEMH/Jira. To select/deselect the relevant processor you will have to use Ctrl + Click.
Indicate active Field Processor/Profile
This will prefix the description/comment with text identifying the Field Processor that was used and from what Profile.