Syncing FocusMate and CalDAV with Python

If you just want the details for deploying yourself, skip to that here.

Being self-employed, it’s often challenging to stay on task, especially tasks without a client or manager to deliver to. FocusMate is a tool I use to solve this problem, a virtual co-working app; book a session, show-up and tell your partner your task, they tell you theirs, you both work on camera for a period of time then reconvene at the end and say how it went.

The biggest downside, it only connects to google calendar, so for every booking, cancellation, and change, I’d get an email with an amended calendar event.

Surely there’s a better way, I thought, and set out to write a connector for my calendar.

Looking into the documentation, I found there is an API, unfortunately it’s currently read only without webhooks, so requires a manual sync or a cronjob.

With this and the Python CalDAV library, I built a connector I’ve been running the past few months on a VPS. Below is an explanation of the code and how I put it together, if you don’t need an explanation, you can jump to implementation.

Getting Focusmate sessions

Step 1 is to see what info we can get from Focusmate and create a connection. In the documentation, we can see there’s a GET request for sessions.

With this, we can use the request library to get data from the FocusMate API. I’ve also used the pytz and datetime libraries to set the duration we want to get sessions between.
For this extract, I’ve also added the JSON library to output the sessions returned by the request.

# This code snippet can run standalone
import requests
import pytz
from datetime import datetime, timedelta, time
import json

API_KEY = "s0m3ap1key123456789a1b2c3d4e5f6z";

timezone = pytz.timezone('Europe/London')
START = datetime.combine(datetime.now(timezone).date(), time.min)
END = START + timedelta(days=8)


def get_focusmate_events(API_KEY, start_time, end_time):
    """ Get focusmate events using api
    Docs: https://apidocs.focusmate.com/
    Return: Json list of items on server
    """
    headers = {"X-API-KEY": f"{API_KEY}"}
    payload = {"start": start_time, "end": end_time}
    response = requests.get(
        "https://api.focusmate.com/v1/sessions", params=payload, headers=headers
    )
    return response.json()["sessions"]

events = get_focusmate_events(API_KEY, START, END)
print(json.dumps(events, indent=2))

Getting CalDAV events

Next, we need to build a connection with our calendar app, mine is CalDAV based, so we’ll use the Python Caldav project to connect to it. They have some examples, we can follow, we start by making a DAVClient Object which is connected to the server. Then we use this to get the calendar, and events in a selected timescale. This code will the print them so we can see event format.

# This code snippet can run standalone
import caldav
import sys
from datetime import datetime, timedelta

## We'll try to use the local caldav library, not the system-installed // from docs
sys.path.insert(0, "..")
sys.path.insert(0, ".")

CALDAV_URL="https://dav.mysite.com/"
CALDAV_USER="username"
CALDAV_PASS="myreallyl0ng&safepassword"
CALDAV_CAL="calendarname"

## CalDAV client creation
caldav_client = caldav.DAVClient(
    CALDAV_URL, username=CALDAV_USER, password=CALDAV_PASS # , headers = {"X-MY-CUSTOMER-HEADER": "123"}
)
CAL_NAME = CALDAV_CAL

def get_calendar(cal_name, caldav_client):
    """ contact server and get calendar """
    my_principal = caldav_client.principal()
    return my_principal.calendar(cal_name)

def get_calendar_events(calendar, start, end):
    """ Search for events between the given dates """
    events_fetched = calendar.search(
        start=start,
        end=end,
        event=True,
        expand=False,  # don't look for recurrences
    )
    return events_fetched

def print_calendar_events(events):
    for event in events:
        print(event.data+ "\n\n")

if __name__ == "__main__":
    START = datetime.fromisoformat("2024-10-15 00:00:00")
    END = START + timedelta(days=8) # or datetime.fromisoformat("2024-10-23 00:00:00")
    calendar = get_calendar(CAL_NAME, caldav_client)
    cal_events = get_calendar_events(calendar, START, END)
    print_calendar_events(cal_events)

Creating new CalDAV events

Now we can get events from both sources, we’ll create new events on our calendar. For this, we use the event’s object returned by FocusMate and the Calendar object. I also use an intermediate function format_fm_session to take the JSON data and format it, returning a dictionary that matches fields available in CalDAV.

def create_new_events(calendar, fm_events):
    for event in fm_events:
        create_new_event(calendar, event)

def create_new_event(calendar, event):
    new_event = format_fm_session(event)
    event = calendar.save_event(
        dtstart=new_event["dtstart"],
        dtend=new_event["dtend"],
        summary=new_event["summary"],
        created=new_event["created"],
        description=new_event["description"],
        location="https://app.focusmate.com",
    )

Now we’re able to add sessions to our calendar, but every time the code runs, all sessions within the timeframe will be duplicated. To get round this, we match FocustMate events to existing ones, only creating events that are not found.

We also need to remove FocusMate event’s that only appear in our calendar but not in the FocusMate events group. I added the sessionId to the top of the event descriptions, allowing FocusMate event’s to be picked up with a regExp and matched, removing those where no match is found.

def check_events_in_fm(
    cal_events, fm_events, calendar
    ):
    for event in cal_events:
        session_id = get_fm_id(event)
        if session_id is not None:  # Event is Focusmate session
            paired = False
            # Find the event on CalDav
            for i, fm_event in enumerate(fm_events):
                # if matching event found
                if session_id == fm_event["sessionId"]:
                    paired = True
                    # Check if changes have been made to title, if so update
                    check_title_updates(event, fm_event, calendar)
                    del fm_events[i]  # remove as we know its already on the calendar
                    break
            if not paired:  # Session no longer booked
                event.delete()  # remove from cal
    return fm_events

The Code

Putting it all together, we get the following code:

Show code

Note: Instead of writing CalDAV events with the attributes, raw data was used, as alarms weren’t fully implemented in the CalDAV python library. (Pull request for issue)

Deploying yourself

Requirements

Calendar that ad hears to the CalDAV spec, major calendars that do this are:
- Google Calendar[Docs]: CalDAV compatible but natively proprietary.
- Apple Calendars[Docs](iCloud Calendar, macOS Calendar, iOS Calendar).
- Others and self-hosted: Nextcloud, Fastmail, Zimbra, Baikal.
- Radicale: My self-hosted calendar of choice.
Always on device to run the sync; Cloud or self-hosted server.
- Alternatively, If you’re running a laptop you can set up the script to run periodically with Task Scheduler on Windows, Cron on Linux or OS X.
  - Sync on these devices won’t take place when the device is turned off.
Credentials for the Calendar and FocusMate API:
- Get FocusMate API key at [https://app.focusmate.com/profile/edit-p?type=account] > generate API key.
- Review the docs for your calendar to find credentials, if using 2fa you may need to create an app password.

Steps

Download the gist file, including requirements.txt.
Create .env.fmcd with the following environmental variables set to your own values:
- FOCUSMATE_API_KEY=s0m3ap1key123456789a1b2c3d4e5f6z CALDAV_URL=https://dav.mysite.com/ CALDAV_USER=username CALDAV_PASS=myreallyl0ng&safepassword CALDAV_CAL=calendarname
- It’s possible your calendar may include other headers or data for authentication, include that here and update the CalDAV client accordingly .
Check the client creation method contains all the required items, it may require headers or other data [CalDAV docs]:
- caldav_client = caldav.DAVClient( secrets["CALDAV_URL"], username=secrets["CALDAV_USER"], password=secrets["CALDAV_PASS"])
Create a virtual environment and install libraries from `requirements.txt`.
- # Make a folder for venv virtual environments mkdir ~/.venvs # Install venvs sudo apt install python3.xx-venv # Create the new virtual environment python3 -m venv ~/.venvs/{env} # Activate the environment . ~/.venvs/{env}/bin/activate # Install requirements for the project pip install -r requirements.txt # Run code python my-code.py # deactivate when done testing code. deactivate
Run the code locally, and sync your calendar, you should now see the newly created events.
Test on remote server: Repeat setup on the server, then test again.
- If you get a KeyError: 'FOCUSMATE_API_KEY' this is likely a result of running the code from a different directory to the environmental variables file, cd to the correct directory and try again.
Assuming the code executed correctly we can now set it to run periodically with cron, in my case I want the script to run roughly every half hour before my devices sync at half past. To do this the steps are as follows
- Open user crontab with `crontab -e`
- Add the line: */28 * * * * . ~/.venvs/<environment>/bin/activate && cd ~/<env-dir> && python3 ~/<code-dir>/focusmate-dav-sync.py –log=INFO && deactivate`
  - */28 * * * * run the code each time the minute is divisible by 28 so at 28 and 56 past the hour, for more info visit cron.help
  - . ~/venvs/<environment>/bin/activate: Activated the codes Python virtual-environment and runs the next command if and only if this was successful.
  - cd ~/<env-dir> && sets the execution directory to the one where I keep env files.
  - python3 ~/<code-dir>/focusmate-dav-sync.py Runs the python script
  - `–log=INFO`:(Optional) Sets the logging level for the program, default is WARN.
  - deactivate: Deactivates the Python virtual-environment.
Done! Assuming the next time the code runs sessions are updated you’re done, hope this was helpful.

TobyR