In this page

Configuring PDF templates via configuration variables

Many of the templates shipped with Better PDF Exporter offer configurability via variables. These variables appear in the top part of the PDF templates or in the top part of the Groovy scripts.

For instance, the Gantt chart template (gantt-chart-fo.vm) offers the following configuration variables: 

#set($showCurrentTime = true)					## whether to highlight the current week or day
#set($startDateCustomFieldId = 10400)			## should be a date picker type custom field
#set($endDateCustomFieldId = 10401)				## should be a date picker type custom field
## ...

Some variables are required by the template to work correctly (e.g. the Tempo Timesheets authentication token for Tempo Timesheets exports), while others modify the PDF result's look or behavior (e.g. whether to export sub-tasks). The variables are quick-documented right in code comments, but are also documented below with more details.

You can edit the configuration variables intuitively:

  1. Login to Jira as administrator.
  2. Go to Apps → Manage your apps → PDF Templates.
  3. Click the template file you wanted to edit, for example gantt-chart-fo.vm. It opens in the built-in template editor.
  4. Edit the variables.
  5. Save your changes.
  6. Create a new export, which will reflect the changes in the configuration variables.

What is the "demo mode"?

Some of the templates shipped with the app must be configured to produce a meaningful PDF result. For example, a meaningful Gantt chart cannot be rendered without setting up the ID's of the two custom fields that supply the start- and end dates for the tasks.

Because users want to understand the value in a PDF template without configuring it, these templates support the special "demo mode". In the demo mode, the data required by the template is supplied from an alternative source. For example, the Gantt chart takes the start date from the issue's creation date and the end date from the issue's last modification date. Although it does not make any sense semantically, these date values are guaranteed to be there and they help to give a feel of the expected output without any configuration.

How to activate or de-activate the demo mode?

You don't have to anything actually:

  • When the template detects that the necessary configuration is not done yet (i.e. when the required configuration variables are left blank or zero), it turns to demo mode automatically.
  • As soon as you you assign actual values to the configuration variables, it exists the demo mode and starts using the configured values.

When the template is in demo mode, it indicates it with a red warning text in the PDF result.

Template configuration variables

This section walks through the configuration variables in each template. (Those templates that don't support any configuration variable are omitted.)

gantt-chart-fo.vm

Configuration variable Description
$startDateCustomFieldId ID of the custom field that represents the start date. It should be a "Date Picker" type custom field.
$endDateCustomFieldId ID of the custom field that represents the end date. It should be a "Date Picker" type custom field.
$progressPercentageCustomFieldId ID of the custom field that represents the percentage. It should be a "Number" type custom field. Alternatively, set it to 0 to calculate the progress from the start date, the end date and the current date. Or, set it to -1 to hide the "Progress" column.
$viewPeriod Granularity of the time axis. Use one of "auto", "week" or "day". "auto" will automatically select between "week" and "day" depending on the difference between the earliest start date and latest end date.
$showCurrentTime Defines if the current time should be shown. Use one of "true" or "false".
$groupSubTasksByParent Whether sub-tasks should be rendered right after their parent. Set it to "true" to enforce sub-tasks appear after their parents regardless the order they appear in the input issues. Set it to "false" to strictly follow the original order (i.e. allow parents and sub-tasks appear "detached").
$startAutoPagingAt When issue count is equal to or greater than this, the template will start auto-paging for better performance.
$rowsPerPage Number of rows per page during auto-paging (also see $startAutoPagingAt).

issue-fo.vm

Configuration variable Description
$maxIssues Upper limit for the issues to be exported. If you have 800 issues while this variable is set to 500, the last 300 will be skipped.
$startIssuesOnNewPages Controls if a page break is added before each issue.
$exportProjectAvatars Controls if the project avatars are exported for each issue.
$exportThumbnails Controls if the thumbnails of the image type attachments are exported.
$exportChangeHistory Controls if the issue field change history is exported.
$exportSubTasks Controls if sub-tasks are exported exactly the same way as top-level issues. If it is set to "false", then sub-tasks are exported as a list at their parent issue's details. If it is set to "true", then all details of the sub-task is exported, each sub-task appearing on a new page.
$exportAllCustomFields Controls if all custom fields are exported, or only the visible ones.
$excludedCustomFieldTypeKeys Comma separated list of the custom field type keys to be excluded from the export. It should be used to exclude those field types that don't carry information valuable in the export (e.g. the lexo-rank).
$excludedCustomFieldIds Comma separated list the ID's of the custom fields to be excluded from the export.
$embedAttachments Controls if binary file attachments are included in the PDF document.
$embeddedAttachmentMaxFileSize Maximum filesize (in bytes) for attachments to be embedded (default: 50M). If a file is larger than this, it will not be embedded.
$exportServiceDeskApprovalDecisions Control if each approver decision or only the final decision is exported for Jira Service Management "Approvals" custom fields.
$tempoApiToken, $tempoDateFrom, etc. See the Tempo Timesheet integration documentation.

issue-navigator-fo.vm

Configuration variable Description
$startAutoPagingAt When issue count is equal to or greater than this, the template will start auto-paging for better performance.
$rowsPerPage Number of rows per page during auto-paging (also see $startAutoPagingAt).
$excludedCustomFieldTypeKeys Comma separated list of the custom field type keys to be excluded from the export. It should be used to exclude those field types that don't carry information valuable in the export (e.g. the lexo-rank).

project-report-fo.vm

Configuration variable Description
$startDateCustomFieldId ID of the custom field that represents the start date. It should be a "Date Picker" type custom field.
$endDateCustomFieldId ID of the custom field that represents the end date. It should be a "Date Picker" type custom field.
$periodLength Length of the reported period in days. Use 7 for weekly reports, or 30 for monthly reports.

release-notes-fo.vm

Configuration variable Description
$useFirstFixVersion Selects the version for which the release notes are generated fo Set it to "true" to use the first "fix version" of the first issue, or to "false" to use the latest version of the project that contains the first issue.

requirements-specification-fo.vm

Configuration variable Description
$headingNumberCustomFieldId ID of the custom field that stores the requirement heading numbers (e.g. "1.4.2.2"). It should be a Text type custom field.
Note that heading numbers define the hierarchy of requirements, consequently if you don't configure this, it will be a flat list of requirements.
$uppercaseTopLevelRequirements Whether top-level requirement names should be written in uppercase. Use it only if the $headingNumberCustomFieldId is configured, otherwise all requirements are considered top-level.
$startAutoPagingAt When issue count is equal to or greater than this, the template will start auto-paging for better performance.
$rowsPerPage Number of rows per page during auto-paging (also see $startAutoPagingAt).

story-card-fo.vm

Configuration variable Description
$storyPointsCustomFieldID ID of the "Story Points" field managed by Jira Software. Alternatively, the ID of any Number type custom field (if Jira Software is not used or you want to supply story point values from another custom field).
$cardsPerRow Number of cards to be shown in a row. The physical size of one card is defined by this variable together, $rowsPerPaper and the paper size.
$rowsPerPaper Number of rows to be shown on a single page.
$markerStyle Line style of the crop marks. The crop marks guide your cutter or scissors when cutting the printed paper to individual cards.

time-by-x-report-fo.vm

Configuration variable Description
$fieldId The ID of the field that is the basis for the report. It can be one of "status", "assignee" or "customfield_12345" (where 12345 is the numeric ID of the desired custom field). (Make sure that you enter this all lowercase!)
Note that custom field values are converted to strings, therefore most custom field types work out of the box. (Tip: if you want to add support for a new field, this is fairly trivial to do, just look at time-by-x-report.groovy.)
$prettyPrint Whether time values should be formatted as "2h 15m 2s" (instead of the decimal format "2.25h").
$timelineChartBarHeightMeasureFactor The height of the timeline chart grows dynamically based on the number of changes. This variable controls the height of each horizontal bar of the timeline.
$maxIssues Upper limit for the issues to be exported. If you have 800 issues while this variable is set to 500, the last 300 will be skipped.
$startIssuesOnNewPages Controls if a page break is added before each issue.
$exportProjectAvatars Controls if project avatars are exported for each issue.

timesheet-invoice-fo.vm

Configuration variable Description
$isInvoice Controls the export type. Set it to "false" to export a timesheet, which does not include monetary information. Set it to "true" to export a time-based invoice, which includes line price, total price, tax and others in addition to time values.
$documentNumber Identifier for document (i.e. the timesheet identifier or the invoice number). Defaults to the document title (which itself defaults to the issue key or the saved filter's name).
$logoUrl URL for the (company) logo. Comment this out to hide the logo.
$paymentTermsDays Number of calendar days from invoice creation to the due date. Comment this out to hide "Payment Due Date".
$providerName Name of the invoice provider.
$providerAddressLine1
$providerAddressLine2
$providerAddressLine3
 Address of the invoice provider.
$customerName Name of the invoice customer.
$customerAddressLine1
$customerAddressLine2
$customerAddressLine3
 Address of the invoice customer.
$hourlyRate Hourly rate. Comment this out to hide the "Amount" column.
$currency Currency of the invoice.
$taxPercentage Percentage of VAT to be added (ex: 7.75%). Comment this out to hide "Tax".
$notes Additional notes at the end of the document. Defaults to the filter's description.
$tempoApiToken, $tempoDateFrom, etc. See the Tempo Timesheet integration documentation.

Questions?

Ask us any time.