Integrating CalDAV with Ruby on Rails

This is an English translation of the original French article by @gab_ https://gabriel-kinoba.medium.com/int%C3%A9gration-de-caldav-en-rails-d52c6bbdd02

For one of our projects at Kinoba we wanted to design a calendar tool to manage our members vacation leaves. One of the key features of this tool was to be able to automatically add an event to our team calendar upon the validation of a leave.

The first step was to understand the protocol used to transfer the information of a leave between our tool and a calendar.
We use Nextcloud for our shared calendars. Nextcloud makes it possible for us to use the CalDAV protocol.
CalDAV to make it easy allows us to transfer informations through another one : iCalendar

The iCalendar protocol

It is a data format described in RFC 5545 used for calendar data transfers. We can for example use it to describe a calendar (VCALENDAR), an event (VEVENT), a task (VTODO) and other elements.

BEGIN:VEVENT
UID:123456789
DTSTAMP:20210201T080000Z
DTSTART:20210201T123000Z
DTEND:20210201T133000Z
SUMMARY:Lunch
CLASS:PRIVATE
CATEGORIES:BUSINESS
END:VEVENT

The code above describes an event with the title Lunch which has happened between February 2nd 2021 00:30 and 01:30 UTC PM.

We now know a little more about the data format used to communicate with a calendar through CalDAV. As (almost) always, there is a Gem, icalendar — maintained — which transforms a ruby object into an iCalendar representation.
The last step is to find a way to send this iCalendar representation to our Nextcloud instance : meet the CalDAV protocol.

The CalDAV protocol

It is one of the ways to edit an online calendar. It is described in RFC 4791 and is an extension to WebDAV which is used to work with files. In our case CalDAV will only manage .ics files of the iCalendar protocol.

Many CalDAV gems exists but none of them seem to be actively maintained.

The int2root/twisted-caldav

We settled for the twisted-caldav gem which was last updated 9 months ago. Sadly it only managed the 1.x version of iCalendar, the little brother of the 2.x version.
Open source being about sharing and caring, we dug a little in this gem’s code and made the appropriate modifications for it to be able to manage iCalendar 2.x.

We also made other small changes such as dependencies updates, code refactoring of client.rb and added the transp attributes which helps us know if one is free during an event or not. Finally we improved how beginning and end dates were managed by allowing multiple data formats to be passed : timestamps, dates with or without the timezone as iCalendar lets us choose whether we want the timezone or not.

Both PRs are accessible here and here

Getting started with the twisted-caldav gem

Thanks to those PR we hope the community now has a more up to date Gem to add, delete and modify events to a calendar. Setting up this gem is simple and classic:

gem install 'twisted-caldav'

And using it:

require 'twisted-caldav'

u = 'user1'# calendar initialization
cal = TwistedCaldav::Client.new(uri: "http://yourserver.com:8008/calendars/users/#{u}/calendar/", user: u , password: 'xxxxxx')# getting already created events
events = cal.find_events(start: '2021-02-01', end: '2021-04-16')# creating an event
event = cal.create_event(start: '20210416T1000Z', end: '20210416T1100Z', title: 'Very special meeting')

Now thanks to this Gem we have a working and fully integrated tool to manage our team member vacation leaves with our Nextcloud shared calendars. Even if this Gem was not initially perfect for our needs we made changes and hopefully helped the community!

A big thanks to the twisted-caldav gem’s author as well as to all the contributors who helped him improving it.