JEMH Mail Field Processors
- Former user (Deleted)
- Noah Griffiths
- Phil Evans
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 Colon Suffix (Mailform) Field Processor enables JEMH to map values to Jira Fields with the notation “key:value”, where “key” is the name/id of the Field and “value” is the data that will populate the field. The Colon Suffix Field Processor can be used to set Fields during issue creation and update Fields on comment. Like the @Prefix Field Processor, the Colon Suffix Field Processor is defined at the top of the email body, and is capable of multiline directives. Multi-line directives should only be included as the first of at-least 2 directives, otherwise JEMH will not know where the directive ends and the email begins.
Edge case: Colon Suffix Processor false Directive hits
The Colon Suffix Processor can falsely identify lines of text as a Directive if a colon is used within the first line of the email body, which will remove the falsely identified directive from the description/comment in the issue.
In the below example, “all of our servers went down at 8:30” is removed from the description:
Stop the removal of text that has a colon
In Profile > Configure > Email > Pre-processing, enabling the checkbox “Pre-validate Custom Field values”, will prevent the removal of the text “all of our servers went down at 8:30”.
Subject Field Processor
This processor allows the subject line to be used as the vehicle for Issue creation Directives, i.e., using Subject Directives in emails that comment on existing issues will not work. Subject Field Processors follow the format “#key=value”, where “key” is a Field and “value” is the data to set to the Field. 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.
Simple example
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.
Subject Field Processor is space delimited
Out of the box, the Subject Field Processor ends when white-space is found. If there is white-space in the key or the value, the Subject Field Processor won’t work as expected, for instance the following will fail to find the epic link and will only populate the Field ‘CustomTextField’ with the value 'A':
With some configuration changes, Subject Field Processors can contain white-space. For examples of Subject Field Processors containing white-space, see: Using Directives with spaces in the key, Using Directives with with spaces in the value: Double quotation marks and Using Directives with spaces in the value: square brackets.
Using Directives with spaces in the key
Specific to the Subject Field Processor, keys with spaces e.g. “Epic Link” wont work, this can be solved using an Alias without spaces in place:
Set up an Alias where the Alias is a Custom Field without a space and the value is a Custom Field.
Alias:
Value:
In the email, add the Subject Directive In the code-block below, the Alias “epiclink” that was created is used as the key instead of “epic link”.
Using Directives with spaces in the value: Double quotation marks
By default, a space character marks the end of a value or, in other words, only values of Subject Field Processors that do not contain spaces will work. For example, ‘#AKey=some value’ will populate the custom field ‘AKey’ with ‘some’. To process values that have spaces, enclose the value in double quotation marks. Note, apostrophes won’t work, only double quotation marks work:
Create an email with a Subject Directive and enclose the value in double quotation marks.
Some Fields only accept specific formats, for instance, the Labels field does not allow space characters therefore quotation marks won’t affect the final value of the Field.
Using Directives with spaces in the value: square brackets
Enclosing a directive with square brackets, for example “[#key=value]”, will prevent white-space delimiting a value of a Text Field.
Example
Create an email with a Subject Directive and enclose the entire Subject Directive with square brackets.
Limitations
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.