In this page

PDF document properties

The app generates a sensible default title and default filename for each output PDF document. You can optionally override one or both of those via the template. This offers an easy way to generate consistent document properties.

How is the title used? Well, it is completely up to the template. Most typically, the title is displayed in the top part, in the header, in some cover page, or the template may not use it at all.

How is the filename used? It will be offered as the default filename when downloading and saving the PDF document from the browser. Therefore, properly defining the filename via the template can eliminate the need for tedious file renames.

Default title

The default title is generated according to the following logic:

  • "issue key" for single issues (e.g. "FOO-123")
  • "search request name" for saved filters with a name (e.g. "Team Alpha Pending Tickets")
  • "PDF view name (Jira title)" for ad-hoc searches without a name (e.g. "Worklog Report (ACME Jira)")

Customizing titles

To override the title for the generated PDF document, just assign a string to the context variable title any time during the rendering process. Please note that this variable originally contains the default title, allowing you to set the final title based on the default one. (Please see the scripting tutorial for executing scripts and defining context variables.)

You can set it in two ways:

  1. In the Velocity template: 

    #set($title = "${project.name} ${version.name} Release Notes")

    This will set the title to "MongoDB 1.2.0-beta Release Notes", for example.

  2. Alternatively, you can also do this in Groovy: 

    // "title" is a standard Java String, not a GString
title = "North American Revenues - ${new Date().format('yyyy MMM')}".toString()

    This will set the title to "North American Revenues - 2016 Nov", for example.

Default filename

The default filename is simply the title plus the ".pdf" file extension, e.g. "FOO-123.pdf" or "Team Alpha Pending Tickets.pdf".

Customizing filenames

Similarly to the title, to override the filename, just assign a string to the context variable filename. You can do this any time during the rendering process.

You can set it in two ways:

  1. In the Velocity template: 

    #set($filename = "${project.name}-${version.name}-release-notes.pdf")

    This will result in "MongoDB-1.2.0-beta-release-notes.pdf", for example.

  2. Alternatively, you can also do this in Groovy: 

    // "filename" is a standard Java String, not a GString
filename = "north-american-revenues-${new Date().format('yyyy-MM')}.pdf".toString()

    This will result in "north-american-revenues-2012-11.pdf", for example.

Customizing PDF metadata

Better PDF Exporter for Jira enables you to set PDF/A metadata for your PDF documents.

Metadata is information about the document itself, like its author, original title and abstract. This is particularly useful when storing these files in a Document Management system, indexing them in some search application or using them in process automation.

You can set the metadata in your template simply: 

<dc:title>$xmlutils.escape($title)</dc:title>
<dc:creator>$xmlutils.escape($user.displayName)</dc:creator>
<dc:description>Issues exported from Jira</dc:description>

As the definition of metadata is a core part of your document template, you allowed to do anything to configure the metadata values that you could to customize real content.

You can check the resulted metadata in Adobe Reader by opening the "Document Properties" dialog:

Configuring paper size and DPI

The FO → PDF conversion settings (like paper size, DPI, font paths and base URLs for relative URLs, etc.) can be configured in the fop-config.xml configuration file. See more information about the options in the original FOP documentation.

Specifying paper size right in the templates

In case you prefer configuring paper size locally in the templates, you can do that trough the attributes of the <simple-page-master> element: 

<fo:layout-master-set>
	<fo:simple-page-master master-name="A6-landscape" page-height="10.5cm" page-width="14.8cm" margin=".6cm">
		<fo:region-body region-name="page-body"/>
	</fo:simple-page-master>
</fo:layout-master-set>

Questions?

Ask us any time.