Writing a custom time-tracker / task manager integration: Pt 1

This is part 1 of a series on how I built a custom integration between Todoist and Clockify, a couple of productivity apps at the core of my daily workflow.

If you’re only interested in following the technical details, feel free to tune into part 2 when it arrives - but I always think it’s important to explore the ‘why’ behind any project, particularly since this is software designed to provide something of genuine use. Ultimately, the scripts that I created use TypeScript, the Todoist and Clockify RESTful APIs, and scheduling/automation using GitHub Actions workflows.

Here I’ll be stating the ‘problem’ to be solved, as well as outlining the requirements and design considerations behind my solution.

Productivity options

In work and in life, the number of items on our ever-expanding mental to-do lists can seem overwhelming. Adding items to your list(s) can feel like a job in itself, and good luck clearing tasks more quickly than they perpetuate, in pursuit of the Holy Grail of freedom-from-tasks or ‘inbox zero’ (more thoughts on these concepts at the end of this article).

If this feels familiar and you’re anything like me (a bit of a productivity nerd), you will likely have experimented with a wide range of different tools to try to manage conflicting tasks and demands on our time. Enter: the modern productivity app.

I have personally switched between quite a number of note-taking, to-do and time-tracking apps, trying to find The One that will best allow me to quickly organise my thoughts and tasks, and start actually clearing them rather than endlessly accumulating.

Picking the ‘right’ tool for this is obviously a highly subjective choice. Ultimately, any of them can be used effectively, but for me the best apps achieve the right balance of:

• flexibility (can it do everything I want it to do?), and

• simplicity (can I use this quickly and intuitively without triggering my own mental stack overflow?)

Having jumped between quite a few, for task management I have settled on Todoist, which I feel ticks the most boxes (pun intended) in both respects. It has very useful filtering and tagging options for grouping and searching, a really handy task calendar view with dates set using natural language, and plenty of integrations with other apps (e.g. tracking subscriptions, adding tasks from emails or Teams). At its core though, it feels focused, streamlined and not overly bloated with options and attention/performance-hogging features.

Time-tracking is its own animal, but something I have also grown to appreciate. Clockify is my current choice - it’s free and does everything I need it to. I know that some intensely dislike the idea of logging their daily tasks, and if misused this could become a potential barrier to productivity at best (logging tasks is itself another task), or at worst, an unhealthy obsession with min-maxing every hour of the day, leaving no space for inevitable surprises…or simply allowing yourself a break.

For me, though, this can be something more than a Trojan Horse of hustle culture. There are at least a couple of real positives to time-tracking:

• It can actually combat overwhelm by allowing you to reflect on what you have actually done, even if very few items are ticked off your list of tasks. Seeing that - hey - you actually put 2-3 hours into a project (easily forgotten after a busy day) can really help gain perspective here.

• It’s nice to be able to take a broader view of my week and how much time I have been able to spend on different tasks or projects. If I’m having trouble fitting in all of my different priorities, I can use this to reconsider how I schedule or prioritise my week.

As a side-note, for note-taking (and more) I highly recommend Capacities, an app I discovered alongside the term ‘Personal Knowledge Management’, or PKM. In short, it takes a slightly unconventional approach compared to other note-taking apps, but once you’re used to its core concepts - grouping items into types of ‘object’ (a Book, Movie, Note, Person, whatever you define) with their own fields, and linking them by theme, rather than in a traditional folder structure - it’s pretty hard to go back.

Although there are plenty of others I could mention, I would say that my core workflow utilises some combination of these 3 applications. I try to keep things focused or centralised around these to provide fewer barriers to what’s ultimately more important than any of these ‘meta’ tools - getting things done!

Why build an integration?

Inevitably one app won’t do everything for us (nor should it!), so in our tech-driven world we’re usually hopping between multiple throughout the day - that’s not including social media, of course - for emails, to-dos, reading-lists, note-taking etc. This can again introduce mental overhead and a sense of unwanted complexity, or perhaps the desire to run off into the sunset, never to return.

Integrations allow a user to connect applications, which can remove some of the headaches of manually switching between multiple apps, thereby reducing the instances we need to open, or even allowing us to work within a single interface. They can also sync automatically or handle repetitive tasks through scheduling, making them more reliable and less effortful.

Apps regularly ship with a series of their own out-of-the-box integrations - if available within your chosen app, you can easily link 2 applications and sync data across them. This is by far the easiest approach and is often all you need.

On the other hand, for deeper customisation and flexibility while still taking ‘no-code’ approach, more dedicated tools like Zapier are incredibly powerful and widely used to handle integrations between an enormous number of different applications. You can use these to build some very complex workflows, using a visual flowchart-like interface while interacting directly with data from each of your connected apps.

So why build my own? In short, because I have my own requirements which in practice are far from easy to implement using an integrations platform - no matter how convenient these tools may be overall. You often have to understand the structure of the data you’re working with quite well to make these work as you might expect. And once the complexity of an integration increases, I find that you already need to be adopting a focused, logical, programmer’s type of mindset, which - while by no means exclusive to professional developers - begs the question: why not write your own script, over which you have full control?

Like many apps, Todoist and Clockify provide their own APIs, which allows for a great amount of flexibility and control, since you can use these to directly access and manipulate your own data.

Requirements

My requirements can be broken down into 4 overall categories (each of which formed their own script / GitHub Action workflow, which I’ll come to later). The 5th regards tying all of these workflows together:

Creating tasks from time entries

• A Clockify time entry should populate as a Todoist task.

• At present, my Clockify time-tracker has its own integration with my calendar apps (Outlook and Google Calendar), so it can populate time entries automatically from any events or meetings scheduled in these. I want to be able to view these within my Todoist calendar interface, so that I use them as a basis to time-block my day with tasks, move them around as necessary, and mark any as complete.

• (note: as of writing, there is no native Outlook calendar integration in Todoist, and Google Calendar items can’t be moved or otherwise edited/tagged within Todoist)

Creating time entries from tasks

• I want my tasks (or meetings) to sync back to Clockify as time entries, so that I can track how long I spent on each task.

• Since my day’s tasks and scheduling can (and likely will) change, I don’t want to sync/log tasks to Clockify until they are in the past. Optionally, this might be limited to manually ‘completed’ tasks.

• Scheduled meetings that are in the past should also be treated as ‘completed’ (ideally without requiring manual tagging).

Closing tasks once complete

• Once synced to Clockify, the completed tasks on Todoist should ‘close’ so that they either shift to another date (recurring tasks) or are removed from my outstanding to-dos.

• To ensure a correct sequence here, I need a tagging system that enables tasks to be marked ‘completed’ (but not removed from Todoist’s list until synced to Clockify).

Rescheduling overdue tasks

• Any tasks with due dates that are in the past (overdue) should be automatically rescheduled to today’s date, so that they can be used in the current schedule, or rescheduled to a later date.

Syncing on a scheduled basis

• All of the above scripts should run automatically on a time schedule at regular intervals.

• Since there is some dependency between scripts, this needs to follow the correct sequence:

Some of the solutions proposed here were only apparent after looking into the respective docs for the Todoist API and Clockify API - always a recommended first step - but the majority of high-level requirements were laid out from the offset.

Within these however, there are a series of smaller, attached considerations, some of which only truly became apparent while iterating the app in development. For example:

• The regularity of sync - do I want to populate tasks from time entries daily? A week in advance? (picked the latter for most flexibility)

• Not duplicating entries (checking for entries in either app with the same name and/or start and end time) - important for an effective two-way sync. Especially relevant if running the app on a schedule multiple times daily, or days in advance, where there will be some overlap each time.

• Syncing items so that the same project name/tag populates in both apps - helping keep a consistent data structure and reduce manual effort.

As you can see, the requirements and considerations can quickly add up, and do add complexity. I had to be wary of feature creep here, and focus on the core functionality that I needed. I managed this (as with other projects) using Todoist’s Kanban view, breaking down each feature into a ‘ticket’ which could be organised/prioritised as needed.

In summary

I originally set out here to write a script (or two) to help automate a two-way sync between productivity apps, but you can see how the requirements and considerations quickly expand into something that needs to be planned and managed effectively.

While there can certainly be an upfront cost in terms of time and effort, I do find the results really pay off. It can be very satisfying to be intentional about your own workflows and consider how you go about planning and completing your daily tasks, as well as what goes into an effective productivity app/integration.

In later posts I’ll discuss the implementation stage, along with some of the design challenges that presented themselves - such as the dependencies between scripts, and the trade-offs between automation and user control. Looking forward to seeing you there!

Extra thoughts on time and task management

A quick final note on time management and productivity overall - having read the fantastic (and often sobering) Four Thousand Weeks by Oliver Burkeman, a self-confessed ‘reformed’ productivity nerd - it’s really important to find balance, prioritise what truly matters and to understand our limitations:

“the core challenge of managing our limited time isn’t about how to get everything done—that’s never going to happen—but how to decide most wisely what not to do, and how to feel at peace about not doing it.”
― Oliver Burkeman, Four Thousand Weeks: Time Management for Mortals

“The technologies we use to try to “get on top of everything” always fail us, in the end, because they increase the size of the “everything” of which we’re trying to get on top.”
― Oliver Burkeman, Four Thousand Weeks: Time Management for Mortals

These seem like strong statements, but I’m sure everyone has felt this in one way or another about task overwhelm and the paradoxical role of productivity apps in exacerbating the issue! This isn’t a rejection of the technology, but a reframing and refocusing of our approach in general - considering the ultimate purpose of these tools in our lives, which should be to simplify and clarify.

Burkeman offers some pieces of specific advice on managing our tasks/workload, such as:

• Adopt a fixed volume approach to productivity. Idea is to have an ‘open’ and a ‘closed’ todo list, with the ‘open’ list having a limited size. Only add tasks to the ‘open’ list once you have completed

• Focus on what you’ve already completed, rather than just what’s left (you will always be in productivity debt!). This ties back to my motivation for time-tracking mentioned above.

At all stages, it’s helpful to recognise that productivity (defined here as simply ‘being busy' and/or adding more and more tasks to an endless list) is not the goal in itself - at its simplest, it’s about figuring out what we really need to get done, and removing the obstacles to doing it.