In this page

What is Tempo Timesheets?

(supported since Better Excel Exporter 1.1.0)

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

Tempo Timesheets integration features

  • You can export Excel reports 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 Excel Exporter 2.2.0)
  • You can export the Tempo-managed custom field types, like Account, Team, Iteration, etc., to Excel.
  • You can export the Tempo-managed worklogs to Excel along with their custom worklog attributes. You can optionally filter the Tempo worklogs by start date and end date or to exclude the non-billable worklogs, for example.
  • Better Excel Exporter also offers a reporting template that includes several pivot table and pivot chart worksheets to report planned and spent time by projects, assignees, accounts, iterations and teams.

Tutorial video

Watch this short video to see how to create custom worklog reports from Tempo Timesheets data:

Export samples

Tempo time estimate vs. time spent pivot table

The tempo-report.xlsx exports the high level Time Estimate and Time Spent values augmented with the Tempo-managed data (Account, Iteration, Team) for each issue. It offers various pre-configured pivot tables, or can be cloned to create your own Tempo reports.

jira-tempo-timesheets-report.xlsx

Tempo accounts pivot chart

Account is a concept specific to Tempo, yet fully supported by Better Excel Exporter. This pivot chart example features an aggregation using the account field managed by Tempo.

jira-tempo-timesheets-report.xlsx

Tempo teams pivot chart

This an another example of using Tempo-managed data, in this case teams, in an Excel report.

jira-tempo-timesheets-report.xlsx

Configuration

Exporting Tempo custom fields

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

Configuring the Tempo Servlet API access

If you wanted to export Tempo worklogs, Excel templates download those from the Tempo servlet during the spreadsheet rendering. Tempo servlet is basically Tempo's HTTP based API.

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

  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsAccess 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 AdministrationAdd-onsExcel Templates (under Better Excel Exporter).
  6. Download the file tempo-tool.groovy.
  7. Open the file in any plain text editor for editing.
  8. Paste the security token from the clipboard to the value in the top part:
    // tempo-tool.groovy
    
    tempoApiToken = '3022ac1e-db73-4c54-9c15-cceccbb94554'
    
  9. Save the Groovy file (do not change its name!), and upload that to Jira.
  10. For testing, go to Issue Navigator. Export an Excel file with the Tempo Worklogs (Current f.) view, and check whether the cell values are correctly exported in the last worksheet.
    If those are, you are done.
    If you are seeing java.io.IOException: Server returned HTTP response code: 401 for URL or similar error messages in the cells, check the Tempo API token again in tempo-tool.groovy.

(Please note that this is easy, and you have to configure this only once.)

After you set up the Tempo servlet access, you may want to configure the details of exporting the worklogs. There are several straightforward configuration parameters in the top part of the tempo-tool.groovy script.

Configuring the Excel views for Tempo

By default, Tempo related Excel views are disabled.

Steps to enable them:

  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsExcel Views.
  3. Edit the view Tempo Worklogs (All fields), set the type to "All", and submit.
  4. Edit the view Tempo Worklogs (Current f.), set the type to "Tempo Timesheet" (or "Multiple Issues" in pre-2.2.0 versions), and submit.
  5. Edit the view Tempo (Excel), set the type to "Tempo Timesheet" (or "Multiple Issues" in pre-2.2.0 versions), and submit.

Then the Excel options become available in the Export drop-downs:

Configuring the Excel templates for Tempo

The template tempo-report.xlsx contains placeholders for the Tempo-managed custom fields, which should be correctly configured before generating reports.

Steps:

  1. Login to Jira as administrator.
  2. Go to AdministrationAdd-onsExcel Views.
  3. Click the view Tempo Worklogs (All fields), change its context to at least the "Issue Navigator" and submit. (This view was not enabled by default.)
  4. Go to AdministrationAdd-onsExcel Templates.
  5. Download the template tempo-report.xlsx.
  6. Open the file in Microsoft Excel for editing.
  7. Go to the last worksheet, check the cells in the second row that contain an expression like ${fieldHelper.getFieldValue(issue, "customfield_10123")}. Replace the placeholder custom field ID customfield_10123 with the actual ID of that custom field (see this section for help). For instance, if the ID is 10456 in your Jira instance, then change the expression to ${fieldHelper.getFieldValue(issue, "customfield_10456")}.
  8. Repeat this for the following columns: Account, Iteration and Team.
  9. Save the Excel file (do not change its name!) and upload that to Jira.
  10. For testing, go to Issue Navigator. Export an Excel file with the Tempo Worklogs (All fields) view, and check whether the cell values are correctly exported in the last worksheet.
    If those are, you are done.
    If not, check the custom field IDs again in the template.

(Please note that this is easy, and you have to configure this only once.)

Configuring the period filter for Tempo 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 a start- and an end date passed in request parameters.

Start and end date are available in Tempo contexts (like the Timesheet screen), but not available in others (like the Issue Navigator screen). This is simply because while the Tempo 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 the values in the end of these expressions:

// tempo-tool.groovy

def tempoDateFrom = tempoDateFromRequestParameter ?: '2000-01-01'
def tempoDateTo = tempoDateToRequestParameter ?: '2099-12-31'

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

// tempo-tool.groovy

def tempoDateFrom = '2000-01-01'
def tempoDateTo = '2099-12-31'

Configuring the user filter for Tempo worklogs

Since app version 3.4.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 contexts (like in the Timesheet screen), but not available in others. Again, this is simply because the user selector is available only in Tempo contexts.

You may want to disable this filtering also in Tempo 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-loading for Tempo worklogs

Since app version 3.4.0, 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 API call (instead of one Tempo API call per issue).

There is a potential danger to consider! 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. 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:

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:

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 = "${baseUrl}/plugins/servlet/tempo-getWorklog/?dateFrom=${dateFrom}&dateTo=${dateTo}&format=xml&addBillingInfo=true&addUserDetails=true&tempoApiToken=${apiToken}"

Troubleshooting

Characters 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