Exporting Report Results

Exporting a Report

To export report results, click the Export toolbar dropdown in the top right corner of the page, and then select PDF, CSV or Excel format. A version of the report results in the desired file format will start downloading shortly.

Export File Format Differences

Due to the different nature of each export file type, there are some differences in the format of data included:

File Format Notes

PDF

Produces a professionally-formatted PDF export, including all report charts and data tables. PDF exports can include optionally 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 on your JIRA instance.

An example PDF export is shown below:

CSV

Includes only the tabular data from the web browser-based report results. CSV exports are suitable for batch processing or for importing into other programs that only accept CSV-format files.

In CSV exports, all dates are expressed in the ISO date format as "yyyy-mm-dd". (For example, 2013-07-01 represents July 1, 2013). The character set encoding is always UTF-8.

Excel

Includes only the tabular data from the web browser-based report results.

Dataplane performs a native Excel export in .XLS format, which makes it the preferred choice for exporting to most spreadsheet applications.

Excel exports have the following advantages over CSV exports and over JIRA's built-in Excel export from the Issue Navigator:

Any JIRA issue keys in the export are automatically linked back to the corresponding JIRA issue.
Cells are formatted according to their underlying data types. Date fields are automatically exported as dates, number columns are exported as numbers and are right-aligned, and so on. This means that you can start writing Excel formulas and analyzing data immediately, without having to manually convert the cell formats (as you would otherwise need to do with JIRA's Excel export from the Issue Navigator or the CSV export).
Date fields are automatically formatted according to the country selected in the user's JIRA profile (mm/dd/yy, dd/mm/yy, dd.mm.yy, or yyyy/mm/dd, as appropriate).
Column headings are rendered as bold text and the columns are sized proportionately to the column title.
No special character set options are required when cells containing accented characters, Asian language characters, or other non-ASCII characters—it all works automatically

Customizing Exports

Some of the default options for PDF and CSV exports can be customized on a system-wide basis by your JIRA administrator. In addition, additional options for PDF and CSV exports can be customized on a report-by-report basis using Dataplane Customizer Scripts. (At present, no configuration options are available for Excel exports.)

Both the system-wide defaults and the per-report configuration options are described in more detail in this section.

Exporting in PDF Format

Global Defaults

When exporting reports in PDF format, Dataplane references a number of default settings to determine the size, orientation and layout of the file.

A few of these default settings can be customized by a JIRA administrator to provide a global default specific to your organization.

Property	Default	Description
size	letter or A4	The page size for Dataplane PDF exports is determined individually for each user based on the user's JIRA Profile. If a user's JIRA profile language/region is set to the US, Canada or Mexico, the default page size will be "letter" (8.5 inches x 11 inches). For all other regions, the default is "A4" (210 mm x 297 mm).
orientation	portrait	Dataplane uses vertically oriented pages ("portrait") as the default for PDF exports.
background image (corporate letterhead or logo)	none	By default, Dataplane does not add a background image, logo or letterhead to PDF exports. If you wish to set up a default, global background image to customize the look of all Dataplane reports exported by your organization, place an image file named exactly `defaultBackground.png` in the following location on your 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 default background image on all subsequent reports exported from Dataplane. No restart of JIRA or reinstallation of Dataplane is necessary. Per-report background images can also be defined through the use of Dataplane Customizer scripts (see below).
stylesheets	<none>	By default, Dataplane uses its own built-in styling for reports exported to PDF. If you wish to set up a default, global cascading stylesheet to customize the layout of all Dataplane reports exported by your organization, place a cascading stylesheet file named `default.css` in the following location on your 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 subsequent reports exported from Dataplane. No restart of JIRA or reinstallation of Dataplane is necessary.

Customizing the Export

With Dataplane Customizer Scripts, you can also customize the size, orientation, layout and other attributes of your exported PDF files on a report-by-report basis.

If you are not yet familiar with using Customizer Scripts in your reports, read through Customizing Reports with Scripts for some background and then return back here.

Here's the general syntax for a Customizer Script that sets a number of different properties of the PDF export:

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

The words format "pdf" indicate 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 your PDF export customizations on separate lines (still starting with format "pdf"), such as the following:

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

Here is a list of the available properties and values that 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 the section below entitled "Adding a Corporate Letterhead or Logo".
`stylesheet stylesheets`	`"<filename>"("<filename1>", "<filename2>", ...)`	To provide a custom styling for the text, layout, header or footer for the exported report, you may specify one or CSS cascading stylesheets. The stylesheet 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. To add multiple stylesheets, you must still enclose the filename in quotation marks, and the comma-separated list of stylesheets must be enclosed within parenthesis. Any "stylesheet" keyword will automatically replace all previously-listed stylesheets. For example: // Add one styleesheet stylesheet "sheet1.css" // Add multiple stylesheets stylesheets ("sheet1.css", "sheet2.css") For more information on the rules you can use in the CSS stylesheets, see the PDF Export Stylesheet section below.

Adding a Corporate Letterhead or Logo

PDF report exports can be configured to use a custom background image, using either the system-wide default background image, or a report-specific background image defined with a customizer script. Both methods for setting background images are described in the previous sections.

In either case, the background image must be saved in the PNG file format. Depending on the export page size, Arsenale suggests the following dimensions for the background image in order to render the export at a standard print resolution of 300 ppi. Note that Dataplane will automatically select the best page size to use based on the user's profile:

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

If needed, the image you provide will be automatically stretched to fill the entire height of the page, and then the width will be scaled as needed to maintain the proper proportions. This means that horizontal cropping may sometimes occur if your image dimensions are not proportional to the selected page size.

If users will be exporting in both Letter and A4 sizes, Arsenale recommends using the A4 dimensions for your background image in order to avoid unnecessary horizontal cropping.

PDF Export Stylesheets

Dataplane uses the Flying Saucer HTML-to-PDF engine in order to render PDF report exports, and Dataplane supports most standard CSS3 attributes, including selectors for paged media.

Dataplane PDF output is targeted for print media, so when specifying the size of fonts or any other element, you should always use "pt" (points) rather than "px" (pixels) to specify dimensions. One point is always 1/72 of an inch.

For example, use "font-weight: 10pt;" rather than "font-weight: 10px;". The same rule applies for margins, borders, padding, any any other CSS attribute that requires a dimension.

Exporting in CSV Format

Files exported in Comma Separated Value (CSV) format by default use a comma (,) to separate the individual fields on a line.

Customizing the Export

With a Dataplane Customizer Script, you can customize the CSV export on a report-by-report basis.

If you're not yet familiar with using Customizer Scripts in your reports, read through Customizing Reports with Scripts for some background and then return back here to get going.

Here's the general syntax for a Customizer Script that sets a property of the CSV export:

customizeExport {
	format "csv" <property1> <value1> <property2> <value2>
}

The words format "csv" indicate you are customizing the CSV export format, and following that are one or more pairs of properties and their values.

For example:

customizeExport {
	format "csv" separator ";"			// export the file using semi-colons to separate values
}
 
customizeExport {
	format "csv" separator "\t"        	// export the file using tabs to separate values
}

Here's a list of the available properties and values that can be used to customize CSV exports:

Property Values Description

separator

<single character>

Specifies the character to use as a field separator on each line of the file.

Any single character in quotes may be used. Common options are:

"," – comma (default)
";" – semi-colon
":" – colon
"|" – bar
"/" – slash

Use the following special notation to indicate a tab character:

"\t"– tab

Page Contents