Velocity Script Custom Field Defaults

Owned by Ryan Clifton
Last updated: Jun 13, 2023
5 min read

Summary

Similar to custom notification templates, Velocity can be used in JEMH's custom field defaults in order to provide dynamic values.  While in the custom field default edit screen, select Velocity Scripted Value for the Field Value Type.

Velocity Scripted Value configuration (4.1.13 and older)

When you change to Velocity Scripted Value it will show some additional elements that are used to assist with the creation of the Script.

1

Preview Button

Press this in order to render the velocity script that you have in the preview window

2

Velocity Context Help

Select this to get some additional information on the classes that are exposed for use

3

Preview Window

Once the preview button has been clicked, the script will be evaluated and the resulting output will be rendered here

Example Velocity context:

Velocity Scripted Value configuration since 4.1.14

Within 4.1.14 there has been some changes with the elements that are shown when you select Velocity Scripted Value. These new elements allow you to select a Test Case to evaluate the Script against, allowing for more accurate testing.

1

Show Script Context 

Select this to get some additional information on the classes that are exposed for use

2

Test Case

This is where you select the Test Case that should be used to test the Script

3

Evaluate

Runs the script against the selected Test Case

4

Custom Field Value

Shows the Custom Field value that will be added.

Example Velocity context:

Using values from the incoming email

Gathering a Specific Header

Referring to $message will allow you to retrieve information using the methods available for Message (Java Mail API) objects.  For example, lets say we want to get the value from an email's "References" header:

#foreach ($id in $message.getHeader("References")) $id #end

Will render the emails References (if it has one):

<BANLkTinB1mfSh+GwOXGNgdL4SyDvOpdBoQ@mail.gmail.com> <BANLkTinB1mfSh+GwOteGNWoL4SyDvOpdBoQ@mail.gmail.com>

Gather All Headers

Additionally, you may wish to store headers within a custom field, this can be achieved using the simple Velocity script below:

#foreach ($header in $message.getAllHeaderLines()) $header #end

Will render all of the emails header:

Useful specific email related values

context variable

Data Type

Description

context variable

Data Type

Description

message

javax.mail.Message

the raw message object

subject

java.lang.String

the Subject text

$jemhUtils.getCatchEmailAddress().getAddress()

java.lang.String

The Mailbox catchEmailAddress

fromAddress

javax.mail.InternetAddress[]

the from: address

toAddresses

javax.mail.InternetAddress[]

the to: addressees

ccAddresses

javax.mail.InternetAddress[]

the cc: addressees

bccAddresses

javax.mail.InternetAddress[]

the bcc: addressees (don't expect many here!)

allAddresses

javax.mail.InternetAddress[]

all addressees

body

java.lang.String

the post processed (html > markup) content – :warning: since JEMH 2.7.36 for Jira 7.10.x

Using values from LDAP queries

Since 3.1.6 we have added LDAP querying capabilities to the $jemhUtils support class, available in Script Field Processor (javascript) and Custom Field Default (velocity, shown below) contexts. See Using LDAP in Script Field Processor for available LDAP methods and definitions for LDAPUser.

Example edit time preview

We fixed the preview so dynamic queries like LDAP will render (ok for testing, not so much for email derived values).

Using values from the related JIRA issue

If the email is determined to be commenting on an existing issue, you can retrieve information from it by referring to $issue and using methods available for TemplateIssue (JIRA API) objects.  For example, we could get the issue priority:

Using values from a JSON Object retrieved via JIRA REST API

The invokeLocalRest method added to $jemhUtils enables the velocity script to send GET requests to the JIRA REST API.  The method returns a JSONObject, which if the REST call was successful will contain data that the script can manipulate to extract the value required.  In this example we will try to retrieve issue data via the REST API for a hard-coded issue and get the ID of the issue.

The previously linked REST API documentation shows us what we can expect the response data to look like.  Here is an excerpt of the JSON data that our example JIRA would return for issue SOF-1:

Note that the above is a very simple example of what is possible - it checks that the REST call was successful and renders the ID value.

Authentication

If the sender of an email is found to be a JIRA user, they will be the used for authenticating the REST call.  If the sender does not have a JIRA user account, the Profile's Default Reporter is used instead.  If no default reporter is set and the sender is not a JIRA user, then the REST call will not succeed.

Additional Examples

See the following pages for some additional Velocity examples: