Use Script Field Processor

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.

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.

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.

Installing Graal into a JDK8 Java Runtime

Download from https://www.graalvm.org/downloads/ (eg the GraalVM Community 20.1.0 version), the archive that is appropriate for your OS, eg (Java8) graalvm-ce-java8-linux-amd64-20.1.0.tar.gz

Unzip the archive and enter the folder created (graalvm-ce-java8-20.1.0), assuming $JAVA_HOME points to your JDK installation:

1 2 3 4 5 6 export DEST=$JAVA_HOME/lib/ext cp ./jre/languages/js/graaljs.jar $DEST cp ./jre/languages/js/icu4j.jar $DEST cp ./jre/lib/truffle/truffle-api.jar $DEST cp ./jre/lib/boot/graal-sdk.jar $DEST cp ./jre/lib/boot/graaljs-scriptengine.jar $DEST

Directory $JAVA_HOME/jre/lib/ext should then look like:

Installing Graal into a JDK11 Java Runtime

Not yet supported.

Picking Graal ScriptEngine

This should now be a simple select (the Graal.js prefix in the select (to make the Engine source more clear) 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 usually require Directive Processing to be enabled on the Profile.  Go to the Profile > Directives section and set the 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

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

 

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:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 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:

1 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, where (1) shows the extracted fields and (2) shows the debug log from the script execution.

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.