Jira Misc Custom Fields (version 1.x)

JMCF 1.x only!

This documentation applies only to JMCF version 1.x. Documentation for versions 2.0.0 and above can be found here.

Overview

The JIRA Misc Custom Fields plugin's objective is to provide several new types of custom fields for use in custom JIRA workflows as well as useful JQL functions.

Included custom fields:

Calculated Number Field : a calculated custom field returning a number (integer or float). It is a read-only field that returns the result of the evaluation of a formula, such as the addition of two other fields.
Calculated Text Field ^{(new in 1.5.5)}: a calculated custom field returning a String. It is a read-only field that returns the result of the evaluation of a formula, such as the concatenation of two other fields.
- Exact Text Searcher (Statistics-compatible) ^{(new in 1.5.6)}: a custom searcher that allows calculated text fields to be used in statistics gadgets
Calculated Date/Time Field ^{(new in 1.5.5)}: a calculated custom field returning a java.util.Date (which represents a date+time). It is a read-only field that returns the result of the evaluation of a formula.
Transition Date/Time Field ^{(new in 1.2)}: a calculated custom field returning the date and time of the last execution of a specified workflow transition.
Transition Caller Field ^{(new in 1.2)}: a calculated custom field returning the caller of the last execution of a specified workflow transition.
Transition Count Field ^{(new in 1.5.11)}: a calculated custom field returning the number of times a specified workflow transition was executed.
Last Field Value Change Date/Time Field ^{(new in 1.6)}: a calculated custom field returning the date and time a field was last modified.
Last Field Value Change Author Field ^{(new in 1.6.5/1.7.2)}: a calculated custom field returning the author of the last modification made to a field.
Parent Status Field ^{(new in 1.2.2)}: a calculated custom field returning the Status of the issue's parent issue.

Included JQL function:

currentUserPropertyAsList ^{(new in 1.1)}: a JQL function that returns the value of a property of the current user, transforming comma-separated values into a list of values.

Getting help

Please visit our Support Page for more information.

Installation

The plugin is a "type TWO" plugin, which means that the plugin can be installed by copying it to jira-home/plugins/installed-plugins or, better yet, using the excellent Atlassian Universal Plugin Manager.

Usage

Using calculated fields on large servers

If you are using complicated (like recursive) formulas in calculate custom fields, and you are running on a large server, you might need to tune JMCF's thread pool as documented in JMCF-173.

Calculated Number Field

Create a new custom field, choosing "Calculated Number Field" for its type.
During step 2, in the Description field, include the calculation formula using the syntax described below.
Re-index your data, as JIRA will kindly suggest you to.

Formula syntax

The formula is written using the BeanShell language, and should be included in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @@Formula: (note the colon at the end). For example:

You can naturally include the real description of the custom field as well. For example:

This field represents the number of Affected Versions.
<!-- @@Formula: issue.get("versions").size() -->

The formula itself is a Java-style expression that can reference any issue field value, include arithmetic operators as well as any other Java operator, and Java method calls (such as the .size() example above). Access to issue field values is achieved by the following syntax:

issue.get("<field_ID_or_Name>")

where <field_ID_or_Name> is either a built-in JIRA or custom field ID (the latter in the form customfield_nnnnn), or a field name. See this page for details.

You can also access the JIRA Issue object using the issueObject variable.

To identify the custom field ID:

go to Administration/Custom Fields
click on the "Configure" link for the custom field you're interested in
in the URL of the Configure Custom Field page, note the number after "customFieldId=" and append it to "customfield_" to build the custom field ID

Note that you must make sure the formula returns a number, or null.

Debugging the script

If the calculated field does not show up on the view issue screen, you must make sure the formula isn't raising an error. For that, you must look at the end of the JIRA log file (atliassian-jira.log) right after displaying the issue (displaying an issue will always force calculated fields to be re-calculated).

You can also include logging code into your script using the "log" object. For example:

<!-- @@Formula: 
log.error("Value of field 10114 is: "+issue.get("customfield_10114"));
log.error("Value of field 10150 is: "+issue.get("customfield_10150"));

if (issue.get("customfield_10114") == null || issue.get("customfield_10150") == null)
    return null;
 
return issue.get("customfield_10114") + issue.get("customfield_10150");   //we already made sure neither field is empty (==null) 
-->

We recommend you write to the logs using the "log.error()" method because ERROR-level logs are always written out to atlassian-jira.log (whereas DEBUG-level logs are filtered out by default).

Example

Adding two fields

To add two custom fields, such as "Business Value" and "Technical Value" to get an "Overall Value":

<!-- @@Formula: (issue.get("customfield_10114") != null ? issue.get("customfield_10114") : 0) + (issue.get("customfield_10150") != null ? issue.get("customfield_10150") : 0) -->

Custom formatting

You can also specify custom formatting for the value of the Calculated Number field. In the Description field, add your formatting formula using the following syntax:

The formula itself is a Java-style expression that can reference the value returned by the formula using the value variable. You can also use the numberTool object to format the number value:

numberTool.format(value)

Example

To display an icon to the left of the field value depending on the field value: