Use Script Field Processor

1 Introduction
- 1.1 Supported scripting languages
  - 1.1.1 Groovy
  - 1.1.2 Graal
  - 1.1.3 Selecting a Scripting language
2 Enabling the Script Field Processor
- 2.1 Enable Directives
3 Editing the Script
- 3.1 Key to image above
4 Example
- 4.1 Email Test Case
- 4.2 Example Script
5 Forcing the Script Field Processor to be active always
6 Auditing
7 Stopping excess logging about Nashorn deprecation
8 Useful references
9 How we support this
- 9.1 Future Features
10 Related articles

Introduction

since 2.5.2 (Minimum Jira 7.7.x)

When JEMH Processes messages, the content (subject/body) can be subjected to Field Processors, which are specialized 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 customization 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!

Supported scripting languages

In theory, any language with a JSR-223 compliant engine can be used. ECMAScript (JavaScript) is supported by default through the Nashorn script engine at present, but this has been deprecated for final removal in JDK 14. To install additional Scripting languages see: Install a Scripting runtime Engine (Nashorn, Groovy, Graal)

Groovy

Apache Groovy – Typical installation involves dropping the embeddable Groovy .jar file into JIRA_INSTALL/lib. If ScriptRunner is installed, the Groovy engine from that will be used.

For a guide on installing Groovy see: Install a Scripting runtime Engine (Nashorn, Groovy, Graal) | Groovy

Graal

since 3.3.18 (Minimum Jira 8.0.x)

GraalVM is a full virtual machine in its own right, a component of which is the Graal Script Engine, which can be dropped into existing Java Virtual Machine installations to enable it to be used in place of Nashorn. By not bundling the script runtime we (a) reduce memory footprint of our app, by deploying Graal ScriptEngine into Jira or your Java Runtime, it is then available for other apps to use, (b) we do this to not exclude other 3rd party apps from making use of the script engine as incompatibilities will arise if apps include script engines.

For a guide on installing Graal see: Install a Scripting runtime Engine (Nashorn, Groovy, Graal) | Graal

Selecting a Scripting language

This should now be a simple select (each scripting language is prefixed with it relevant name (to make the Engine source more clear e.g. Graal.js) comes in with JEMH 3.3.13 (Jira 8.0+)

Enabling the Script Field Processor

Edit your JEMH Profile, and then edit the Field Processors section:
Check the box for the Script Field processor and submit:
Once the Script Field Processor has been enabled, it will be shown toward the bottom of the main profile screen. It can be expanded to preview its configuration. To start with, it show an example configuration:

Enable Directives

Field Processors require Directive Processing to be enabled on the Profile. Go to the Profile > Directives section and set the Directive Processing Behaviour to be something other than disabled. You can expand the Directives section by clicking on the left hand side arrow, shown below:

This setting is primarily required for other Field Processor types where users can supply content than can update issues. If you have other field Processors active, it will already be on, if after enabling the Script Field Processor you enable other Field Processors, be aware that this can be a security risk in some situations.

Editing the Script

Once enabled, the way to get to the Script Field Processor editor is at the bottom of the Profile > Summary screen.

Using the pen icon on the Script Field Processor section you will get to the Script Field Processor editor screen:

Custom Field Keys vs Custom Field Names

JEMH Script rules and Script Field processors accept both custom field’s Name, and Keys in the resultMap, however we would recommend using the custom field Key where possible as the Key is Unique, whereas multiple custom fields can share the same name. Additionally, JEMH uses Custom Field Keys/Ids internally to track Custom Fields to prevent fields being overwritten (except for in Script Rules). If a Custom field name is used, a pre-existing field could be overwritten. For example, a custom field set via name in the Script Field Processor could be unintentionally overwritten by a Custom Field Default.

Key to image above

	Section	Description

	Section	Description
1	Language selection	The Language picker defaults to the ECMAScript implementation which is bundled with the Oracle JRE. It is possible to add more scripting engines such as Groovy, by adding its embeddable distribution JAR to the Tomcat or Jira class path, e.g. JIRA_INSTALL/lib.
2	Description	A description will help you and others remember what the purpose of this script is. Its also possible of course to add code comments within the script, shown later.
3	Context	This shows the variables you have access to within the script, for example, if your script contained print('subject is : '+subject); then, the email subject would be added to the console. The resultMap reference has a special use. Its purpose is to hold the field values that you wish to be set. Keys in the map should match Supported fields for use with Directives. Values should be appropriate and formatted as needed (usually text values are fine).
4	Script Editor	The editor enables manipulation of the script content.
5	Test Case selection	Allows selection of a Test Case to be used during in order to provide email-specific context data, such as subject.
6	Test run button	This button is used to execute the script with the selected test case email.
7	Test results	Once the test is completed, test results will be displayed. This will show mapped values for use in issue creation/update, and any debug log output:

Example

Email Test Case

Here is a test case email with some text grabbed from a website today:

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>
Subject: This is a starting email template, update as required
From: "Andy Brook" <andy@localhost>
To: changeme@thiswontwork.com, to1@to1.com, to2@to2.com
Cc: blah@blah.com, blah2@blah2.com
Bcc: bcc1@blah.com, bcc2@blah2.com
Content-Type: text/plain; charset=UTF-8

London, Frankfurt and Paris all fell sharply at the open with losses of up to 3%, before recovering some ground. In the US overnight the Dow lost 4.6%.

Japan's Nikkei 225 closed down 4.7%.

The sell-off began last week after data in the US showed stronger wage growth, which raised expectations that US interest rates might start to rise more quickly to tackle inflation.

London's FTSE 100 was down 150 points or 2% at 7,184.74 in mid morning trade. Frankfurt's Dax and Paris's CAC were down 2.2% and 2% respectively.

On Monday the FTSE 100 closed at its lowest level since April of last year.

The falls follow some good years for investors.

In 2017 the Dow in the US was up 25% and London's FTSE 100 rose 7.6%.

Example Script

The following is the default ECMAScript generated when enabling the Script Field Processor, with some changes at the end to show how email content can be parsed, and values stored in the map. Here we're adding a label to the issue "sell-off" because the word "sell-off" appeared in the body content.

print('hello world, below you can see some of the variables available in the rule context');

print('message is '+message);

print('subject is '+subject);

print('fromAddress is '+fromAddress.getAddress());
for (i =0 ; i< allAddresses.length ; i++)
{
  print('allRecipient #'+i+' = '+allAddresses[i].getAddress());
}

if (toAddresses) {
    for (i =0 ; i< toAddresses.length ; i++) {
      print('toRecipient #'+i+' = '+toAddresses[i].getAddress());
    }
}
if (ccAddresses) {
    for (i =0 ; i< ccAddresses.length ; i++) {
      print('ccRecipient #'+i+' = '+ccAddresses[i].getAddress());
    }
}
if (bccAddresses) {
for (i =0 ; i< bccAddresses.length ; i++) {
      print('bccRecipient #'+i+' = '+bccAddresses[i].getAddress());
    }
}

if (body.toLowerCase().indexOf('sell-off')!=-1)
{
    resultMap.put("labels", "sell-off");
}

print('goodbye world!');

Forcing the Script Field Processor to be active always

When an email is processed, the enabled field processors within the related Profile all take part in an election process to determine which set of output should be used. Its possible that you may want the Script processor to be active for a given message, this can be forced with the following:

resultMap.put("FORCE_JEMH_SCRIPTFP", true);

Auditing

If you have auditing enabled (shown below), you'll find a transcript of the Script Field Processor output, along with the detail of what fields (key value pairs) were extracted by it, the way to get at the detail is through the highlighted icon bottom right, accessed by hovering on the auditing row.

An example of the detail generated by the Script Field Processor is shown below which shows the debug log from the script execution.

Stopping excess logging about Nashorn deprecation

The Nashorn javascript engine is bundled with JDK8 though JDK11 but was removed in JDK15, so will not be available in JDK17 (an open source nashorn library can be used, as well as an alternate Graal engine, for more info see: Install a Scripting runtime Engine (Nashorn, Groovy, Graal) ). Jira logs may report this deprecation many times, to disable this deprecation notice, add the following as a JVM ARG (https://confluence.atlassian.com/adminjiraserver/setting-properties-and-options-on-startup-938847831.html ).

Useful references

Methods available to operate on the body content which is a Java type String, see Oracle JRE String class documentation for available methods (e.g. body.toLowerCase() , body.indexOf("bla") etc).
Mozilla JavaScript landing page and JavaScript reference
JavaScript language (spec)

How we support this

We have provided a script capability for Field Processors, and also for Project Mapping Rules. There is no end to the variability of how these features can be used, and for your requirements. To prevent our support system from getting completely jammed, we cannot provide implementation or debugging support for your scripts. If the scripting side of this is too complex, then you should approach a trusted Atlassian Partner who can support your efforts.

Future Features

Its quite likely that in order to maximize your ability to solve a particular problem, that it would be very useful for X to be available in the context, or utility feature Y to be made available. Feel free to ask through our SUPPORT mailbox (support@thepluginpeople.com), no guarantees - we want to keep the Field Processors and the context as streamlined as possible.