ScriptRunner Integration

In this page

What is ScriptRunner?

(supported since Better Excel Exporter 1.1.0)

ScriptRunner is the most powerful app to extend and customize Jira with every kind of custom logic, expressed as Groovy scripts.

ScriptRunner integration features

• ScriptRunner-executed scripts can access the Excel API provided by the Better Excel Exporter app. They can generate custom Excel files, then use that in various types of Excel automations and integrations implemented in Groovy. (Although the Excel API can be used from any language running on the JVM, the Groovy language is Midori's primary recommendation to solve these types of problems with ease.)
• You can export the ScriptRunner-managed built-in script field types, like Date of First Transition, Issue(s) picker, No. of Times In Status, Remote issue(s) picker, Show parent issue in hierarchy, Time of Last Status Change and Database picker, to Excel. (These are the fields which are powered by ScriptRunner's default Groovy scripts, therefore work without any coding.)
• You can export the ScriptRunner-managed custom script field types to Excel. (These are the fields which are powered by Groovy script written by you, giving you unlimited flexibility.)

(Need more features? Tell us in a support ticket!)

Tutorial video

The integration between Better Excel Exporter and ScriptRunner supports two equally important, but independent use cases: automating Excel reports in ScriptRunner-executed scripts (since Better Excel Plugin 1.1.0) and exporting ScriptRunner-managed fields to Excel (since Better Excel Exporter 4.4.0). As an example for the former, watch this video about running custom scripts (done by ScriptRunner) that create and email periodic Excel reports (done by Better Excel Exporter):

As an example for the latter, watch this video about exporting ScriptRunner-managed fields to Excel:

ScriptRunner Excel export samples

Configuration

Generating Excel files from ScriptRunner-executed scripts

There is a complete tutorial dedicated to this use case. Please read the Excel API tutorial to get started.

Configuring the ScriptRunner built-in script fields

There is nothing to do. Better Excel Exporter will automatically recognize the built-in script fields, and export them accordingly.

Configuring the ScriptRunner custom script fields

In addition to the built-in script fields, ScriptRunner also allows you to implement custom script fields which are powered by Groovy scripts written by you. These custom script fields have two configuration options, Template and Searcher, which affect the cell type, the cell format and the cell value when the field is exported to Excel.

In the following section, we explain how these settings determine the Excel cell properties. Note that although we implemented a simple and intuitive conversion logic, it is perfectly possible to modify that in the field-helper.groovy script.

First, it is checked if there is a custom template set for the custom script field (i.e. if the Template setting is set to Custom). If there is, the field will be exported to a regular text cell. Rationale: we assume that you use a custom template to modify the presentation of the value in the Jira web interface and that you want to export this custom presentation to Excel, too.

If there is no custom template set, the field's searcher (also called indexer) determines the cell properties. Obviously, the searcher heavily depends on the return type of the script.

The following table summarizes the recommended combinations that are exported correctly to Excel:

Template	Return type of the script	Searcher(s)
Text field (multi-line)	String	Free Text Searcher, Exact Text Searcher
Date	Date	Date Time Range picker
Date Time	Date	Date Time Range picker
Absolute Date Time	Date	Date Time Range picker
Duration	Long	Duration Searcher
Duration (time-tracking)	Long	Duration Searcher
Number Field	Double	Number Searcher
User Picker (single user)	ApplicationUser	User Picker Searcher
User Picker (multiple users)	Collection<ApplicationUser>	Multi User Picker Searcher
Group Picker (single group)	Group	Group Picker Searcher
Group Picker (multiple groups)	Collection<Group>	Multi Group Picker Searcher
HTML	String	Free Text Searcher, Exact Text Searcher
Custom	any	any
Version Picker	Collection<Version>	Version Searcher
Project Picker	Project	Project Dropdown Searcher

A practical note on return types: when working with Jira objects, always check their types, because those are not always straight-forward! For example, due to historical reasons, the Issue class offers two getters to obtain the encompassing project. The first one is more intuitively named, but its return type will not work as expected. You probably want to use the second one:

// Issue.java

GenericValue getProject();
Project getProjectObject();

After you double-checked if the return type is correct, also make sure that you configured a searcher that is able to handle that return type. For example, a Date Time Range picker expects that your script returns Date objects, otherwise indexing will fail and your field will not work.

Other than correctly configuring the custom script fields on the ScriptRunner side, there is nothing to do on the Better Excel Exporter side. Better Excel Exporter will automatically recognize them, and export them accordingly.

Performance tuning

While working on the ScriptRunner integration, we ran lots of performance profiling sessions to understand how the script fields affect the total creation time of the Excel files.

To create the export, the scripts are automatically executed for each issue and each script field, so that the most current field value gets exported to each Excel cell. Not surprisingly, there are three factors that affect the total time required for this:

1. the number of issues
2. the number of script fields
3. the time of a single script execution

For example: if you export 100 issues with 3 script fields, it results in 3*100 script executions. If you have a script that runs for 5 milliseconds, then the total execution takes 3*100*5 = 1500 milliseconds (1.5 seconds).

Therefore, there is only one rule of thumb: write efficient scripts, because every millisecond can matter if you have lots of issues and lots of script fields! (It will not only make the Excel exports fast, but the web UI powered by the ScriptRunner fields will be fast, too.)

Learn more about ScriptRunner

• ScriptRunner product information (at its own vendor)
• ScriptRunner documentation
• ScriptRunner app page (on the Atlassian Marketplace)