Tempo Timesheets Integration

In this page

What is Tempo Timesheets?

(supported since Better PDF Exporter 3.4.0)

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

Tempo Timesheets integration features

• You can export PDF documents directly from the Timesheet (with all issues in the timesheet), Calendar (with all issues in the selected period), Report (with all issues in the report) and List views (with all unique issues in the list). (supported since Better PDF Exporter 4.0.0)
• You can export Tempo Timesheets (or Tempo Planner)-managed custom field types, like Account, Iteration, Team to PDF.
• You can export Tempo Timesheets-managed worklogs to PDF. Exporting custom work attributes is optional.
• You can filter Tempo Timesheets worklogs by start date and end date.
• You can export worklogs created by all users or the current user only.
• You can implement other types of custom filtering, for example excluding the non-billable worklogs.
• Better PDF Exporter also offers a customizable timesheet/invoice template to generate custom timesheets and time-based invoices from Tempo Timesheets worklogs.

(Need more features? Tell us in a support ticket!)

Tempo Timesheets integration vs. the Tempo Timesheets built-in PDF exports

You may want to ask: if Tempo Timesheets has a built-in PDF export feature, why would you use another app for the same?

While the Tempo Timesheets built-in PDF exports may be sufficient for basic use cases, the Better PDF Exporter integration is more powerful in, at least, these:

• It supports PDF automation.
  You can export, email and attach PDF files using Automation for Jira (visual automation rules), ScriptRunner (Groovy scripts), or the REST API (use your favorite language!).
• It is extremely customizable.
  Instead of accepting the pre-defined export types in Tempo Timesheets, you can define your own types via PDF templates.
• It supports all the powerful PDF features.
  You can use custom calculations in Groovy (sorting, complex math, data integration, etc.), embedded attachments, PDF bookmarks, charts, graphics (in Groovy, SVG, QR codes and barcodes, etc.), among others.
• It is integrated with all the popular Jira apps.
  You can freely combine Tempo Timesheets data and other apps' data in the same PDF file.
• It comes with powerful templates optimized for Tempo Timesheets.
  You can use those "as is", or customize them to your needs.
• It is well-documented with the customization guide, the Expression Reference Manual, the recipes, and such.

If at least one of these is important for you, give the app a try.

Tutorial video

Create customized timesheets or invoices from the Tempo timesheets with one click!

Tempo Timesheets PDF export samples

Configuration

Configuring the Tempo Timesheets custom fields

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

Configuring the Tempo Timesheets Servlet API access

If you want to export Tempo Timesheets worklogs, PDF templates download those from the Tempo Timesheets Servlet API during the document rendering. Tempo Timesheets Servlet is basically Tempo Timesheets' HTTP based API.

Execute these steps to allow the templates to connect to the Tempo Timesheets Servlet:

1. Login to Jira as administrator.
2. Go to Administration → Add-ons → Access Control (under Tempo).
3. Enter "127.0.0.1" (localhost) or the Jira server's actual IP to "Allowed addresses", and "Save" the changes.
4. Copy the "Security token" string to the clipboard.
5. Go to Administration → Add-ons → PDF Templates (under Better PDF Exporter).
6. 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 = '3022ac1e-db73-4c54-9c15-cceccbb94554')
   

7. Paste the security token similarly to the timesheet-fo.vm template, as well.
8. Export a Jira issue having Tempo Timesheets worklogs with the "PDF" view as a test. You will see java.io.IOException: Server returned HTTP response code: 401 for URL error messages in the exports until the access permissions are properly set up.

Configuring the Tempo Timesheets worklogs in PDF templates

After you set up the Tempo Timesheets 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 Timesheets worklogs of the current user only, or "false" to export everyone's

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

## timesheet-fo.vm

#set($tempoExportCustomer = true) ## whether to look up the "Customer" from Tempo Timesheets based on the account set in the first issue to be exported
#set($tempoExportWorklogAttributes = false) ## whether to display the work attributes for each worklog item
#set($tempoExcludeWorklogsWithAttributesContaining = "NonBillable=NonBillable") ## Tempo Timesheets worklogs with attributes containing this string will be skipped, ex: "NonBillable=NonBillable" 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-fo.vm template is rendered in "invoice" mode, it will automatically figure out the customer's invoice address based on the Tempo Timesheets worklogs. This section explains how.

First, let's see the underlying Tempo Timesheets concepts!

In Tempo Timesheets, 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-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 Timesheets.)
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 Timesheets worklogs

If there is a time period specified, then 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 passed as request parameters.

The start date and the end date are available in Tempo Timesheets contexts (like the Timesheet screen), but not available in others (like the Issue Navigator screen). This is simply because while the Tempo Timesheets contexts offer a period selector, Issue Navigator doesn't.

For this latter case, the period is basically "all times". You can configure the default period by setting these values in the templates:

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

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

Or, you can disable the filter by ignoring the period passed and forcing "all times":

// tempo-tool.groovy

// remove this snippet to ignore passed period
if(tempoDateFromRequestParameter && tempoDateToRequestParameter) {
	tempoDateFrom = tempoDateFromRequestParameter
	tempoDateTo = tempoDateToRequestParameter
}

Configuring the user filter for Tempo Timesheets worklogs

Since app version 6.2.0, the tempo-tool.groovy script can export the worklogs of only one specific user if the username is passed in a request parameter.

The username is available in Tempo Timesheets contexts (like in the Timesheet screen), but not available in others. Again, this is simply because the user selector is available only in Tempo Timesheets contexts.

You may want to disable this filtering also in Tempo Timesheets contexts, in order to export the worklogs for all users. The most typical use case example is creating a monthly report that accumulates the work of every team member. To disable the filtering, set this configuration variable to true:

// tempo-tool.groovy

def exportWorklogsOfAllUsers = false

Configuring the pre-loader for Tempo Timesheets 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 in the period are downloaded with a single Tempo Timesheets API call (instead of one Tempo Timesheets API call per issue).

Beware! If you have a large number of issues and the period is "all times" (or very long), then pre-loading can generate heavy load on Tempo Timesheets. Therefore, by default, pre-loading is used only if there are more than 10 issues to export and the period is not "all times" (but some specific start and end date)!

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

// tempo-tool.groovy

preloadWorklogs = (issues.size() > 10) && !exportWorklogsOfAllTimes

If you are not worried about longer periods and want to make it depend only on the issue count, you can reduce the decision to this:

// tempo-tool.groovy

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:

// tempo-tool.groovy

preloadWorklogs = true

Configuring the Tempo Timesheets Servlet request details

If you want to change the low-level details of invoking the Tempo Timesheets 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:

// tempo-tool.groovy

def url = "${baseUrl}/plugins/servlet/tempo-getWorklog/?dateFrom=${dateFrom}&dateTo=${dateTo}&format=xml&addBillingInfo=true&addUserDetails=true&tempoApiToken=${apiToken}"

Troubleshooting

Character encoding problems

If you see broken international characters in the exported files (especially in the worklog description field), start Jira with the -Dfile.encoding=utf-8 parameter. If it doesn't help, see the Troubleshoot character display issues in Jira server page in the Jira manual.

Learn more about Tempo Timesheets

• Tempo Timesheets product information (at its own vendor)
• Tempo Timesheets documentation
• Tempo Timesheets app page (on the Atlassian Marketplace)