In this page

Integration with other Jira apps
Automation Lite for Jira
Integration features
Configuration
Learn more about Automation Lite for Jira
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
Integration features
Export samples
Configuration
nFeed 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
ScriptRunner
Integration features
Configuration
Learn more about ScriptRunner
Table Grid Editor
Integration features
Export samples
Configuration
Learn more about Table Grid Editor
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

Automation Lite for Jira is a flexible automation app for Jira (similar to the IFTTT or Zapier services). (supported since Better PDF Exporter 3.1.0)

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 Send PDF in email, Save PDF to the file system and Attach PDF to an issue actions to email, export and attach PDF documents from Jira at regular intervals (periodic job) or at issue events (issue created, updated, assigned, etc.)

Configuration

Read the automation tutorial for a complete how-to.

Learn more about Automation Lite for Jira

See the Automation Lite for Jira page (at its own vendor).

Gliffy

Gliffy is a powerful app to create diagrams and wireframes for Jira issues. (supported since Better PDF Exporter 5.3.0)

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 Template Gallery for sample files exported from Gliffy.

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

See the Gliffy page (at its own vendor).

Insight

Insight is the leading asset management app for Jira, that allows implementing CMDB, CRM, HR, ITSM or ITIL functionality on the Jira platform. (supported since Better PDF Exporter 5.9.0)

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

Integration features

  • You can export all Insight-specific 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 Template Gallery for sample files exported from Insight.

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

See the Insight page (at its own vendor).

JEditor (Jira Editor)

JEditor is a hyper-popular WYSIWYG rich text editor app for Jira. (supported since Better PDF Exporter 3.3.0)

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 Template Gallery for sample files exported from JEditor (Jira Editor).

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)

See the JEditor (Jira Editor) page (at its own vendor).

Jira Service Desk

Jira Service Desk is the de-facto service desk solution running on the top of Jira. (supported since Better PDF Exporter 3.4.0)

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-specific custom field types, like Approvals (including decision details), Customer Request Type, Organizations, Request Participants, Satisfaction, Satisfaction Date, SLA to PDF.

Export samples

See the Template Gallery for sample files exported from Jira Service Desk.

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

## 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 issue-fo.vm and issue-navigator-fo.vm:

## Jira Service Desk 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 Jira Service Desk

See the Jira Service Desk page (at its own vendor).

Jira Software

Jira Software is the Scrum and Kanban solution for Jira. (supported since Better PDF Exporter 3.4.0)

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 issues in a sprint or in the backlog), Scrum Board and Kanban Board views (with all issues in a column). (supported since Better PDF Exporter 4.0.0)
  • You can export the Jira Software-specific custom field types, like Sprint, Epic, Story Points, etc., 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 Template Gallery for sample files exported from Jira Software.

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 templates' 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

See the Jira Software page (at its own vendor).

nFeed

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

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

Integration features

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

Export samples

See the Template Gallery for sample files exported from nFeed.

Configuration

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

nFeed 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

See the nFeed page (at its own vendor).

ScriptRunner

ScriptRunner is the most powerful tool to implement every kind of custom logic, expressed as Groovy scripts, in Jira. (supported since Better PDF Exporter 3.1.0)

This short tutorial video shows you how to set up a scripted workflow post-function using ScriptRunner, to generate a PDF document from the transitioned issue and email that:

Integration features

  • The PDF API provided by the Better PDF Exporter app fully supports ScriptRunner. Midori actually recommends Groovy as the generally best choice of language to implement automations and integrations that rely on the PDF API.

Configuration

Read the PDF API tutorial for a complete how-to.

Learn more about ScriptRunner

See the ScriptRunner page (at its own vendor).

Table Grid Editor

Table Grid Editor is a Jira app that extends Jira with list- and spreadsheet-like (table-like) custom fields. (supported since Better PDF Exporter 3.4.0)

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 Template Gallery for sample files exported from Table Grid Editor.

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

See the Table Grid Editor page (at its own vendor).

Tempo Timesheets

Tempo Timesheets is the most widely used time tracking solution for Jira. (supported since Better PDF Exporter 3.4.0)

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-specific 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 Template Gallery for sample files exported from Tempo Timesheets.

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

See the Tempo Timesheets page (at its own vendor).

Zephyr

Zephyr is the most popular test management solution for the Jira platform. (supported since Better PDF Exporter 5.5.0)

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 Template Gallery for sample files exported from Zephyr.

Configuration

Installing ZAPI

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

The Zephyr + Better PDF Exporter integration relies on the REST API provided by ZAPI. Therefore, please install ZAPI with a valid license as the starting step. (Note: ZAPI is a paid app. For evaluation purposes, a free trial license will work, too.)

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

See the Zephyr page (at its own vendor).