Reporting on Calculated Values with JMCF

Report on and chart custom calculations using Dataplane Reports and Jira Misc Custom Fields (JMCF).

With JMCF calculated fields, expose Jira’s ‘hidden’ information - such as dates and authors of specific transitions or field changes - that is otherwise not easily accessible to users, or create calculations - from simple math operations to sophisticated Groovy scripts - based on other fields and insights available in Jira.

Using JMCF with Dataplane

Dataplane Reports can use your existing JMCF calculated custom fields, or you can add new fields to be used in conjunction with Dataplane. JCMF custom fields can be used in most reports in Dataplane.

Since JMCF calculated field values are calculated in real-time and changes to a calculated value are not stored in the Jira changelog or database, only the current values of JMCF calculated fields (and not the historical, previously-calculated values) can be used in Dataplane.

Follow the steps below to add a JMCF calculated custom field for use with Dataplane. Existing custom fields can also be used, as long as the field's Search Template is configured for the appropriate data type (as described below).

Creating a Calculated Field

To create a new JMCF calculated field:

Install the Jira Misc Custom Fields (JMCF) app. See the JMCF installation documentation for instructions.
Navigate to Jira Administration (gear icon) → Issues → Custom Fields.
Click Add custom field.
Click on the All or Advanced tab on the left-hand side of the dialog, or enter "JMCF" in the Search field.
Select one of the Calculated (scripted) JMCF field types and click Next.
Give the new field a name and click Next.
Select the appropriate contexts for the field, and then click Create.
Scroll down the custom field list to find your newly-created field, click on the Actions menu ("...") for the field, and select Edit details or Edit.
Configure the field's Search Template option based on the type of data you wish to store in the field:

To use the field in Dataplane as... ...select for Search Template:
Numeric data "Number Search" or "Number Range Searcher"
Date "Date Range Picker" or "Date Time Range Picker"
Text "Free Text Searcher"
Finally, click Update to save the changes to the field.

The custom field's Search Template option controls the data type of the field, as seen by Dataplane Reports, and it influences the reports in which the custom field is available.

If you do not configure the Search Template option, the new custom field will not report any data when used in Dataplane Reports.

Writing a Script for the Calculated Field

To define the functionality of the newly added calculated field:

Navigate to Jira Administration (gear icon) → Issues and select Custom Fields in the left-hand navigation menu.
Scroll down to find your field, click on the Actions menu ("...") for the field, and select Configure contexts or Configure.
On the custom field Configure page, click Edit Groovy Formula to write the script for your field.

Making the Field Available to Reports

After creating a new calculated field, or changing an existing field's selected Search Template, you must reindex Jira and also click the "Sync Index" button on the Dataplane Reports → Administration → Configuration page. These two steps are required to make the field's values visible to Jira and Dataplane Reports.

You must also reindex Jira after modifying an existing calculated field's script. This is required to make the field's new values visible to Jira and Dataplane Reports. If you have only updated the script, reindexing Jira itself is sufficient – no additional Dataplane Reports operations need be performed.

The following tips are helpful for script testing and for speeding up a Jira reindex:

If you do not want the calculated field to be visible to end users outside of Dataplane Reports, do not associate the field with any Jira issue screens. However for initial script testing, it can be useful to temporarily associate the field with the Default or View issue screen in order to see and evaluate script results.
To test your script before doing a full reindex of Jira, you can edit any field value or perform a status transition in a single Jira issue. JMCF will automatically update the value of the calculated field for that one issue. You can then see the issue's calculated field value in your Dataplane reports.
If your version of Jira supports it, you can perform a background Jira reindex without downtime.
Performing a Jira reindex of only a single project is also possible.

Script Examples

This section provides examples of a few scripts that access issue data.

The JMCF documentation on available custom field types and custom field use cases provides more examples of how to use calculated fields. Most Groovy language concepts can be used within calculated fields, including accessing other custom field values, performing arithmetic, and calling Java or Groovy APIs.

For more details on calculated field script writing, see Writing scripts in JMCF using the Groovy language.

Number of Stories in the Epic

For epic issue types, the following script calculates the number of stories associated with the epic.

Create a new JMCF custom field of type Calculated (scripted) Number, set the field context to apply to Epic issues only, and use the following script.

In order to be usable in numeric reports, the field for this script must be configured with a Search Template of "Number Search" or "Numeric Range Searcher," as described above.

return issue.stories ? issue.getStories().size() : 0

Page Contents

To use the field in Dataplane as...	...select for Search Template:
Numeric data	"Number Search" or "Number Range Searcher"
Date	"Date Range Picker" or "Date Time Range Picker"
Text	"Free Text Searcher"