<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=825597734225432&amp;ev=PageView&amp;noscript=1">

Generating PDF invoices from Tempo Timesheets with the JIRA PDF View Plugin

This is a guest post by Aron Gombas from Midori Global Consulting, who recently launched a killer add-on via the Atlassian Marketplace, which extends our Tempo Timsheets add-on for JIRA.

Tempo is clearly the most powerful time tracking solution for the JIRA platform.

Often times, the time tracking data created with Tempo is also fed into an external invoicing system to produce electronic or physical invoices. The invoicing system in these deployments is responsible for merging the Tempo worklogs with hourly rates and customer data, for generating and emailing the invoice documents, for tracking the payment status and for reporting.

We at Midori investigated how we could simplify this flow, by automating the manual tasks and by eliminating data duplication between the two systems. Our result: unless you have really complex invoicing requirements, you can turn JIRA itself into a powerful invoicing solution via customization and smart use of plugins!

Why should I use JIRA for time-based invoicing?

Because you will be able to:

  • Eliminate the separate invoicing system from your business. There is one less system to learn, one less system to operate.
  • Save the costs of synchronizing data between JIRA and the invoicing system.
  • Prevent all problems caused by failed synchronizations, by inaccurate customer information and by duplicated data in general.

What is this article about?

This particular article focuses on how JIRA, the Tempo product family and the JIRA PDF View Plugin allow generating time based invoices from worklogs. (We assume that you are already familiar with JIRA and Tempo Timesheets.)

For the broader aspects of invoicing (which would actually deserve their own articles), we give practical hints and ideas at end of this article.

Generating PDF invoices from Tempo worklogs

In a nutshell, JIRA PDF View Plugin is an extremely customizable, template-driven PDF exporter add-on for JIRA. It can be used to generate every type of document, ranging from issue exports, print-optimized Gantt charts, client-facing Release Notes to custom JIRA reports.

An invoice would be just another export type for the add-on, implemented by its own template.


Tempo invoice example (PDF document)

The PDF View Plugin has a default template called timesheet-fo.vm, which can be easily customized by setting a couple of configuration options (see the next section) or can be used as a starting point for defining your own invoice templates.

We strongly suggest to customize the followings in the template as a minimum:

  1. Your company information (name and address)
  2. Your branding (logo, colors)
  3. Price information (rate per hour, currency, VAT rate)
  4. Payment information (bank account details, credit card acceptance, PayPal, etc.)

Configuring invoice templates for Tempo Timesheets


Invoice template opened in the online editor

PDF templates are simple text files using the XSL-FO document formatting language augmented with Velocity statements (for logic, like if-then conditions or for-each iterations). They are editable in a convenient editor right in your browser.

Please note that you can also execute Groovy scripts during the document rendering, to implement more complicated logic for data collection, integration and processing. Due to the limitation of this article, we will not go into details here, but you are always welcome to read the PDF template development guide in the product manual.

As mentioned before, the invoice template is highly configurable by setting a couple of variables in the top part of the template code. The variables are well-documented right in the code, but here are the answers to the most common questions.

How to connect the template to Tempo Timesheets?

We are glad you asked it. :-) This is the very first thing to do, otherwise the template won’t have access to Tempo Timesheets worklogs, accounts and other data.

To establish the connection, please follow the short configuration guide.

How to set my company details?

Super easy, see these variables in the template:

#set($logoUrl = "http://www.midori-global.com/images/midori-logo.gif")
#set($providerName = "Acme Inc.")
#set($providerAddressLine1 = "123 Hyde Street ")
#set($providerAddressLine2 = "San Francisco, California")
#set($providerAddressLine3 = "USA")

How to change the hourly rate, currency or VAT percentage?

Just modify these:

#set($hourlyRate = 50.0)
#set($currency = "USD")
#set($taxPercentage = 7.75)

Bonus question:  What if these depend on the project, on the customer or some other factors? No problem, the template allows defining conditions with the easy to read Velocity syntax:

#set($project = $issues.get(0).projectObject)
#if(project.key == “FOO”)
#set($hourlyRate = 50.0) ## for the project “FOO”
#elseif(project.key == “BAR”)
#set($hourlyRate = 60.0) ## for the project “BAR”
#set($taxPercentage = 10.0)
#set($hourlyRate = 70.0) ## for all other projects

How to specify my customer’s invoice address?

The first part of this question is: how can the invoice automatically find out the customer from the list of issues? It is simple: the template checks the Tempo account associated with the very first issue, and uses the Tempo customer linked to that account.

Secondly, how does the invoice know the customer’s address, as Tempo does not store that? The template has a customer-key-to-customer-address map, which is easy maintain and which guarantees consistency. When you have a new customer, just add a new entry to this map. The map’s key is the Tempo customer key, and the value is a string array with the address lines:

#set($tempoCustomerAddresses = {
"ACME": [ "17 boulevard Saint-Marcel", "75013 Paris", "France" ],
"MEGACORP": [ "45 Stirling Hw.", "Crawley WA 6009 Perth", "Australia" ]

How to exclude non-billable worklogs from the invoice?

Tempo Timesheets allows adding custom attributes to worklogs. The idea is to set up a checkbox type attribute called “Not Billable” and to skip the worklogs where its value is “checked”.

For that, just configure the following configuration variable:

#set($tempoExcludeWorklogsWithAttributesContaining = "NotBillable=NotBillable")

Simple, right?

How to get a plain vanilla timesheet without any financials?

Just set $hourlyRate to zero. It will effectively hide all money-related information.

Advanced tips

Custom “invoice” issue type

In case you need a clear issue model, not mixing invoicing attributes and statuses with actual work item type issues (tasks, new features, etc.), introduce a new issue type for invoices.

It has multiple benefits:

  • You can hide the invoicing details from the people who completed the work item, but are not interested in charging for it (like the developer who solved the customer request).
  • You can use more flexible invoice attributes: each invoice can have its own hourly rate, currency, etc., via custom fields.
  • You can decouple the workflow of the invoice from the workflow of the work items, for better mapping of statuses and transitions and for better notifications.

It sounds really great, but it has its own costs, as well.

First, you need to deal with a new issue type, a new custom field scheme, a new workflow, obviously.

Second, you need to associate work item type issues with the corresponding invoice somehow. The most intuitive approach for this is using a new issue link type called “invoiced by”. In this case, you also need to adapt your invoice template’s Groovy script, so that it processes the work items linked to invoice issue.

Invoice automation

Another logical step in automating your invoicing process is automatically emailing the invoice PDF to your customer when the invoice is approved. To translate this to JIRA lingo, you need to generate and email the PDF file when the issue is transitioned with a particular workflow transition, inutitively named “Send” for example.

The good news is that it is relatively easy to do with the truly awesome JIRA Automation Plugin and the PDF Automation Plugin for JIRA. Check out this automation tutorial.

Invoice calendars

Make the due date field required for invoices, and display the invoices in a JIRA calendar gadget that is placed in a dashboard shared with your invoicing staff.

Invoice pipelines

Many people prefer to think to the sales process as a pipeline, where each sale is represented by an item in the pipeline.

If you extend this thinking also to invoicing, you can use JIRA Agile to visualize and control your invoice pipelines with Kanban boards.

Reporting on invoices

To produce conceptually correct data for reporting, we suggest to configure your invoice workflow with two resolutions, “Paid” or “Cancelled”, and to make sure that the resolution date is updated accordingly.

Some ideas for setting up a real-time reporting dashboard for invoices:

  • Use the Created vs Resolved gadget: trend of new invoices vs. paid/cancelled invoices.
  • Use the 2D Dimensional Filter Statistics gadget: invoices by Tempo account and status, for example.
  • Use the Filter Results gadget: list of invoices due to the next 5 days, unpaid invoices pending for more 30 days, and so on.

Be creative, you can achieve a lot with JQL and the gadgets. For more complex reporting needs, you may need to use one of the several reporting and Business Intelligence plugins.

Bottom line

We believe that using JIRA, Tempo Timesheets and the PDF View Plugin for invoicing should be a viable option for consultancies, service providers and companies that charge their customers based on Tempo worklogs.

Happy invoicing!


Author's bio

Aron Gombas is the founder and CEO of Midori Global Consulting, a company building productivity add-ons for Atlassian products. A collaboration enthusiast and efficiency hacker, he is always looking for ways to optimize business processes. Email him any time: aron.gombas@midori-global.com

Tempo Note: It’s really awesome to see add-on vendors supporting our products! Are you building, or have you built, an extension to a Tempo add-on for JIRA?  If so, please drop us a line and let us know! (jessie [at] temposoftware [dot] com)