Customizing PDF Exports

In this page

Customizing PDF content, look and layout

Overview

PDF document content, look and page layout is defined by PDF template files named something-fo.vm. (There can be any number of these, but more on that later.)

The -fo.vm suffix denotes that these files are Velocity / FO templates. It means that those are a plain text file written in the Velocity template language, which is then transformed into FO documents, which is finally transformed to PDF. See more about this process in the next section.

Although both of those languages are very easy to grasp without any further reading, you may want to familiarize yourself with the basics of the Velocity template language syntax and the FO syntax. Where to start?

1. You can probably learn most just by looking at the sample template files shipped with the app. Not only they are useful as is, they can also be great starting points to develop totally new templates.
2. The best documentation available on the simple, yet powerful Velocity language is the Velocity User Guide. It is illustrated with great examples.
3. Various XSL-FO tutorials are available on the web (just Google for "xsl fo tutorial"). Start with reading this tutorial if you want to pick up the FO basics quickly.

Editing PDF templates

PDF templates are editable through a convenient web based management interface, called the Template Manager. Go to Apps → Manage your apps → PDF Templates to see the filelist. Please note that it includes not only templates, but also Groovy scripts and other resources available for the PDF renderer.

Click any of the filenames to edit it right in your browser! The editor allows modifying the filename and the description of the file, and edit its actual content. It comes with syntax highlighting, line numbering and other convenience features you would expect from a code editor.

The PDF file rendering process

The two-stage PDF rendering process works like this:

1. First, issue-fo.vm is rendered through Apache Velocity: it iterates over the issues, replaces the variable references (like $issue.description or $issue.resolutionObject.name) by their actual values, executes scripts and so on. The result of this stage is a temporary in-memory FO document.
2. Then, the resulted FO document is transformed into PDF by Apache FOP. The result is the actual final PDF document.

The rendering context

The rendering context is the set of variables and tools you can use in your PDF templates and in your Groovy scripts (optional, see this later). Every item in the context is identified by a unique name, just like a variable in a programming language. For example, the issues to be exported are available under the name $issues.

Velocity objects for templates

You can access the following domain objects while rendering the PDF template:

You are, of course, not limited to using these objects only. You can access tons of other information by navigating from these starting points in the object graph.

You can, for instance, retrieve the enclosing project and its latest version with the following Velocity code:

#if($issues.size() != 0)
	#set($project = $issues.get(0).projectObject)
	#if($project.versions.size() != 0)
		#set($lastVersionIndex = $project.versions.size() - 1)
		#set($version = $project.versions.get($lastVersionIndex))
	#end
#end

Velocity tools for templates

You can use the following tools in PDF templates:

def changeHistories = changeHistoryManager.getChangeHistoriesForUser(issue, user)

def comments = commentManager.getCommentsForUser(issue, user)

#set($avatarService = $componentAccessor.avatarService)
#set($applicationProperties = $componentAccessor.applicationProperties)
#set($constantsManager = $componentAccessor.constantsManager)
#set($projectManager = $componentAccessor.projectManager)
#set($userManager = $componentAccessor.userManager)
## ...

#set($customFields = $customFieldManager.getCustomFieldObjects($issue))

#if($fieldVisibilityManager.isFieldVisible('versions', $issue)) ... #end

def linkCollection = issueLinkManager.getLinkCollection(issue, user)

#set($issues = $jqlSearch.searchByJql("project = FOO"))
#set($issues = $jqlSearch.searchBySavedFilter(10000))

#set($remoteIssueLinks = $remoteIssueLinkManager.getRemoteIssueLinksForIssue($issue))

#set($thumbnails = $thumbnailManager.getThumbnails($issue, $user))

#set($users = $userManager.getUserByAccountId(1))
#set($users = $userManager.getUsersByAccountId([1, 2]))
#set($users = $userManager.getAllApplicationUsers())

#set($worklogs = $worklogManager.getByIssue($issue))

#set($percentage = $workRatio.getWorkRatio($issue))

$date.format("yyyy-'W'ww-EEE", $currentDate)

$include.parse($ctx, "your-company-header-fo.vm")

#set($totalTimeSpent = $math.add($totalTimeSpent, $worklog.timeSpent))

$number.format("integer", $storyPoints)

#foreach($issue in $sorter.sort($issues, "key"))
	<fo:block>$xmlutils.escape($issue.summary)</fo:block>
#end

#set($headingLevel = $stringutils.countMatches($issue.summary, "."))

#set($comments = $pdfContent.commentsByIssue($issue))

#set($changeHistories = $pdfContent.changeHistoriesByIssue($issue))

$pdfFormatter.formatFileSize($attachment.filesize)

$pdfFormatter.formatCalendarDuration($issue.timeSpent)

$pdfFormatter.formatDuration($issue.timeSpent)

$pdfRenderer.asRendered($issue, 'description', $issue.description)

$scripting.execute("hello-world.groovy")

$userDateTimeFormatter.withStyle($dateTimeStyle.COMPLETE).format($currentDate)

Expressions for templates

These are the best resources to find the template language expressions for your own templates:

1. The Expressions Reference Manual gives you categorized expressions for all the frequent needs, that you can just copy to your own templates.
2. The code of the default templates shipped with the app are also worth a deeper look. We offer several templates built for real-life use cases, so make sure to check the default templates that export the same data or work similar to your own templates.

Embedding images and issue attachments in the PDFs

Embedding external images

In short: images are fully supported. You will use the <fo:external-graphic> element, which supports every sort of resizing options.

This code snippet will give you an idea, or will even do the job for you in most of the cases:

<fo:external-graphic width="100%" height="100%" content-width="scale-to-fit" content-height="100%" src="url('https://www.midori-global.com/images/midori_logo.gif')"/>

For more information about the parameters, please see the tons of great tutorials available on the web.

Embedding images attached to issues

The default issue-fo.vm template differentiates between image attachments and non-image attachments. For the former, it displays the thumbnails. For the latter, it simply prints the filenames and file sizes.

In certain applications, you might rather want the image thumbnails not to be shown in the PDF. This is easy: just set the $exportThumbnails option to false in the template.

Embedding all types of files attached to issues

In some cases, you may want to embed all the files attached to the exported issues in the PDF, not only the images.

This is also supported! It makes your PDFs real self-containing units of information. Please read the embedding issue attachments page for details.

Implementing custom logic with Groovy scripting

Some document types need more logic than just simple if-then statements. You may want to, for instance:

• Draw charts. (Ex: generate graphical visualization in project status reports.)
• Integrate with external resources. (Ex: integrate vendor information into your quotes queried from an external webservice.)
• Do precise arithmetic. (Ex: calculate precise money values in invoice documents.)
• Access Jira internals. (Ex: execute a secondary saved filter to collect more data.)
• Implement data processing algorithms using advanced data structures. (Ex: build dependency tables for traceability matrixes.)

To implement these you can easily write Groovy scripts and execute those scripts while generating the final PDF document! Please read the scripting to implement custom logic page.

Rendering charts

Charts are visual representations of Jira data. Charts often make it easier to understand the data in business reports, because readers can easily pick out patterns and trends illustrated in the charts that are otherwise difficult to see when looking at raw numbers.

A detailed, yet easy to follow tutorial that will explains how to collect data for charts, how to customize the look of charts and how to insert them to the final PDF documents is available here.

Next step

Run short Groovy scripts to integrate data from external resources, to access Jira internals (ex: getting project or version metadata) or to pre-process data before exporting that to PDF.

Questions?

Ask us any time.