Tempo Timesheets Integration

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 Tempo Timesheets (or Tempo Planner)-managed custom field types, like Account, Iteration, Team to Excel.
• You can export Tempo Timesheets-managed worklogs to Excel. 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 Excel Exporter also offers a ready-made report template to report planned and spent time by projects, assignees, accounts, iterations and teams. Although this is useful as is, this can also be used as a starting point to create custom Excel reports from Tempo Timesheets data.

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

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

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

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

• It supports Excel automation.
  You can export, email and attach Excel 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 Excel templates.
• It supports all the powerful Excel features.
  You can use Excel formulas and functions, custom calculations in Groovy (sorting, complex math, data integration, etc.), charts, pivot tables, pivot charts, Visual Basic macros, 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 Excel 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 custom worklog reports from Tempo Timesheets data!

Tempo Timesheets Excel export samples

Configuration

Configuring the Tempo Timesheets Excel views

Note that the Tempo Timesheets custom fields will be available in every Excel view. There are additional views that are specific to Tempo Timesheets and are disabled by default. Don't forget to activate those!

Steps:

1. Login to Jira as administrator.
2. Go to Administration → Add-ons → Excel Views (under Better Excel Exporter).
3. Click the view Tempo Worklogs (All fields).
4. Check the contexts (screens) in which you want this integration be available. (If unsure, check Issue Navigator at least.)
5. Click Save.

Repeat this also for the following views:

• Tempo Worklogs (Current f.)
• Tempo Worklogs (All fields repeating)
• Tempo Worklogs (Current f. r.)
• Tempo Report (Excel)

Configuring the Tempo Timesheets custom fields

There is nothing to do. Better Excel 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, Excel templates download those from the Tempo Timesheets Servlet during the spreadsheet 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 Timesheets).
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 → Excel 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
   
   def 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 Timesheets 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 Timesheets 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 Tempo Timesheets Excel report templates

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

Steps:

1. Login to Jira as administrator.
2. Go to Administration → Add-ons → Excel Templates.
3. Download the template tempo-report.xlsx.
4. Open the file in Microsoft Excel for editing.
5. 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")}.
6. Repeat this for the following columns: Account, Iteration and Team.
7. Save the Excel file (do not change its name!) and upload that to Jira.
8. 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 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 a start- and an end date passed in request parameters.

Start and 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 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 Timesheets 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 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

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 Timesheets API call (instead of one Tempo Timesheets 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 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)