In this page

Integration with other JIRA plugins
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 add-on, it also disables the PDF View Plugin
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
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 plugins

This page describes how JIRA PDF View Plugin exports data from, or integrate with popular JIRA plugins.

If a plugin is not mentioned here, it does not mean that it would not work in PDF exports. This page only lists the most important plugins, that are actively used by the PDF View Plugin user community and whose integration is officially supported by Midori.

Automation Lite for JIRA

Automation Lite for JIRA is a flexible automation add-on for JIRA (similar to the IFTTT or Zapier services). (supported since PDF View Plugin 3.1.0)

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

Integration features

  • Better Excel Plugin 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 add-on to create diagrams and wireframes for JIRA issues. (supported since PDF View Plugin 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 add-on for JIRA, that allows implementing CMDB, CRM, HR, ITSM or ITIL functionality on the JIRA platform. (supported since PDF View Plugin 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 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. PDF View Plugin 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 plugin for JIRA. (supported since PDF View Plugin 3.3.0)

Watch this short video to see the JEditor PDF View Plugin integration in action:

Integration features

  • JIRA PDF View Plugin 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. JIRA PDF View Plugin 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 PDF View Plugin 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 PDF View Plugin 4.0.0)
  • You can export the JIRA Service Desk-specific custom field types (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. PDF View Plugin 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 PDF View Plugin 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 PDF View Plugin 4.0.0)
  • You can export the JIRA Software-specific custom field types, like Sprint, Epic, Story Points, etc., to PDF.
  • JIRA PDF View Plugin 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.
  • JIRA PDF View Plugin 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. JIRA PDF View Plugin 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 add-on integrates external data sources (SQL databases, LDAP, Active Directory, REST APIs, Salesforce, CSV files, etc.) to JIRA. (supported since PDF View Plugin 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. JIRA PDF View Plugin will automatically recognize the nFeed managed fields and export them accordingly.

nFeed troubleshooting

When I uninstall or disable the nFeed add-on, it also disables the PDF View Plugin

This is a very infrequent and random problem, which is deeply rooted in JIRA's OSGi component dependency management. Solution: simply re-enable the PDF View Plugin (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 the PDF View Plugin 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 PDF View Plugin 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 JIRA PDF View Plugin 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 plugin that extends JIRA with list- and spreadsheet-like (table-like) custom fields. (supported since PDF View Plugin 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. JIRA PDF View Plugin 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 PDF View Plugin 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 PDF View Plugin 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.
  • JIRA PDF View Plugin 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. JIRA PDF View Plugin 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 are several straightforward configuration parameters in the top part of the issue-fo.vm template. You can use these to specify the worklog export period (this is basically set to "unlimited" by default) or filter the worklogs for the current user:

#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
#set($tempoFilterByUser = false)       ## set to "true" to export the Tempo worklogs of the current user only, or "false" to export everyone's
In addition to these, timesheet-fo.vm allows looking up the customer from Tempo, exporting the custom worklog attributes, and filtering the worklogs by their attributes (ex: non-billable):
#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

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/?issueKey=${issueKey}&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 PDF View Plugin 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 add-on itself does not expose any public API. Instead, there exists a separate add-on called ZAPI (developer by the Zephyr team), to provide a REST API for Zephyr tests, test executions and so.

The Zephyr + PDF View Plugin 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 add-on. 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).