Home

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.

• 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.

• 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.

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

Calculated Number Field

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

Formula syntax

The formula 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:

<!-- @@Formula: formula goes here -->

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>")

where <field_ID> is a built-in JIRA field ID (see this list) or a custom field ID (in the form customfield_nnnnn).

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

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:

<!-- @@Format: formula goes here -->

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:

<!-- @@Format:
if (value > 21)
  return "<img src='/images/icons/priority_trivial.gif'> "+numberTool.format(value);
else if (value >= 10)
  return "<img src='/images/icons/priority_major.gif'> "+numberTool.format(value);
else
  return "<img src='/images/icons/priority_blocker.gif'> "+numberTool.format(value);
 -->

Transition Date/Time Field

1. Create a new custom field, choosing "Transition Date/Time Field" for its type.
2. During step 2, in the Description field, include the transition ID(s) (recommended) or name as described below.
3. Optionally, specify whether you want the first or last execution of the transition(s) ^{(new in 1.2.5 and 1.5.2)}
4. Re-index your data, as JIRA will kindly suggest you to.

Indicating the transition

The transition(s) should be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @TransitionId: or @TransitionName: (note the colon at the end). For example:

<!-- @TransitionId: transition ID -->

or

<!-- @TransitionName: transition name -->

If you use @TransitionId, you can specify a list of transition IDs, separated by commas ^{(new in 1.2.5 and 1.5.2)}:

<!-- @TransitionId: transition_ID_1 , transition_ID_2 -->

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

This field represents the date and time of the Resolution of this issue.
<!-- @TransitionId: 5 -->
<!-- @Execution: last -->

Specifying whether to capture the first or last transition execution

You can also specify whether to capture the first or last transition execution, using the @Execution: keyword followed by first or last. For example:

<!-- @Execution: first -->

If you don't specify anything, the last execution will be captured.

Transition Caller Field

1. Create a new custom field, choosing "Transition Caller Field" for its type.
2. During step 2, in the Description field, include the transition ID (recommended) or name as described below.
3. Optionally, specify whether you want the first or last execution of the transition(s) ^{(new in 1.2.5 and 1.5.2)}
4. Re-index your data, as JIRA will kindly suggest you to.

Indicating the transition

The transition(s) should be indicated in the field description inside an html comment (so that it remains invisible when showing the field description), preceded by the following keyword: @TransitionId: or @TransitionName: (note the colon at the end). For example:

<!-- @TransitionId: transition ID -->

or

<!-- @TransitionName: transition name -->

If you use @TransitionId, you can specify a list of transition IDs, separated by commas ^{(new in 1.2.5 and 1.5.2)}:

<!-- @TransitionId: transition_ID_1 , transition_ID_2 -->

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

This field represents the Resolver of this issue.
<!-- @TransitionId: 5 -->
<!-- @Execution: last -->

Specifying whether to capture the first or last transition execution

You can also specify whether to capture the first or last transition execution, using the @Execution: keyword followed by first or last. For example:

<!-- @Execution: first -->

If you don't specify anything, the last execution will be captured.

Parent Status Field

1. Create a new custom field, choosing "Parent Status Field" for its type.
2. Re-index your data, as JIRA will kindly suggest you to.

currentUserPropertyAsList JQL function

The currentUserPropertyAsList function can be used in a JQL query in an "in" or "not in" condition. It takes one parameter: the name of a user property.
When running the search query, the function will grab the value of the user property and treat it as a comma-separated list of values.

What use is it anyway?

This function is especially useful for building shared filters (and dashboards). You can, for example, create a standard filter that lists open issues for the current user's preferred projects, which you'll store in a user property:

resolution = Unresolved AND project in currentUserPropertyAsList("myProjects")