In this page

Integration with other Jira apps

This page describes how Better PDF Exporter for Jira exports data from, or integrate with popular Jira apps.

If an app is not mentioned here, it does not mean that it would not work in PDF exports. This page only lists the most important apps, that are actively used by the Better PDF Exporter user community and whose integration is officially supported by Midori.

Jira Service Desk

(supported since Better PDF Exporter 0.1.0)

Jira Service Desk is the de-facto service desk solution running on the top of Jira.

Export Jira Service Desk tickets to PDF super-easily! (Although the video below was captured about the app's Server version, the Cloud version is very similar.)

Integration features
  • You can export the Jira Service Desk-managed custom field types, like Approvals (including decision details), Customer Request Type, Organizations, Request Language, Request Participants, Satisfaction, Satisfaction Date, SLA to PDF.
Export samples

See the sample files exported from Jira Service Desk (in the Template Gallery).

Configuration

Exporting Jira Service Desk custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Jira Service Desk managed fields and export them accordingly.

Configuring the export format for Jira Service Desk custom fields

There is one configuration variable that affects the output format of the Approvals field. The default behaviour is that the overall approval will be exported ("Approved" "Declined", "Pending"). You can also include the individual approvers' decisions by setting this configuration variable in the top part of the issue-fo.vm, issue-navigator-fo.vm and traceability-report-fo.vm templates:

## Jira Service Desk
#set($exportServiceDeskApprovalDecisions = false) ## set to "true" to export approver decisions

If you want full control over the export format, look at the Velocity macro definition marked with this comment in the above mentioned templates:

## Jira Service Desk custom field types
## ...

Note: you can absolutely have different export formats in the different templates, as issue-fo.vm typically has more space for details.

Learn more about Jira Service Desk

Jira Software

(supported since Better PDF Exporter 0.1.0)

Jira Software is the Scrum and Kanban solution for Jira.

Export user stories from the backlog or the board to custom PDF files! (Although the video below was captured about the app's Server version, the Cloud version is very similar.)

Integration features
  • You can export PDF documents directly from the Backlog (with all the issues in a sprint or in the backlog), Scrum Board and Kanban Board views (with all the issues in a column).
  • You can export the Jira Software-managed custom field types, like Sprint, Epic, Story Points, etc., to PDF.
  • You can export the Jira Development Integration app managed custom field called Development (which stores branch, commit and pull request information) to PDF. (coming soon!)
  • Better PDF Exporter offers a Sprint Report template, with Burn Down Chart, Daily Velocity Chart and agile key performance metrics. It can flexibly work from any list of input issues, not strictly belonging to the same Jira Software sprint.
  • Better PDF Exporter also offers a customizable story card template to print physical story cards from any type of Jira issues, also including Jira Software stories. (It works both with and without Jira Software.)
Export samples

See the sample files exported from Jira Software (in the Template Gallery).

Configuration

Exporting Jira Software custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Jira Software managed fields and export them accordingly.

Configuring the PDF templates for Jira Software

The template using Jira Software data, story-card-fo.vm, contain several configuration parameters in their top part. These are are documented right in the template source code.

The most important ones are the IDs of the Jira Software custom fields:

#set($storyPointsCustomFieldID = 10900)

Learn more about Jira Software

Tempo Timesheets

(supported since Better PDF Exporter 1.1.0)

Tempo Timesheets is the most widely used time tracking solution for Jira.

Create customized timesheets or invoices from the Tempo timesheets with one click! (Although the video below was captured about the app's Server version, the Cloud version is very similar. The only major difference is that in the Cloud version you cannot export directly from the Tempo screens, due to a limitation in Atlassian Connect.)

Integration features
  • You can export the Tempo-managed custom field types, like Account, Team, Iteration, etc., to PDF.
  • You can export the Tempo managed worklogs to PDF, along with their custom worklog attributes. You can filter the Tempo worklogs by start date, by end date and by custom worklog attributes. You can exclude the non-billable worklogs and implement other types of custom filtering.
  • Better PDF Exporter also offers a customizable timesheet/invoice template to generate custom timesheets and time-based invoices from Tempo worklogs.
  • Known limitation: you cannot start exports directly from the Tempo screens, because Tempo Cloud does not allow extending its interface by external actions. We will absolutely implement PDF export also for these screens as soon as they support external actions. Note that only the Tempo Cloud team can remove this blocker.
    To indicate its importance:
    1. Please open a ticket in the Tempo support system. Ask for the feature "Support for Better PDF Exporter actions in Tempo Cloud screens" and explain your use case in short. As it takes only 2 minutes of your time, absolutely do this. The more tickets opened with this feature request, the higher probability it will be implemented.
    2. Also, there is a counter-part feature request at Midori. Although the Tempo feature request must be solved first, we use this one to collect feedback and interest on our side. Vote for this by clicking the "thumbs-up" icon, add your use case as a comment and click "Follow". All future updates on this story will be posted there.
Export samples

See the sample files exported from Tempo Timesheets (in the Template Gallery).

Configuration

Exporting Tempo custom fields

There is nothing to do. Better PDF Exporter will automatically recognize the Tempo managed fields and export them accordingly.

Enabling the Tempo Cloud Servlet API

If you want to export Tempo worklogs, PDF templates download those from the Tempo Cloud Servlet API during the document rendering.

Execute these steps to allow the templates to connect to the Tempo servlet:

  1. Login to Jira as administrator.
  2. Go to TempoSettingsExternal Systems Token (under Developer Tools).
  3. Enter a secret string, like "ThisIsMySuperSecret2019", as "Security token". It acts as a sort of password, so keep it secret.
  4. Enter "0.0.0.0-255.255.255.255" to "Allowed addresses", and click to "Add". Note that there is a little bug in the Tempo UI: reload the page if you can't see the value you entered previously. (The PDF renderer runs in the Amazon AWS cloud infrastructure, which assigns varying IP addresses to the renderer. Therefore, allow every IP address here.)
  5. Copy the "Security token" string to the clipboard.
  6. Go to Jira settingsAppsPDF Templates (under Better PDF Exporter).
  7. Open the issue-fo.vm template for editing, uncomment this variable in the top part, and paste the security token from the clipboard to the value:
    ## issue-fo.vm
    
    #set($tempoApiToken = 'ThisIsMySuperSecret2019')
    
  8. Paste the security token similarly to the timesheet-invoice-fo.vm template, as well.
  9. Export a Jira issue having Tempo worklogs with the "PDF" view as a test. You will see java.io.IOException: Server returned HTTP response code: 403 for URL error messages in the exports until the access permissions are properly set up.
Configuring the PDF templates for Tempo worklogs

After you set up the Tempo servlet access, you may want to configure the details of exporting the worklogs.

There is a configuration parameter in the top part of the issue-fo.vm template to filter the worklogs for the current user:

## issue-fo.vm

#set($tempoFilterByUser = false)       ## set to "true" to export the Tempo worklogs of the current user only, or "false" to export everyone's

There are multiple configuration parameters in timesheet-invoice-fo.vm to look up the customer from Tempo, to export the custom worklog attributes, and to filter the worklogs by their worklog attributes (e.g. to skip non-billable worklogs):

## timesheet-invoice-fo.vm

#set($tempoExportCustomer = true)              ## whether to look up the "Customer" from Tempo based on the account set in the first issue to be exported
#set($tempoExportWorklogAttributes = false)    ## whether to display the worklog attributes for each worklog item
#set($tempoExcludeWorklogsWithAttributesContaining = "NonBillable=true")    ## Tempo worklogs with attributes containing this string will be skipped, ex: "NonBillable=true" will exclude the worklog where the "NonBillable" checkbox attribute is checked

## mapping of Tempo customer keys to customer address lines (note: keys are case-sensitive)
#set($tempoCustomerAddresses = {
	"ACME":		[ "17 boulevard Saint-Marcel", "75013 Paris", "France" ],
	"MEGACORP":	[ "45 Stirling Highway", "Crawley WA 6009 Perth", "Australia" ],
	"XYZINC": 	[ "Schwanthaler Strasse 85a", "Munich 80336", "Germany" ]
})
Configuring the customer invoice addresses

When the timesheet-invoice-fo.vm template is rendered in "invoice" mode, it will automatically figure out the customer's invoice address based on the Tempo worklogs. This section explains how.

First, let's see the underlying Tempo concepts!

In Tempo, each worklog is linked to a Tempo account in one of these two ways:

  1. Either the worklog inherits the account from the Account custom field of its owning issue. (This is the default.)
  2. Or, the worklog has the account set by using an "Account" type work attribute.

Plus, each Tempo account is linked to a Tempo customer. Consequently, each worklog is indirectly linked to a Tempo customer. Note that both accounts and customers are identified by unique textual keys.

So, how is the customer address figured out by the timesheet-invoice-fo.vm template?

  1. It takes the first issue passed to it.
  2. It takes the first worklog of that issue.
  3. It takes the customer name from the worklog. (It means you can maintain your customers natively in Tempo.)
  4. It takes the customer key from the worklog, and using that key it looks up the customer address from the $tempoCustomerAddresses map. (It means you can maintain the list of the customer addresses in the template, see the code block above!).

Note that this logic is coded to the template itself. As always, it can be easily modified if necessary.

Of course, every invoice must be created for one specific customer. The simplistic logic above assumes that all the worklogs of all the issues passed to the template are created for the same customer. It means that:

  • It is safe to check only the first worklog to figure out the customer.
  • It is your responsibility to export only those issues that are created for the same customer to an invoice.

To troubleshoot the case when the customer or its address is not found by template, check these:

  1. Is the first issue's first worklog linked to a Tempo account?
  2. Is that Tempo account linked to a Tempo customer?
  3. Is there a $tempoCustomerAddresses entry with the key of that Tempo customer?
Configuring the period filter for Tempo worklogs

You can configure a time period, and the tempo-tool.groovy script exports only the worklogs in that time period. The time period is specified by its start date and end date.

You can configure the period by setting these values in the templates:

## issue-fo.vm or timesheet-invoice-fo.vm

#set($tempoDateFrom = '2000-01-01')    ## start date for the exportable Tempo worklog period
#set($tempoDateTo = '2099-12-31')      ## end date for the exportable Tempo worklog period
Configuring the pre-loading for Tempo worklogs

tempo-tool.groovy script supports two loading strategies: "pre-load worklogs for all issues" vs. "load worklogs for each issue separately".

In our profiling, the former works faster for larger number of issues, i.e. when we expect a larger number of worklogs to be returned. These requests can be served faster if all the worklogs are downloaded with a single Tempo API call (instead of one Tempo API call per issue).

Beware! If you have a large number of issues, then pre-loading can generate heavy load on Tempo. Therefore, by default, pre-loading is used only if there are more than 10 issues to export.

This is the expression in tempo-tool.groovy that captures the default decision logic, allowing to change the value of 10 issues:

preloadWorklogs = (issues.size() > 10)

Or, you can enforce pre-loading (in every case) by deleting the right-side expression and setting the variable to true:

preloadWorklogs = true
Configuring the Tempo servlet request details

If you wanted to change the low-level details of invoking the Tempo servlet, you can do that by editing the tempo-tool.groovy script. The script itself is short and very easy to understand. You can change the servlet's URL by editing this line, for instance:

def url = "https://app.tempo.io/api/1/getWorklog?dateFrom=${dateFrom}&dateTo=${dateTo}&format=xml&addBillingInfo=true&addUserDetails=true&baseUrl=${baseUrl}&tempoApiToken=${apiToken}"

Learn more about Tempo Timesheets