Set custom fields using Custom Field Defaults


This page refers to the current custom field default system introduced in version 2.0.11, which is found inside Project Mappings.  Using 2.0.10 or older? See documentation for the old system.

Overview

Custom field defaults allow static or dynamic values to be defined for custom fields in an issue.  These values can be configured to be applied to an issue during issue creation and/or comment.  Field values are inherited, meaning for example that a value for a field set at the project mapping level will be inherited by all of that mappings rules, unless overridden at the rule level.

Creating and Editing Custom Field Defaults

From the main profile configuration screen, click edit  on the Project section, and then proceed to edit  an existing project mapping.  Custom Field Defaults can be set at the Project Mapping level, or the Project Mapping Rule level.  Where a default is created can make a difference as to how it is used, as you will see when inheritance is discussed further below.  The process of creating a default is the same regardless of which level you are at:

Find the Custom Field Default section on the Project Mapping page.  Click New Custom Field Default:


After doing so, a new default will be created and will be visible in the list, but will not have a field or value defined:


Click edit  to proceed to the edit screen:

SettingDescription
Custom Field

The custom field that the value will be used for.  If there is a project defined in the associated project mapping, then only fields applicable for the projects issue types will be shown. 

Please note:

    • Select custom field - Project Context values are provided as the primary values and Default/Global Context values are provided as secondary values - Change is applied from - JEMH version3.1.6 2.7.50 2.6.24 2.5.21 2.4.22
Field Value Type

The type of value that is going to be defined.  Options are:

ValueIf the selected field value type is Simple Text Value, then the static value(s) will be entered here.  If the value type is Velocity Scripted Value, then the VTL script will be entered here.
Apply Rule

Allows selection of when this custom field default should be applied.  Options are:

  • Create Only
  • Comment Only
  • Create and Comment

Once the parameters of the custom field default have been defined as desired, click submit to save changes.  The newly configured default will be present in the list on the mapping:

Using a dynamic velocity scripted value

For more information on using Velocity see the User Guide here: http://velocity.apache.org/engine/devel/user-guide.html


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.  Three new page elements should be displayed:

1Preview ButtonPress this in order to render the velocity script that you have in the preview window
2Velocity Context HelpSelect this to get some additional information on the classes that are exposed for use
3Preview WindowOnce the preview button has been clicked, the script will be evaluated and the resulting output will be rendered here

Example Velocity context:

Using values from the incoming email

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 "Message-ID" header:

#foreach ($id in $message.getHeader("Message-ID"))
$id
#end

Will render the emails message ID (if it has one):

<fdf5D44TGFExf5+GwOXGJD0SyDvOd4Ci9@mail.example.com>

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 the emails header:

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: simple create from a non jira user
From: "Nobody" <nobody@faraway.com>
To: jira@myco.net
Content-Type: text/plain; charset=UTF-8

$message can also be used to access the From: address of the incoming email:

#foreach ($address in $message.getFrom())
$address.getAddress()
#end

Will render the email sender's address:

nobody@faraway.com

Useful specific email related values

SINCE 2.4.21

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

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 Markup

#set ($ldap=$jemhUtils.getLdap())
ldap = $ldap.getClass().getName()
#set ($username="andy")
#set ($ldapUser = $ldap.getUserDetails($username))
#if ($!ldapUser)
    user record for: andy, email= $ldapUser.getEmail()
#else
    no user found for: $username
#end

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:

$issue.getPriority().getName()

Using values from a JSON Object retrieved via JIRA REST API

New in 2.1.18

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:

{
	"expand": "renderedFields,names,schema,operations,editmeta,changelog,versionedRepresentations",
	"id": "10200",
	"self": "http://localhost:8080/rest/api/2/issue/10200",
	"key": "SOF-1",
	"fields": {
		"fixVersions": [],
		"resolution": null,
		"customfield_10104": null,
		"lastViewed": "2017-06-27T13:15:18.878+0100",
		"priority": {
			"self": "http://localhost:8080/rest/api/2/priority/3",
			"iconUrl": "http://localhost:8080/images/icons/priorities/medium.svg",
			"name": "Medium",
			"id": "3"
		},
		"customfield_10101": [],

Configuration

Go to the Project Mapping where you want the custom field value to apply.  Create a new custom field default (as explained earlier on this page) and edit it.  Change the Field Value Type to Velocity Scripted Value and enter your Velocity script.  Here is an example script:

Example Velocity script
#set ( $jsonObj = $jemhUtils.invokeLocalRest("/rest/api/2/issue/SOF-1") ) ##returns JSON object with data/error or null if email sender is not a JIRA user
#if ( $jsonObj && !$jsonObj.has("jemhError") ) ##if REST call was authenticated and no errors occurred
$jsonObj.getString("id") ##in this examnple we simply get the underlying issue id of issue defined in REST call URL
#end ##close if block

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.

Upon selecting Submit the configuration will be saved.  If a value is able to be rendered without a $issue object being available, you may see the results rendered in the Custom Field Defaults list:

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.

Run-time result

The custom field will be set with the value extracted, and will render its view of that data in whatever way that field does.  Non standard custom fields may have problems, e.g. Valiantys nFeed.

Inheritance of Custom Field Defaults

Custom field defaults are inherited in the project mapping hierarchy.  Defaults created on a default project mapping are inherited by other non-default project mappings.  Defaults created on a standard project mapping are inherited by that project mapping's children (mapping rules).  To override an inherited default, simply add a new default for that custom field at the current mapping level.

If a custom field default is set to apply only on comment, a default for the same custom field on the parent mapping level on create will still be inherited. The same behaviour applies in the opposite scenario.


Related Articles