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:

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

Enabling a Field Processor

To enable a Field Processor need to toggle the relevant field Processor from a grey toggle to a Green toggle.

Image Added

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.

Image Added

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

Image Added

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

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:

h3. Comprehensive per-project Mail Form
This form shows how Form Mail NG can be used to provide a per-project specific mail form.  If project specific keys like Components are not required, the Project can also be added as a selectable entry.

{mail-form:destination=conf@jira.myco.net}
{mail-input:type=hidden|name=reporter|vtlValue=$!user.name}
{mail-input:type=hidden|name=from|vtlValue=$!user.email}
{mail-input:type=hidden|name=dueDateFormat|value="dd-MMM-yyyy"}
|| Category of request:| {mail-select:name=components}
  {mail-option:selected=true}General Help{mail-option}
  {mail-option}Authentication / Authorization{mail-option}
  {mail-option}Client Integration{mail-option}
  {mail-option}New Features{mail-option}
  {mail-option}New Space Requests{mail-option}
  {mail-option}Server{mail-option}
  {mail-option}Standards{mail-option}
{mail-select}|
|| Subject | {mail-input:type=text|name=subject|cssStyle=width: 500px;|required=true}|
|| Description | {mail-textarea:name=description|cssStyle=width: 500px; height: 100px|required=true}{mail-textarea} |
|| Priority| {mail-select:name=priority}
  {mail-option:selected=true}Trivial{mail-option}
  {mail-option}Minor{mail-option}
  {mail-option}Major{mail-option}
  {mail-option}Critical{mail-option}
  {mail-option}Blocker{mail-option}
  {mail-option}Emergency{mail-option}
{mail-select}|
|| Issue Type |{mail-select:name=issueType}
{mail-option:selected=true}Bug{mail-option}
{mail-option}New Feature{mail-option}
{mail-option}Task{mail-option}
{mail-option}Improvement{mail-option}
{mail-option}Risk{mail-option}
{mail-option}Documentation{mail-option}
{mail-option}Requirement{mail-option}
{mail-option}Change{mail-option}
{mail-select}|
|| Due Date (dd-MMM-yyyy) | {mail-input:type=text|name=dueDate} |
|| Labels (label,label) | {mail-input:type=text|name=labels} |
|| Watchers (user1,user2) | {mail-input:type=text|name=watchers} |
|| Affects Version (1.1,2.2) | {mail-select:name=issueType}
{mail-option:selected=true}Unknown{mail-option}
{mail-option}1.1{mail-option}{mail-select} |
|| Linkto (eg ABC-10/duplicate) | {mail-input:type=text|name=linkto} |
|| Category of request:| {mail-select:name=assignee}
  {mail-option:value=axb|selected=true}UK Support{mail-option}
  {mail-option:value=sjo}US Support{mail-option}
{mail-select}|
{mail-submit}
{mail-success:render=wiki}
{tip:title=Support Request Submitted}
Thank's for your query, please expect a response within 24hours.{tip}
{mail-success}
{mail-form}

Screenshot

Image Added

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.

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

Example

"This is the value for an issue ""description"". This is the second sentence of the description."

,

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.

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!

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

private void doit()
{
JemhXmlPayload payload=new JemhXmlPayload();
List<Entry> entries=payload.getJemhPayload();
createSimpleEntry(entries, "priority", "high");
createSimpleEntry(entries, "reporter", "userX");
createSimpleEntry(entries, "assignee", "admin");
createSimpleEntry(entries, "watchers", "user1","user2","user3");
createSimpleEntry(entries, "description", "this is the body of the email");
createSimpleEntry(entries, "summary", "this is the summary of the email");
		
XStream xs=new XStream();
xs.alias("JemhXmlData",JemhXmlPayload.class);		
xs.alias("Entry", Entry.class);
String xml=xs.toXML(payload);
System.out.println("XML:\n"+xml);
}

private void createSimpleEntry(List<Entry> entries, String key, String... value )
{
List<String> values=new ArrayList<String>();
for (int i = 0; i < value.length; i++)
  {
	values.add(value[i]);
  }
entries.add(new Entry(key,values));
}

Parsing of XML payload

Example email body content to send to JEMH

<JemhXmlData>
  <Entries>
    <Entry>
      <Key>priority</Key>
      <Values>
        <string>high</string>
      </Values>
    </Entry>
    <Entry>
      <Key>reporter</Key>
      <Values>
        <string>userX</string>
      </Values>
    </Entry>
    <Entry>
      <Key>assignee</Key>
      <Values>
        <string>admin</string>
      </Values>
    </Entry>
    <Entry>
      <Key>watchers</Key>
      <Values>
        <string>user1</string>
        <string>user2</string>
        <string>user3</string>
      </Values>
    </Entry>
    <Entry>
      <Key>description</Key>
      <Values>
        <string>this is the body of the email</string>
      </Values>
    </Entry>
    <Entry>
      <Key>summary</Key>
      <Values>
        <string>this is the summary of the email</string>
      </Values>
    </Entry>
  </Entries>
</JemhXmlData>

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:

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>
X-JEMH-priority: low
X-JEMH-project: Service Project
X-JEMH-assignee: admin
X-JEMH-issueType: bug
Subject: This is a starting email template, update as required
From: admin@localhost
To: mailbox@localhost
Content-Type: text/plain; charset=UTF-8

This is the email body

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:

From nagios@trippy  Fri Jan 29 11:50:54 2010
Return-Path: <nagios@trippy>
X-Original-To: nagios@jira.myco.net
Delivered-To: nagios@jira.myco.net
Received: by trippy (Postfix, from userid 117)
	id BFAE31E8C; Fri, 29 Jan 2010 11:50:54 +0000 (GMT)
To: nagios@jira.myco.net
Subject: ** PROBLEM Service Alert: localhost/SSH is CRITICAL **
Message-Id: <20100129115054.BFAE31E8C@trippy>
Date: Fri, 29 Jan 2010 11:50:54 +0000 (GMT)
From: nagios@trippy

***** Nagios *****

Notification Type: PROBLEM

Service: SSH
Host: localhost
Address: 127.0.0.1
State: CRITICAL

Date/Time: Fri Jan 29 11:50:54 GMT 2010

Additional Info:

Connection refused

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.

Related Articles