In this page

Integration with other Jira apps
Automation Lite for Jira
Integration features
Configuration
Learn more about Automation Lite for Jira
Color Custom Fields
Integration features
Export samples
Configuration
Exporting Color Custom Fields custom fields
Configuring the export format for Color Custom Fields custom fields
Troubleshooting
I get "StringIndexOutOfBoundsException: String index out of range" error in the PDF
Learn more about Color Custom Fields
Gliffy
Integration features
Export samples
Configuration
Configuring the PDF templates for Gliffy
Configuring the REST API for Gliffy
Why do all REST API calls result in "Server returned HTTP response code: 403" or "401" error?
Learn more about Gliffy
Insight
Integration features
Export samples
Configuration
Exporting Insight custom fields
Configuring the export format for Insight custom fields
Learn more about Insight
JEditor (Jira Editor)
Integration features
Export samples
Configuration
Learn more about JEditor (Jira Editor)
Jira Service Desk
Integration features
Export samples
Configuration
Exporting Jira Service Desk custom fields
Configuring the export format for Jira Service Desk custom fields
Learn more about Jira Service Desk
Jira Software
Integration features
Export samples
Configuration
Exporting Jira Software custom fields
Configuring the PDF templates for Jira Software
Learn more about Jira Software
nFeed (now called Elements Connect!)
Integration features
Export samples
Configuration
Troubleshooting
When I uninstall or disable the nFeed app, it also disables the Better PDF Exporter app
There is a "Failed to find the nFeed API" warning in my Jira log
Learn more about nFeed (now called Elements Connect!)
Portfolio for Jira
Integration features
Export samples
Configuration
Exporting Portfolio custom fields
Exporting issues in a Portfolio program
Exporting issues in a Portfolio plan
Exporting issues within the hierarchy, by team and by target dates
Learn more about Portfolio for Jira
Profields
Integration features
Export samples
Configuration
Exporting Profields custom fields for issues
Exporting Profields custom fields for projects
Learn more about Profields
ScriptRunner
Integration features
Export samples
Configuration
Generating PDF files from ScriptRunner-executed scripts
Exporting ScriptRunner's built-in script fields
Exporting ScriptRunner's custom script fields
Configuring the level of detail for issue picker fields
Performance tuning
Learn more about ScriptRunner
Table Grid Editor
Integration features
Export samples
Configuration
Learn more about Table Grid Editor
Table Grid Next Generation
Integration features
Export samples
Configuration
Learn more about Table Grid Next Generation
Tempo Timesheets
Integration features
Export samples
Configuration
Exporting Tempo custom fields
Enabling the Tempo servlet
Configuring the PDF templates for Tempo worklogs
Configuring the period filter for Tempo worklogs
Configuring the user filter for Tempo worklogs
Configuring pre-loading for Tempo worklogs
Configuring the Tempo servlet request details
Learn more about Tempo Timesheets
Zephyr
Integration features
Export samples
Configuration
Installing ZAPI
Configuring the PDF templates for Zephyr
Configuring the REST API for Zephyr
Why do all REST API calls result in "Server returned HTTP response code: 403" or "401" error?
Learn more about Zephyr

Integration with other Jira apps

This page describes how Better PDF Exporter for Jira exports data from, or integrate with popular Jira apps.

If an app is not mentioned here, it does not mean that it would not work in PDF exports. This page only lists the most important apps, that are actively used by the Better PDF Exporter user community and whose integration is officially supported by Midori.

Automation Lite for Jira

(supported since Better PDF Exporter 3.1.0)

Automation Lite for Jira is a flexible automation app for Jira (similar to the IFTTT or Zapier services).

This allows to create automation rules from triggers (when should happen?) and actions (what should happen?):

Integration features
  • Better PDF Exporter extends Automation Lite with the Send PDF in email action to email PDF documents from Jira at regular intervals (periodic job) or at issue events (issue created, updated, assigned, etc.).
  • It also offers the Save PDF to the file system action to export PDF documents from Jira at regular intervals or at issue events.
  • Finally, it offers the Attach PDF to an issue action to attach PDF documents from Jira at regular intervals or at issue events.
Configuration

Read the automation tutorial for a complete how-to.

Learn more about Automation Lite for Jira

Color Custom Fields

(supported since Better PDF Exporter 7.3.0)

Color Custom Fields extends Jira with custom fields that store color values. It makes managing issue attributes that can be intuitively color-coded (e.g. Risk, Impact or Complexity) intuitive and visual.

The Better PDF Exporter app enables exporting those to customizable PDF documents:

Integration features
  • You can export the Color Custom Fields-managed custom field types like Select Color and Picker Color to PDF.
Export samples

See the sample files exported from Color Custom Fields (in the Template Gallery).

Configuration

Exporting Color Custom Fields custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Color Custom Fields managed fields and export them accordingly.

Configuring the export format for Color Custom Fields custom fields

The default behaviour is that the color RGB values or color names will be exported (e.g. "#b04c75" or "green"). You can show the color itself in a small solid-filled, colored rectangle by uncommenting this line in the issue-fo.vm and issue-navigator-fo.vm templates:

## uncomment this to export the colored rectangle
## <fo:inline background-color="$xmlutils.escape($color)" border="thin solid #777777">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;</fo:inline>
$xmlutils.escape($color)

Note that by commenting out the first and the second line, you have the options to export the colored rectangle, the color name, or both. All these will work.

Troubleshooting

I get "StringIndexOutOfBoundsException: String index out of range" error in the PDF

First, this problem can occur only if you enabled the "colored rectangle" export.

The root cause is that, unfortunately, Color Custom Fields does not validate the color RGB strings that its UI allows to select or enter. With some tricks, user can enter invalid RGB values, like "#ffcc99a" (note that instead of 6, it contains 7 characters after the hash mark!).

Although the browser tolerates these and treats them as white color in most cases, the PDF renderer is stricter and it raises this exception for invalid RGB strings:

java.lang.StringIndexOutOfBoundsException: String index out of range: 9
 at java.lang.String.substring(String.java:1963)
 at org.apache.fop.fo.expr.PropertyTokenizer.nextColor(PropertyTokenizer.java:239)
 at org.apache.fop.fo.expr.PropertyTokenizer.next(PropertyTokenizer.java:175)
 at org.apache.fop.fo.expr.PropertyParser.parseProperty(PropertyParser.java:118)
 at org.apache.fop.fo.expr.PropertyParser.parse(PropertyParser.java:91)
 at org.apache.fop.fo.properties.PropertyMaker.make(PropertyMaker.java:438)
 at org.apache.fop.fo.PropertyList.convertAttributeToProperty(PropertyList.java:413)
 at org.apache.fop.fo.PropertyList.addAttributesToList(PropertyList.java:321)
 at org.apache.fop.fo.FObj.processNode(FObj.java:122)
 ...

How to fix it? Turn off the "colored rectangle" display and enable the "color name" display for the field values, based on the configuration guide above. Now the rendering will succeed even if the RGB string is invalid, and will show you which field value in which issue is the problem. Fix that, and then you can re-enable the "colored rectangle" display.

Learn more about Color Custom Fields

Gliffy

(supported since Better PDF Exporter 5.3.0)

Gliffy is a powerful app to create diagrams and wireframes for Jira issues.

Watch this short introductory video to see how easy you can export your Gliffy diagrams to PDF:

Integration features
  • You can export the high resolution Gliffy diagrams that illustrate your issues to PDF documents. Gliffy diagrams will be core part of your issue exports, just like image attachments.
Export samples

See the sample files exported from Gliffy (in the Template Gallery).

Configuration

Configuring the PDF templates for Gliffy

The template issue-fo.vm contains a single configuration parameter in its top part, to enable this feature:

## Gliffy
#set($exportGliffyDiagrams = false) ## set to "true" to export Gliffy diagrams
Configuring the REST API for Gliffy

As this integration relies on the Gliffy REST API, you need to configure the login credentials of a valid Jira user account for the REST API calls. Please set the username and password to these configuration variables in issue-fo.vm:

## Jira user credentials for REST API calls
#set($restUserName = "admin") ## Jira username for REST authentication
#set($restPassword = "admin") ## Jira password for REST authentication

Don't worry about using plain text passwords: this file is visible only for Jira administrators, who would have super-user permissions any way. Also note that if you are using multiple REST API based integrations in the same template (ex: Gliffy plus Zephyr), then all REST API will be used with the same user credentials.

As a good practice, this is safer to avoid usernames and passwords that contain non-English characters. Albeit our Gliffy script correctly encodes international usernames and passwords, their handling also depends on the configuration of the container that hosts your Jira web application (typically Tomcat). If you're having difficulties, just replace those characters in your username or password with English letters or numbers.

Why do all REST API calls result in "Server returned HTTP response code: 403" or "401" error?

First off, be 101% sure that the REST username and password are correct. If those are, but you are still receiving 403's, please open Jira in your browser, logout and login with the same user account which you configured for the REST calls. You will be asked for a CAPTCHA verification, but after answering that and logging in to Jira, the REST calls will also be successfully executed!

Why does this happen? As its default behavior, Jira will lock your account and present a CAPTCHA on the login form after a few (3 - 5) unsuccessful login attempts. Since the Gliffy integration may send several REST API requests per export, the unsuccessful login attempts limit can be reached very quickly if the password is wrong. To resolve this: you just have to pass the CAPTHCA verification, that's it.

Please note that it will never happen again, unless you change the password of the corresponding Jira user account.

If you are an administrator, there is also a quicker solution: go to Administration → User management and clear the failed login attempts counter with one click.

Tip: you can increase the allowed login attempts or even disable this feature altogether in Jira.

Learn more about Gliffy

Insight

(supported since Better PDF Exporter 5.9.0)

Insight is the leading asset management app for Jira, that allows implementing CMDB, CRM, HR, ITSM or ITIL functionality on the Jira platform.

Watch this short introductory video to see how fast you can export your Insight data to PDF:

Integration features
  • You can export all Insight-managed custom field types like Insight Object (single select), Insight Object (multi select), Insight Object/s (since app version 6.4.0), Insight Referenced Object (single select), Insight Referenced Object (multi select) and Insight Object (read only) to PDF.
  • You can configure the export format to include object names (e.g. "My supa dupa server"), object keys (e.g. "My supa dupa server [SRVR-123]"), object attributes (e.g. "My supa dupa server [SRVR-123] (Manufacturer=Cray Research, Vector Processors=4, Type=Supercomputer)") and any combination of these.
Export samples

See the sample files exported from Insight (in the Template Gallery).

Configuration

Exporting Insight custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Insight managed fields and export them accordingly.

Configuring the export format for Insight custom fields

The default behaviour is that object names and object keys will be exported (e.g. "My supa dupa server [SRVR-123]"). You can include object name, object key and attributes by setting these configuration variables in the top part of the issue-fo.vm and issue-navigator-fo.vm templates:

## Insight
#set($exportInsightObjectNames = true) ## set to "true" to export Insight object names
#set($exportInsightObjectKeys = true) ## set to "true" to export Insight object keys
#set($exportInsightObjectAttributes = false) ## set to "true" to export Insight object attributes

If you want full control over the export format, look at the Velocity macro definition marked with this comment in issue-fo.vm and issue-navigator-fo.vm:

## Insight custom field types
## ...

Note: you can absolutely have different export formats in the two templates, as issue-fo.vm typically has more space for details.

Learn more about Insight

JEditor (Jira Editor)

(supported since Better PDF Exporter 3.3.0)

JEditor is a hyper-popular WYSIWYG rich text editor app for Jira.

Watch this short video to see the JEditor Better PDF Exporter integration in action:

Integration features
  • Better PDF Exporter supports JEditor's all formatting features.
  • You can export JEditor-rendered Description and Environment fields, issue comments, and any single- or multi-line text custom fields to PDF.
Export samples

See the sample files exported from JEditor (Jira Editor) (in the Template Gallery).

Configuration

There is nothing to do. Better PDF Exporter will automatically recognize the JEditor rendered fields and export them accordingly.

Learn more about JEditor (Jira Editor)

Jira Service Desk

(supported since Better PDF Exporter 3.4.0)

Jira Service Desk is the de-facto service desk solution running on the top of Jira.

Watch this quick tutorial how to export tickets directly from Service Desk queues to PDF:

Integration features
  • You can export PDF documents directly from the Queue view (with all tickets in the queue). (supported since Better PDF Exporter 4.0.0)
  • You can export the Jira Service Desk-managed custom field types, like Approvals (including decision details), Customer Request Type, Organizations, Request Participants, Satisfaction, Satisfaction Date, SLA to PDF.
Export samples

See the sample files exported from Jira Service Desk (in the Template Gallery).

Configuration

Exporting Jira Service Desk custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Jira Service Desk managed fields and export them accordingly.

Configuring the export format for Jira Service Desk custom fields

There is one configuration variable that affects the output format of the Approvals field. The default behaviour is that the overall approval will be exported ("Approved" "Declined", "?"). You can also include the individual approvers' decisions by setting this configuration variable in the top part of the issue-fo.vm and issue-navigator-fo.vm templates:

## Jira Service Desk
#set($exportServiceDeskApprovalDecisions = false) ## set to "true" to export approver decisions

If you want full control over the export format, look at the Velocity macro definition marked with this comment in the above mentioned templates:

## Jira Service Desk custom field types
## ...

Note: you can absolutely have different export formats in the different templates, as issue-fo.vm typically has more space for details.

Learn more about Jira Service Desk

Jira Software

(supported since Better PDF Exporter 4.0.0)

Jira Software is the Scrum and Kanban solution for Jira.

Watch how to export issues from the backlog to PDF or prepare ready-to-print story cards:

Integration features
  • You can export PDF documents directly from the Backlog (with all the issues in a sprint or in the backlog), Scrum Board and Kanban Board views (with all the issues in a column).
  • You can export the Jira Software-managed custom field types, like Sprint, Epic, Story Points, etc., to PDF.
  • You can export the Jira Development Integration app managed custom field called Development (which stores branch, commit and pull request information) to PDF.
  • Better PDF Exporter offers a Sprint Report template, with Burn Down Chart, Daily Velocity Chart and agile key performance metrics. It can flexibly work from any list of input issues, not strictly belonging to the same Jira Software sprint.
  • Better PDF Exporter also offers a customizable story card template to print physical story cards from any type of Jira issues, also including Jira Software stories. (It works both with and without Jira Software.)
Export samples

See the sample files exported from Jira Software (in the Template Gallery).

Configuration

Exporting Jira Software custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Jira Software managed fields and export them accordingly.

Configuring the PDF templates for Jira Software

The templates using Jira Software data, story-card-fo.vm and burn-down-chart-fo.vm, contain several configuration parameters in their top part. These are are documented right in the template source code.

The most important ones are the IDs of the Jira Software custom fields:

#set($storyPointsCustomFieldID = 10900)

There is one particularly interesting setting in burn-down-chart-fo.vm. As this template can also work without Jira Software, setting the ID of the "Sprint" custom field is optional. But even when it is unset, the template needs to find out the sprint's start- and end date to be able to render the charts!

What it does, is parsing the dates from the description of the saved filter that was executed to produce the input list of issues. The description is expected to be in a format that ends with " dd/mm/yyyy - dd/mm/yyyy", for example: "My sprint report 01/02/2013 - 15/02/2013". Please note that it also means that you can render Burn Down Charts from any issue list, they do not need to be related via a Jira Software sprint!

Learn more about Jira Software

nFeed (now called Elements Connect!)

(supported since Better PDF Exporter 5.10.0)

The nFeed app integrates external data sources (SQL databases, LDAP, Active Directory, REST APIs, Salesforce, CSV files, etc.) to Jira.

Take 2 minutes and watch this short introductory video about exporting nFeed managed data to PDF:

Integration features
  • You can export the nFeed-managed custom field types like nFeed, nFeed - Date, nFeed - DateTime, nFeed - User (and even the legacy nFeed [deprecated]) to PDF.
Export samples

See the sample files exported from nFeed (now called Elements Connect!) (in the Template Gallery).

Configuration

There is nothing to do. Better PDF Exporter will automatically recognize the nFeed managed fields and export them accordingly.

Troubleshooting

When I uninstall or disable the nFeed app, it also disables the Better PDF Exporter app

This is a very infrequent and random problem, which is deeply rooted in Jira's OSGi component dependency management. Solution: simply re-enable Better PDF Exporter (via the Universal Plugin Manager) and it will work.

There is a "Failed to find the nFeed API" warning in my Jira log

Just like previous one, this is rare and random, also related to OSGi and Jira's internal ComponentAccessor returning a null object as nFeed API. Solution: simply reinstall Better PDF Exporter and it will work (and it will not happen again). (Note: even with the warning written to the log, the export falls back to a simplified mode and gives a so-so result for the users.)

Learn more about nFeed (now called Elements Connect!)

Portfolio for Jira

(supported since Better PDF Exporter 7.2.0)

Portfolio for Jira is Atlassian's Project Portfolio Management (PPM) solution, an agile roadmapping and project planning app for Jira Software.

The Better PDF Exporter app enables exporting the portfolio items (which are issues themselves) to customizable PDF documents:

Integration features
  • You can export the Portfolio-managed custom field types like Original story points, Parent Link, Team, Target start and Target end, to PDF.
Export samples

See the sample files exported from Portfolio for Jira (in the Template Gallery).

Configuration

Exporting Portfolio custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Portfolio managed fields and export them accordingly.

Exporting issues in a Portfolio program

Portfolio for Jira offers several JQL functions to find issues in a program, in a plan, by parent, by child, etc. Use these JQL functions in the Issue Navigator to search for the issues to export, apply your preferred sorting, then export the result using Better PDF Exporter.

To search for the issues in a Portfolio program, use this JQL:

issuekey in issuesInProgram(12)

where "12" is the program's ID. To learn its ID, open the program, and you will see the ID in the page URL (in the browser's address bar).

Exporting issues in a Portfolio plan

To search for the issues in a Portfolio plan, use this JQL:

issuekey in issuesInPlan(34)

where "34" is the plan's ID. To learn its ID, open the plan, and you will see the ID in the page URL (in the browser's address bar).

Exporting issues within the hierarchy, by team and by target dates

Similarly to the use cases discussed in the previous sections, you can use JQL to search for:

  • the issues linked via the Parent Link custom field
  • the parents of issues
  • the children of issues
  • the issues assigned to a team
  • the issues that have target start- and target end dates

See the Portfolio for Jira documentation for examples.

Learn more about Portfolio for Jira

Profields

(supported since Better PDF Exporter 7.3.0)

Profields is the project administration app for Jira that enables adding custom fields to projects, such as due dates, budgets and supervisors.

After mapping the project custom fields to issue custom fields (using the standard Profields feature), the Better PDF Exporter app transparently exports those to PDF:

Integration features
  • You can export the Profields-managed issue custom field types to which the Profields-managed project custom fields are mapped to. The supported project custom field types include Date, Duration, Group, List, Number, Priority, Project, Status, Text and User to PDF. (Cumulative and Script are not supported, as those cannot be mapped to issue custom fields.)
Export samples

See the sample files exported from Profields (in the Template Gallery).

Configuration

Exporting Profields custom fields for issues

Please note that the Profields managed custom fields are primarily attached to projects (not to issues). To make them available also for the issues, don't forget to enable mapping the project fields to Jira issue custom fields.

After this, Better PDF Exporter will automatically recognize the issue custom fields to which the project custom fields are mapped to, and export them accordingly.

Exporting Profields custom fields for projects

In another Profields-related use case, you want to export the projects (not issues) and their custom fields to PDF. Although the default export types offered by Better PDF Exporter primarily focus on issues, exporting project is also possible with an easy workaround.

Steps:

  1. Open Issue Navigator.
  2. Select exactly one issue from each project you want to export. (See the next section for techniques.)
  3. Show the Project column.
  4. Show the columns with those Profields-managed fields that you want to export.
  5. Hide all issue-specific columns (like Summary and such).
  6. At this point, there is one project in each line and there are only project-dependent columns shown. Export using the "Issue List (PDF)" option in the Export drop-down menu.
  7. Voila, you have just exported your projects to PDF!

All right, but how to select the issues as in step 2 above?

  1. If you want to export only a couple of projects, you can write a JQL by enumerating the first issue keys in those:
    key IN (FOO-1, BAR-1, BAZ-1) ORDER BY project
    This is simple, but it is painful for a larger number of projects.
  2. If you want to make it more automatic, introduce a new issue type that represents projects, and give it some intuitive name, e.g. "Project Object". Then, create exactly one instance of this issue type in each project. Having that, a JQL query like this will return that single issue from each project:
    type = "Project Object" ORDER BY project
    Note that it will work for any number of projects until there is one "Project Object" type issue created in those.
  3. If you need more flexibility, write a short Groovy script that receives the issue collection as input, iterates over it, only leaves one issue per project and removes the rest, and returns the resulted collection to the template.

Learn more about Profields

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.

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

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.)
Export samples

See the sample files exported from ScriptRunner (in the Template Gallery).

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.

Exporting ScriptRunner's built-in script fields

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

Exporting ScriptRunner's 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:

TemplateReturn type of the scriptSearcher(s)
Text field (multi-line)StringFree Text Searcher, Exact Text Searcher
DateDateDate Time Range picker
Date TimeDateDate Time Range picker
Absolute Date TimeDateDate Time Range picker
DurationLongDuration Searcher
Duration (time-tracking)LongDuration Searcher
Number FieldDoubleNumber Searcher
User Picker (single user)ApplicationUserUser Picker Searcher
User Picker (multiple users)Collection<ApplicationUser>Multi User Picker Searcher
Group Picker (single group)GroupGroup Picker Searcher
Group Picker (multiple groups)Collection<Group>Multi Group Picker Searcher
HTMLStringFree Text Searcher, Exact Text Searcher
Customanyany
Version PickerCollection<Version>Version Searcher
Project PickerProjectProject 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

Table Grid Editor

(supported since Better PDF Exporter 3.4.0)

Table Grid Editor is a Jira app that extends Jira with list- and spreadsheet-like (table-like) custom fields. (Table Grid Editor is effectively replaced by its modern re-implementation called Table Grid Next Generation. Both the old and the new apps are integrated with Better PDF Exporter.)

Watch this short introductory video to learn how easy it is to export Table Grid Editor managed data to PDF:

Integration features
  • You can export any Table Grid Editor managed custom field to PDF.
Export samples

See the sample files exported from Table Grid Editor (in the Template Gallery).

Configuration

There is nothing to do. Better PDF Exporter will automatically recognize the Table Grid Editor managed fields and export them accordingly.

Learn more about Table Grid Editor

Table Grid Next Generation

(supported since Better PDF Exporter 7.3.0)

Table Grid Next Generation is a Jira app that extends Jira with list- and spreadsheet-like (table-like) custom fields. (Table Grid Next Generation is the modern re-implementation of the legacy app called Table Grid Editor. Both the old and the new apps are integrated with Better PDF Exporter.)

Watch this short introductory video to learn how easy it is to export Table Grid Next Generation managed data to PDF:

(although this video was recorded about the old app, the new app works 100% identically!)

Integration features
  • You can export any Table Grid Next Generation managed custom field to PDF.
Export samples

See the sample files exported from Table Grid Next Generation (in the Template Gallery).

Configuration

There is nothing to do. Better PDF Exporter will automatically recognize the Table Grid Next Generation managed fields and export them accordingly.

Note on compatibility: pre-1.4.1 versions of the Table Grid Next Generation app return the table data with some defects (missing rows, different column order, etc.), which also appear in the exported PDF. Therefore, upgrading to 1.4.1 or newer is strongly recommended.

Learn more about Table Grid Next Generation

Tempo Timesheets

(supported since Better PDF Exporter 3.4.0)

Tempo Timesheets is the most widely used time tracking solution for Jira.

Create customized timesheets or invoices from the Tempo timesheets with one click:

Integration features
  • You can export PDF documents directly from the Timesheet (with all issues in the timesheet), Calendar (with all issues in the selected period), Report (with all issues in the report) and List views (with all unique issues in the list). (supported since Better PDF Exporter 4.0.0)
  • You can export the Tempo-managed custom field types, like Account, Team, Iteration, etc., to PDF.
  • You can export the Tempo managed worklogs to PDF along with their custom worklog attributes. You can optionally filter the Tempo worklogs by start date and end date or to exclude the non-billable worklogs, for example.
  • Better PDF Exporter for Jira also offers a customizable timesheet / invoice template to generate custom timesheets and time-based invoices from Tempo worklogs.
Export samples

See the sample files exported from Tempo Timesheets (in the Template Gallery).

Configuration

Exporting Tempo custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Tempo managed fields and export them accordingly.

Enabling the Tempo servlet

If you wanted to export Tempo worklogs, PDF templates download those from the Tempo servlet during the document rendering. Tempo servlet is basically Tempo's HTTP based API.

Please execute the following steps to allow the templates accessing the servlet:

  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsAccess Control (under Tempo).
  3. Enter "127.0.0.1" (localhost) or the Jira server's actual IP to "Allowed addresses", and "Save" the changes.
  4. Copy the "Security token" string to the clipboard.
  5. Go to AdministrationAdd-onsPDF Templates (under PDF Views).
  6. Open the issue-fo.vm template for editing, uncomment this variable in the top part, and paste the security token from the clipboard to the value:
    ## issue-fo.vm
    
    #set($tempoApiToken = '3022ac1e-db73-4c54-9c15-cceccbb94554')
    
  7. Paste the security token similarly to the timesheet-fo.vm template, as well.
  8. Export a Jira issue having Tempo worklogs with the "PDF" view as a test. You will see java.io.IOException: Server returned HTTP response code: 401 for URL error messages in the exports until the access permissions are properly set up.
Configuring the PDF templates for Tempo worklogs

After you set up the Tempo servlet access, you may want to configure the details of exporting the worklogs.

There is a configuration parameter in the top part of the issue-fo.vm template to filter the worklogs for the current user:

## issue-fo.vm

#set($tempoFilterByUser = false)       ## set to "true" to export the Tempo worklogs of the current user only, or "false" to export everyone's

There are multiple configuration parameters in timesheet-fo.vm to look up the customer from Tempo, to export the custom worklog attributes, and to filter the worklogs by their worklog attributes (ex: non-billable):

## timesheet-fo.vm

#set($tempoExportCustomer = true)              ## whether to look up the "Customer" from Tempo based on the account set in the first issue to be exported
#set($tempoExportWorklogAttributes = false)    ## whether to display the worklog attributes for each worklog item
#set($tempoExcludeWorklogsWithAttributesContaining = "NonBillable=NonBillable")    ## Tempo worklogs with attributes containing this string will be skipped, ex: "NotBillable=NotBillable" will exlude the worklog where the "Non Billable" checkbox attribute is unchecked
Configuring the period filter for Tempo worklogs

If there is a time period specified, then the tempo-tool.groovy script exports only the worklogs in that time period. The time period is specified by a start- and an end date passed in request parameters.

Start and end date are available in Tempo contexts (like the Timesheet screen), but not available in others (like the Issue Navigator screen). This is simply because while the Tempo contexts offer a period selector, Issue Navigator doesn't.

For this latter case, the period is basically "all times". You can configure the default period by setting the values in the end of these expressions:

## issue-fo.vm or timesheet-fo.vm

#set($tempoDateFrom = '2000-01-01')    ## start date for the exportable Tempo worklog period
#set($tempoDateTo = '2099-12-31')      ## end date for the exportable Tempo worklog period

Or, you can disable the filter by ignoring the period passed and forcing "all times":

// tempo-tool.groovy

// remove this snippet to ignore passed period
if(tempoDateFromRequestParameter && tempoDateToRequestParameter) {
	tempoDateFrom = tempoDateFromRequestParameter
	tempoDateTo = tempoDateToRequestParameter
}
Configuring the user filter for Tempo worklogs

Since app version 6.2.0, the tempo-tool.groovy script can export the worklogs of only one specific user if the username is passed in a request parameter.

The username is available in Tempo contexts (like in the Timesheet screen), but not available in others. Again, this is simply because the user selector is available only in Tempo contexts.

You may want to disable this filtering also in Tempo contexts, in order to export the worklogs for all users. The most typical use case example is creating a monthly report that accumulates the work of every team member. To disable the filtering, set this configuration variable to true:

// tempo-tool.groovy

def exportWorklogsOfAllUsers = false
Configuring pre-loading for Tempo worklogs

Since app version 6.2.0, tempo-tool.groovy script supports two loading strategies: "pre-load worklogs for all issues" vs. "load worklogs for each issue separately".

In our profiling, the former works faster for larger number of issues, i.e. when we expect a larger number of worklogs to be returned. These requests can be served faster if all the worklogs in the period are downloaded with a single Tempo API call (instead of one Tempo API call per issue).

There is a potential danger to consider! If you have a large number of issues and the period is "all times" (or very long), then pre-loading can generate heavy load on Tempo. Therefore, by default pre-loading is used only if there are more than 10 issues to export and the period is not "all times" (but some specific start and end date)!

This is the expression in tempo-tool.groovy that captures the default decision logic, allowing to change the value of 10 issues:

preloadWorklogs = (issues.size() > 10) && !exportWorklogsOfAllTimes

If you are not worried about longer periods and want to make it depend only on the issue count, you can reduce the decision to this:

preloadWorklogs = (issues.size() > 10)

Or, you can enforce pre-loading (in every case) by deleting the right-side expression and setting the variable to true:

preloadWorklogs = true
Configuring the Tempo servlet request details

If you wanted to change the low-level details of invoking the Tempo servlet, you can do that by editing the tempo-tool.groovy script. The script itself is short and very easy to understand. You can change the servlet's URL by editing this line, for instance:

def url = "${baseUrl}/plugins/servlet/tempo-getWorklog/?dateFrom=${dateFrom}&dateTo=${dateTo}&format=xml&addBillingInfo=true&addUserDetails=true&tempoApiToken=${apiToken}"

Learn more about Tempo Timesheets

Zephyr

(supported since Better PDF Exporter 5.5.0)

Zephyr is the most popular test management solution for the Jira platform.

Watch this short video to get the gist of exporting Zephyr tests to PDF documents:

Integration features
  • You can export the Test steps custom field type. As Zephyr tests are regular Jira issues, this enables creating self-containing exports from Zephyr tests with all their details from field values (test details), through attachments (test data) and comments, to test steps (instructions).
  • You can export the test executions for any test. Executions are exported with their (customizable) details for a comprehensive report: test cycle, version, status, defects, executor user and execution date.
  • You can export the test step results of the test executions for detailed test reports. In this case, the following (customizable) details are exported for each step: status, defects, comments and execution date.
Export samples

See the sample files exported from Zephyr (in the Template Gallery).

Configuration

Installing ZAPI

Please note that the Zephyr app itself does not expose any public API. Instead, there exists a separate app called ZAPI (also developed by the Zephyr team) to provide a REST API for Zephyr tests, test executions and so.

The Zephyr and Better PDF Exporter integration relies on the REST API provided by ZAPI. Therefore, please install ZAPI as the starting step. (Note: ZAPI is free since version 2.7.1.27107787. Before that, it was a paid app, but even if you need to use an older ZAPI version, a free trial license will be sufficient for evaluation purposes.)

Configuring the PDF templates for Zephyr

The template issue-fo.vm contains the following three configuration parameters in its top part, to enable these features:

## Zephyr
#set($exportZephyrTestSteps = false) ## set to "true" to export Zephyr test steps
#set($exportZephyrTestExecutions = false) ## set to "true" to export Zephyr test executions
#set($exportZephyrTestExecutionDetails = false) ## set to "true" to export Zephyr test step results (only used if $exportZephyrTestExecutions is also true)

For efficiency reasons, the Zephyr REST calls are made only for the issues with the "Test" type. This is a reasonable default and saves quite some computing time in most cases. If you like, you can alter this filtering logic by modifying this line in issue-fo.vm:

## Zephyr test steps
#if($issue.issueTypeObject.name == "Test")
	## ...
Configuring the REST API for Zephyr

As this integration relies on the Zephyr REST API, you need to configure the login credentials of a valid Jira user account for the REST API calls. Please set the username and password to these configuration variables in issue-fo.vm:

## Jira user credentials for REST API calls
#set($restUserName = "admin") ## Jira username for REST authentication
#set($restPassword = "admin") ## Jira password for REST authentication

Don't worry about using plain text passwords: this file is visible only for Jira administrators, who would have super-user permissions any way. Also note that if you are using multiple REST API based integrations in the same template (ex: Gliffy plus Zephyr), then all REST API will be used with the same user credentials.

As a good practice, this is safer to avoid usernames and passwords that contain non-English characters. Albeit our Zephyr script correctly encodes international usernames and passwords, their handling also depends on the configuration of the container that hosts your Jira web application (typically Tomcat). If you're having difficulties, just replace those characters in your username or password with English letters or numbers.

Why do all REST API calls result in "Server returned HTTP response code: 403" or "401" error?

First off, be 101% sure that the REST username and password are correct. If those are, but you are still receiving 403's, please open Jira in your browser, logout and login with the same user account which you configured for the REST calls. You will be asked for a CAPTCHA verification, but after answering that and logging in to Jira, the REST calls will also be successfully executed!

Why does this happen? As its default behavior, Jira will lock your account and present a CAPTCHA on the login form after a few (3 - 5) unsuccessful login attempts. Since the Zephyr integration may send several REST API requests per export, the unsuccessful login attempts limit can be reached very quickly if the password is wrong. To resolve this: you just have to pass the CAPTHCA verification, that's it.

Please note that it will never happen again, unless you change the password of the corresponding Jira user account.

If you are an administrator, there is also a quicker solution: go to Administration → User management and clear the failed login attempts counter with one click.

Tip: you can increase the allowed login attempts or even disable this feature altogether in Jira.

Learn more about Zephyr