ScriptRunner Integration

In this page

What is ScriptRunner?

(supported since Better PDF Exporter 3.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 PDF API provided by the Better PDF Exporter app. They can generate custom PDF files, then use that in various types of PDF automations and integrations implemented in Groovy. (Although the PDF 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 PDF. (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 PDF. (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 PDF Exporter and ScriptRunner supports two equally important, but independent use cases: automating PDF reports in ScriptRunner-executed scripts (since Better PDF Exporter 3.1.0) and exporting ScriptRunner-managed fields to PDF (since Better PDF Exporter 7.4.0).
As an example for the former, watch this video about running custom scripts (done by ScriptRunner) that create and email periodic PDF exports (done by Better PDF Exporter):

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

ScriptRunner PDF export samples

Configuration

Generating PDF files from ScriptRunner-executed scripts

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

Configuring the ScriptRunner built-in script fields

There is nothing to do. Better PDF 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 output (the value and its format) when the field is exported to PDF.

In the following section, we explain how these settings determine the output. Note that although we implemented a simple and intuitive conversion logic, it is perfectly possible to modify that in the #cfValue macro (can be found in the top part of the template).

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 as a regular text field. 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 PDF, too.

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

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

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 PDF Exporter side. Better PDF Exporter will automatically recognize them, and export them accordingly.

Configuring the level of detail for issue picker fields

Exporting multi-valued fields (e.g. an issue picker that stores 5 issues) may require significant amount of paper space in the exported document. In the templates with limited space (e.g. in issue-navigator-fo.vm where each field value must fit a table cell), it may lead to sub-optimal layout: a narrow column containing very tall cells that include several line breaks.

In order to support both the "non-limited space" and "limited space" types of templates, two output formats are available for the Issue(s) picker and Remote issue(s) picker custom fields:

1. Compact: The comma separated list of the issue keys are exported. This is the default in the templates with limited space.
2. Detailed: The issue keys and summaries are exported with each issue exported to a separate line. This is the default in the templates where space is usually not a problem.

You can choose the default with this configuration parameter in the top part of the template:

## issue-fo.vm

#set($exportDetailedValues = true)       ## set to "true" to export detailed values for custom fields

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 PDF 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 the PDF document. 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 PDF 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)