Toggl Time InvoiceMaker

This script generates invoices based on time entries from Toggl

This script fetches time entries from the Toggl API for a specified client, year, and month, and saves the combined results as a CSV file. The time entries are then able to be grouped together into more concise entries suitable for an invoice.

Features

• Fetch time entries from Toggl for a specific client, year, and month.
• Allow for time entries to be combined by manually editing the csv data in a spreadsheet tool
• Allow for the descriptions of the time entries in a group to be replaced so that the entries can be made more professional
• Sum the durations of combined entries in each group.
• Copy and fill in in an ODT document template with the invoice data.

Prerequisites

• Python 3.10
• pipenv

You can install the required packages using pipenv install

Setup

1. Clone the Repository:

2. Create a .env File: Create a file named .env in the root directory of the project and add your toggl api auth credentials

   TOGGL_API_TOKEN=your_api_token_here
   TOGGL_WORKSPACE_ID=your_workspace_id_here
   

3. Set Up Your Environment: Ensure your environment is set up with the required version of Python 3 and the required packages installed.

4. Create Config File (optional): If you want to pre-input some command line args, copy sampleconfig.ini to a file named config.ini

First Time Usage

Before using the script for the first time, you may want to do a few things

Edit your template Invoice

A sample invoice is included. You may want to edit this to include your logo, your address, the clients address, and any payment terms.

The script will look for the following things to automatically replace in the file:

• the four hashes (####) for the invoice number
• the string mm/dd/yyyy to replace the date
• the word TOTAL (in all caps) to replace the total cost of the invoice
• at least one table in the document. The last table found in the document will have invoice line items filled in starting from its second row. Rows will be added if needed.

When replacing values, the formatting is preserved wherever possible, so choices such as font, font size, text alignment, etc made in the template should(tm) be preserved.

Program arguments and configuration

Other than environment variables, the script can accept arguments via commandline args or the config file. All args are available to be set from either place. Command line args will take precedence over those from the file.

Args available in the command line can be listed by passing in the --help argument.

To define those args in the config file, use the same name. You will need to replace any non-leading hyphens (please leave out leading hyphens) in the CLI arguments with underscores (i.e. the --outfile-template CLI arg becomes outfile_template in the config file).

Example Commands

Fetch and save time entries for the last complete month:

python main.py --templatefile "Sample Invoice.template.odt" --client-name 'Client Name' --invoice-number 42

Fetch and save time entries for a specific year and month:

python main.py --templatefile "Sample Invoice.template.odt" --client-name 'Client Name' --year 2023 --month 7 --invoice-number 42

Output

If pulling data from toggl, a CSV file named time_entries-grouped.csv will be created in the project root directory during the program run. This file contains data from toggl with the following additional columns:

• Group ID: The unique identifier for the group.
• Group Description: The description for the group.

The program will stop and prompt you to edit this file to group the items together.

If no changes are made, the program will assume every time entry should be its own line item in the invoice.

If any item is given a group ID:

• items without a group ID will be discarded
• the last item in the group with a group description set will become the group description for the whole group (if none are set it will use the description if the first item in the group that was fetched from toggl)

When the program resumes, it will create a copy of the template file with the invoice data filled in based on the data from each group that you created. The name of this file will use the template filename provided in the args, or a default one.