Exporting Results to PDF

Overview

The Export » PDF Format option produces a professionally-formatted PDF export, including all report charts and data tables. PDF exports can optionally include custom corporate letterhead or logos, as well as various other options that are described in the following sections.

Projects, users and issue keys are automatically linked back to the corresponding object in your Jira instance.

The Export menu within a report permits the export of a single report at a time. An example PDF export is shown below:

 

To export multiple Dataplane reports into a single PDF file, arrange the desired reports as Dataplane gadgets on a Jira dashboard, and then follow the instructions in Exporting Jira Dashboards to PDF.

PDF exports can be customized in a number of ways by the system administrator, as well as by users who have Customizer Script permission.

Global Default Settings

When exporting reports in PDF format, the following default settings are used for the size, orientation and layout of the PDF file. Where noted, some settings can be customized on a global basis by a Jira administrator.

Property Default Description
page size

letter or A4

The default page size for report exports is user-specific, based on the user's Jira user profile language/region setting.

If a user's language/region is US, Canada or Mexico, the default page size is "letter" (8.5 inches x 11 inches).

For all other user language/region settings, the default page size is "A4" (210 mm x 297 mm).

This default can be modified on a report-by-report basis using Dataplane Customizer Scripts.

page orientation

portrait

Dataplane defaults to vertically-oriented ("portrait") pages for PDF exports.

This default can be modified on a report-by-report basis using Dataplane Customizer Scripts.

background image (letterhead or logo)

none

By default, Dataplane does not add a background image, logo or letterhead to PDF exports.

To add a custom, global background image to all exported Dataplane reports, place an image file named exactly defaultBackground.png in the following location on the Jira server:

<JIRA_DATA>/dataplane/export/defaultBackground.png

(where <JIRA_DATA> is the path to your Jira data directory, not your Jira application install directory)

If this file is present, it will be used as a background image on all exported Dataplane reports. No restart of Jira or reinstallation of Dataplane is necessary.

Report-specific background images can be defined using Dataplane Customizer Scripts.

stylesheets <none>

By default, Dataplane uses its own, built-in cascading style sheet (CSS) for formatting exported PDF reports.

To add a custom, global stylesheet to all exported Dataplane reports, place a CSS file named exactly default.css in the following location on the Jira server:

<JIRA_DATA>/dataplane/export/default.css

(where <JIRA_DATA> is the path to your Jira data directory, not your Jira application install directory)

If this file is present, it will be included as a stylesheet on all exported Dataplane reports. No restart of Jira or reinstallation of Dataplane is necessary.

Additional report-specific stylesheets can be defined using Dataplane Customizer Scripts.

Customizing Individual Reports

Using a Customizer Script

With Dataplane Customizer Scripts, you can customize the size, orientation, layout and other attributes of an individual report's PDF export.

If you are not yet familiar with using Dataplane Customizer Scripts in your reports, first see Customizing Reports with Scripts for background information.

The following Customizer Script syntax is used to modify the properties of a report's PDF export:

customizeExport {
	format "pdf" [properties...]
}

The format"pdf" indicates that you are customizing the PDF export format, and it is followed by one or more pairs of properties and values.

For example, to create a wide-format landscape page for a multi-column Issues Work Log Table Report, you could use the following:

customizeExport {
	format "pdf" size "ledger" orientation "landscape" backgroundImage "ourLogo.png"
}

You can also place each PDF export customization on a separate line, as in the following:

customizeExport {
	format "pdf" size "ledger"
    format "pdf" orientation "landscape"
    format "pdf" backgroundImage "ourLogo.png"
}

Customizer Script Options

Using a Dataplane Customizer Script, the following properties and values can be used to customize PDF exports:

Property Values Description
size

"letter"
"legal"
"ledger"
"A3"
"A4"
"A5"
"B4"
"B5"

Specifies the output page size for the PDF file.

orientation

"portrait"
"landscape"

Selects whether the longest edge of the page is on the vertical ("portrait") or horizontal ("landscape").
backgroundImage

"<filename>"

To add a logo or letterhead to your report, you may specify an image file (of format .png or .jpg) to use as a background for the exported report.

This file must be placed in the following directory on your Jira server by your Jira administrator:

<JIRA_DATA>/dataplane/export/<filename> 

(where <JIRA_DATA> is the path to your Jira data directory)

Only a simple filename may be used. Any paths are ignored. For details on the required format of the background image, see Adding Background Images.

stylesheet

stylesheets

"<filename>"

("<filename1>", "<filename2>", ...) 

To provide custom styling for the exported report text, layout, header or footer, specify one or more cascading style sheets (CSS) to be used.

The stylesheets must be placed in the following directory on your Jira server:

<JIRA_DATA>/dataplane/export/<filename>

(where <JIRA_DATA> is the path to your Jira data directory)

Only simple filenames may be used. Any paths will be ignored.

To add a single stylesheet, simply enclose the filename in quotation marks. For multiple stylesheets, add parentheses around a comma-separated list of quoted stylesheet filenames.

For example:

// Add one stylesheet
stylesheet "sheet1.css"
 
// Add multiple stylesheets
stylesheets ("sheet1.css", "sheet2.css")

Only one "stylesheet" or "stylesheets" keyword may be used per Customizer Script. Any additional "stylesheet(s)" keywords will replace all previously-listed stylesheets.

For more information on stylesheet rules and options see Customization Guidelines and Tips.


Customization Guidelines and Tips

Using Stylesheets

Dataplane uses the Flying Saucer HTML-to-PDF engine in order to render PDF report exports.

The format of PDF exports can be customized by adding one or more cascading style sheets (CSS), which can be specified at a global level or on a report-by-report basis. For custom stylesheets, Dataplane supports most standard CSS 2.1 attributes, including paged media selectors.

See the Flying Saucer User's Guide for details on document formatting options using CSS.

Stylesheet Dimension Units

Dataplane PDF report exports are targeted for print media, so when specifying the size of fonts and other document elements, always use units of points ("pt") rather than pixels ("px"). One point equals 1/72 of an inch.

For example, use "font-weight: 10pt;" rather than "font-weight: 10px;"

The same rule applies for margins, borders, padding and any other CSS attribute that requires a dimension.

Adding Background Images

To add custom letterhead or a watermark to your reports, PDF report exports can be configured to use a background image.

The background image can be defined either as a global background image used on all reports exported by Dataplane users, or as a report-specific background image defined with a Dataplane Customizer Script. Both methods for setting background images are described in the previous sections.

Background images must be in the PNG file format.

We suggest the following background image dimensions in order to render the export at a standard print resolution of 300 ppi:

Export Page Size Image Width Image Height
Letter (8.5 x 11) 2550 px 3300 px
A4 (210 mm x 297 mm) 2480 px 3507 px

The default PDF report export page size is user-specific, based on the language/region setting in the user's Jira profile.

Background image height is automatically stretched to fill the full page height. Background image width is scaled, as needed, to maintain proper proportions. As a result, horizontal cropping may sometimes occur if your image dimensions are not proportional to the selected page size.

If you wish to export reports in both Letter and A4 sizes, use the A4 dimensions for your background image in order to avoid unnecessary horizontal cropping.

Page Contents