In this page

What is Tempo Timesheets?

(supported since Better PDF Exporter 1.1.0)

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

Tempo Timesheets 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 work attributes.
  • You can filter the Tempo worklogs by start date and end date. You can export the worklogs created by the current user only, and implement other types of custom filtering.
  • You can export the billable hours only (i.e. exclude the non-billable hours).
  • 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 vote on the corresponding idea on the Tempo Ideas portal. Leave a comment explaining your use case and its impact on your team's work. The more votes and comments this feature request receives, the higher probability it will be implemented. Voting and commenting takes only 2 minutes of your time, and it also makes sure you will get notified when there is an update.
    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.

(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:

If any of these are important for you, give it a try.

Tutorial video

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.)

Export samples

Timesheet

This is a simplistic timesheet, aggregating the worklogs of an issue list, in a professional document that you can share with your clients.

jira-timesheet.pdf

Time-based invoice

After specifying the hourly rate, it will include money information as well (amout due, net, gross). You may event want to add tax information, payment information (SWIFT code and IBAN). If you run time and material based projects, you can easily turn Jira into a powerful billing system with this template.

jira-invoice.pdf

Tempo invoice

Invoices can also be created from Tempo worklogs, making use of the additional domain data like Account or Team.

jira-tempo-invoice-example.pdf

Configuration

Exporting Tempo custom fields

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

Configuring the Tempo REST API access

As this integration relies on the Tempo REST API, you need to configure the access token for the REST API calls in the templates:

  1. Go to JiraAppsTempoSettingsAPI Integration.
  2. Click Get access token.
  3. Copy the access token from the panel (using the Copy button).
  4. Go to JiraAppsManage your appsPDF Templates (under Better PDF Exporter).
  5. Open the issue-fo.vm template for editing, uncomment this variable in the top part, and paste the access token from the clipboard to the value (don't remove the quotation marks around the string!):
    ## Tempo
    #set($tempoAccessToken = 'AwjMZRE5TfVlj6xU8Zj452BclUhAch')
    
  6. Save the changes. (Don't worry about storing tokens here: this file is visible only for Jira administrators, who would have super-user permissions any way.)
  7. Similarly, set the same access token in the timesheet-invoice-fo.vm template.

Configuring the PDF templates for Tempo worklogs

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

There are configuration parameters in the top part of the issue-fo.vm template to filter the worklogs:

## issue-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
#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 work attributes, and to export the billable hours only (i.e. to exclude the non-billable hours):

## 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
#set($tempoExportCustomer = true) ## whether to look up the "Customer" from Tempo based on the account set in the first issue to be exported
#set($tempoExportWorkAttributes = true) ## whether to display the work attributes for each worklog
#set($tempoExportBillableHours = true) ## whether to export the billable hours only

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. First, it tries to get the account from the "Account" field:
    1. It takes the first issue.
    2. It gets the value of the "Account" field.
  2. If the "Account" field wasn't found or if it is unset, it tries to get the account from the work attributes:
    1. It takes the first worklog of the first issue.
    2. It gets the value of the first "Account" type work attribute.
  3. If the account was found in either way, it gets the key and the name of the customer linked to the account. (You can maintain your customers in Tempo.)
  4. Using the customer key, it looks up the customer address from a map in the template code. You can maintain the list of the customer addresses in this code block:
    ## 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" ]
    })
    

As this customer address finder logic is coded in the template, it can be easily customized 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 issue and its 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 has a Tempo account set in the "Account" field?
  2. If not, is the first issue's first worklog linked to a Tempo account?
  3. Is that Tempo account linked to a Tempo customer?
  4. 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

To minimize the number of Tempo REST API calls, thus to achieve the best performance, the worklogs are pre-loaded for all issues by one or more optimized REST API calls. One REST API call bulk-loads the worklogs of multiple issues. Therefore, the total number of REST API calls depends on the total number of issues.

When the REST API call is made, the issue keys are passed in the URL. It can eventually lead to "URL is too long!" problems if your issue keys are overly long, which could theoretically happen if your project keys are overly long. The number of issue keys passed in one REST API call is configurable in the top part of the tempo-tool.groovy script:

def ISSUE_KEYS_PER_REQUEST = 50

Learn more about Tempo Timesheets