Getting Started With Timeular’s API

In the Care team, we end up working on a lot of different tasks. Some billable projects, some internal work and some other things like deployments out of working hours.

Time tracking was starting to either take more time than the time it was tracking or be glossed over. “Yesterday was project Cox” and forget about the half hour you spent talking to someone about a different project.

So, we have decided to trial “Timeular”. A blank, oversized D8 (board gamers know what I mean) with bluetooth connectivity. When you start a different piece of work you move to a different side. And label each side with a reminder what it’s for. An app detects the movement and which side is up and starts/stops a clock for you.

See https://timeular.com for more information on the basics.

I rapidly discovered that when you stop using your mac, the timer doesn’t stop. I came back and found several hours were logged while my mac was in “sleep” mode. There are obviously jobs where you aren’t using a computer all the time you’re working, but mine isn’t one of those jobs. So I wanted to find a way to stop the clock. The obvious way would be to use their API.

The Timeular API is documented here: https://developers.timeular.com/

To get started with it, go to your Account page and “Edit” that will take you to a web page where you can generate an API key/secret. Make a note of both.

Now, using the API key/secret you can generate an authentication token from the command line using cURL :

curl https://api.timeular.com/api/v2/developer/sign-in -d '{"apiKey":"NTc35Z...4NTGI=","apiSecret":"NDdZZ...zlOWI="}' -H "content-type: application/json"

{"token":"eyJhbMi....kcjA"}

Then you can use the token to make a request. For example your current activity :

curl -s https://api.timeular.com/api/v2/tracking -H "Authorization: Bearer eyJhbGx...jU3N"

{"currentTracking":{"activity":{"id":"474001","name":"Timeular dev","color":"#8cc250","integration":"zei"},"startedAt":"2019-07-24T08:58:30.308","note":{"text":null,"tags":[],"mentions":[]}}}

From there, it is just a matter of using the “jq” command to update the JSON responses into something useful and combine it all into a script. Add your own key/secret before trying to use it! This script will add to the notes “Stopped by a Sleep” and then stop the current tracking session.

#!/bin/bash
set -euo pipefail
TIMEULAR=https://api.timeular.com/api/v2
TOK=$(curl ${TIMEULAR}/developer/sign-in -d '{"apiKey":"NTc...MGI=","apiSecret":"NDE5...OWI="}' -H "content-type: application/json" -s | jq -r .token)

CURRENT=$(curl -s ${TIMEULAR}/tracking -H "Authorization: Bearer $TOK")
ACTID=$( echo $CURRENT | jq -r .currentTracking.activity.id)
if [ $ACTID == null ] ; then exit 0 ; fi
NEWNOTE=$( echo $CURRENT | jq '{note: .currentTracking.note}' | jq  '.note.text += "\nStopped by a Sleep"' )


HDRS=(-H "Authorization: Bearer ${TOK}" -H "content-type: application/json" -s -o /dev/null)

#Set the note :
curl "${HDRS[@]}" ${TIMEULAR}/tracking/${ACTID} \
-X PATCH -d "${NEWNOTE}"

#And stop the tracking
curl "${HDRS[@]}" ${TIMEULAR}/tracking/${ACTID}/stop \
-d "$(jq --null-input '{stoppedAt: now | strftime ("%Y-%m-%dT%H:%M:%S.000")}')"

Save that as a script and provide it as the “sleepscript” for sleepwatcher. (https://formulae.brew.sh/formula/sleepwatcher).

brew install sleepwatcher

There are other ways to run scripts when a mac enters sleep. This seemed easiest and it has a “wakescript” that you could use to remind you to rotate your Timeular when you come back to your machine. On the other hand, if you’re sure you would restart the same task, you could either store the state of the current tracking or query the previous time entry, then use the API to restart it. Or, if you always start your day with catching up on the company news, then start an “internal” tracking session.

Hopefully this will be part 1 and we’ll share some more ways to add features as we discover them.

Blog