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 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:
to proceed to the edit screen:
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.
- 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:
|Value||If 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.|
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
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:
|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:
Using values from the incoming email
$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"))
Will render the emails message ID (if it has one):
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())
Will render the emails header:
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: simple create from a non jira user
From: "Nobody" <firstname.lastname@example.org>
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())
Will render the email sender's address:
Useful specific email related values
the raw message object
the Subject text
The Mailbox catchEmailAddress
the to: addressees
the cc: addressees
the bcc: addressees (don't expect many here!)
the post processed (html > markup) content – :warning: since JEMH 2.7.36 for Jira 7.10.x
Using values from LDAP queries
ldap = $ldap.getClass().getName()
#set ($ldapUser = $ldap.getUserDetails($username))
user record for: andy, email= $ldapUser.getEmail()
no user found for: $username
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).
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
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:
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:
#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:
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.
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.