In this page

Extending the field-helper-tool.groovy script

field-helper-tool.groovy is a customizable Groovy script that is part of the Better Excel Exporter app and that gives easy access to Jira data for the Excel templates. The script file is well-structured and easy to read, and can be customized just like any other Groovy script used by the app.

This article guides you through the most typical customization and extension tasks.

Custom fields

Adding support for new custom field types

The most typical extension you want to make in field-helper-tool.groovy is adding support for new custom field types. Although we support many custom fields out of the box, you may be using 3rd party apps that are not among the official integrations or you may be using your own custom built apps.

Assuming you have basic Java and Groovy skills, exporting custom fields is a fairly straightforward thing to do. For the implementation work, you will need to find out these for each new custom field type:

  1. What is the type key of the custom field?
  2. How to get the value from the value object or the custom field object?
  3. What is the best cell type for the value: text, number or date?
  4. If this is number or date type data, what is the best cell format?
Finding the custom field type key

Each custom field type is identified by a unique textual key, like com.pyxis.greenhopper.jira:gh-sprint.

How to find this?

  1. Go to an issue that has a custom field of this type.
  2. Export the issue to XML by clicking Export → XML.
  3. In the resulted XML document, look for the custom field by its name, and the field type key will be available in the corresponding key attribute: 
    <customfield id="customfield_11103" key="com.tempoplugin.tempo-accounts:accounts.customfield">
<customfieldname>Account</customfieldname>
Returning the custom field value

For this, you should understand how the custom field returns its value, and how can you transform that (if necessary) to an Excel field value. For text fields, this can be as simple as returning the unchanged String object. For some more complicated field, the value itself may be just an ID, that you need to transform to a representation that the users expect to see. For example, you may want to transform a sprint ID to the sprint's name and return that.

This step depends on the field implementation, therefore it is useful to have the Java source of the custom field type class, of the value object class, etc. In most cases you just need call getters on those. As always, you can use the implementation of the already supported custom fields as samples.

Add the logic that returns the field value as a new case in the getCustomFieldValue() method: 

case "com.acme:mycustomfield": // <- your custom field type key comes here
	(value != null) ? value.toString() : null // <- your logic comes here
	break

Pro tip: in certain cases, you may not have the Java source of the custom field, but you need to support that any way. You can resort to reverse engineering, by extracting the app JAR, checking the atlassian-plugin.xml file for the custom field type configurations and decompile the implementation classes with JD-GUI.

Returning the cell type

Add the logic that returns the cell's format to the completely trivial getCustomFieldCellType() method. You can use one of "text", "number" or "date", whichever represent your data the best. Please note that the default format is "text", therefore if your data is of "text" type, then you can completely skip this step and leave the method unchanged.

Returning the cell format

If your data is "number" or "date" type, you can specify the exact cell format to be used with them. For example, a number representing a currency value may be best used with a 2 decimal digit format that also incorporates the currency sign, while a "days since" kind of value may be just an unsigned integer.

For this, you have to return the Excel cell format strings from the trivial getCustomFieldFormat() method.