Google Calendar Synchronization

To get a real synchronization between org-mode and Google Calendar you need to sync two ways. We cover one way of handling the synchronization in the next two sections and also mention some other ways of synchronization at the end.

Google Calendar offers access to each calendar via a hidden/secret url. That is, a url that only you know about and is very hard to guess for other people. You can use this to download your calendar in an iCalendar (.ics) format, which we then can rewrite into something usable for org-mode. For this conversion there luckily already exists a script written by Eric S. Fraga¹.

You can get the latest version here: ical2org.awk

With this you can test your Google Calendar to org-mode synchronization by following these steps:

1. Download the above script and save it as 'ical2org'. Make sure that the script is in your PATH and don't forget to set the executable flag (chmod u+x ical2org). You should customize the script by changing the variables in the config section of the script. Note in particular 'max_age' for setting which entries are converted, and 'author' and 'email_address' for setting your details.
2. Find your private URL for your calendar
   • Log into Google Calendar
   • Goto Settings
   • Click on the calendar you want to export to org-mode
   • At the bottom of the page find the 'private address' section and your ical link Use the 'reset private urls' if you need to, that is if you don't see a unique url.
3. Download the url This can be done for example using 'wget <url>'
4. Transform into org-file Use the downloaded script via 'ical2org < icsfile > orgfile'. Where icsfile is the path to the file you downloaded from Google and orgfile is the org-mode file you want to create.
5. Add the orgfile to your agenda and test

If this all works you can automate the task via cron. Create a script such as the following that will automatically download and convert your calendar. Make sure that this file is only readable by you (chmod 700 <file>), since it will contain the url to your Google calendar.

#!/bin/bash

# customize these
WGET=<path to wget>
ICS2ORG=<path to ical2org>
ICSFILE=<path for icsfile>
ORGFILE=<path to orgfile>
URL=<url to your private Google calendar>

# no customization needed below

$WGET -O $ICSFILE $URL
$ICS2ORG < $ICSFILE > $ORGFILE

automate this via cron by adding something like the following to your crontab:

5,20,35,50 * * * * <path to above script> &> /dev/null #sync my org files

This will sync every 15 minutes starting at 5 minutes past the hour.

You can export from org mode to .ics; upload .ics to a public web server giving it a hidden/secret name; tell Google to import this .ics file.

This has the disadvantage that the item won't show up in your "main" calendar and therefore you can't easily share them with others. Nevertheless, this route is relatively easy and therefore we'll discuss it below.

Also keep in mind that your mileage will vary, since everything described on this page works for some people, but perhaps not for you… if this is the case, feel free to ask on the org mailing list and perhaps we can add missing features.

Back to the topic. We need org to export an .ics file, which can be achieved using the function: org-export-icalendar-combine-agenda-files. This will export all entries in you agenda. If you only want to export certain ones, you can set up a filter. For this we will define a filter function and then tell Emacs to use this filter. The filter shown here, will exclude items with a category "google" (for example from the ical2org script) and "private" and also only export entries that have a date and a time range set (that is, a start and a end time stamp). You can modify the function though to do anything you want!

;;; define categories that should be excluded
(setq org-export-exclude-category (list "google" "private"))

;;; define filter. The filter is called on each entry in the agenda.
;;; It defines a regexp to search for two timestamps, gets the start
;;; and end point of the entry and does a regexp search. It also
;;; checks if the category of the entry is in an exclude list and
;;; returns either t or nil to skip or include the entry.

(defun org-mycal-export-limit ()
  "Limit the export to items that have a date, time and a range. Also exclude certain categories."
  (setq org-tst-regexp "<\\([0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\} ... [0-9]\\{2\\}:[0-9]\\{2\\}[^\r\n>]*?\
\)>")
  (setq org-tstr-regexp (concat org-tst-regexp "--?-?" org-tst-regexp))
  (save-excursion
    ; get categories
    (setq mycategory (org-get-category))
    ; get start and end of tree
    (org-back-to-heading t)
    (setq mystart    (point))
    (org-end-of-subtree)
    (setq myend      (point))
    (goto-char mystart)
    ; search for timerange
    (setq myresult (re-search-forward org-tstr-regexp myend t))
    ; search for categories to exclude
    (setq mycatp (member mycategory org-export-exclude-category))
    ; return t if ok, nil when not ok
    (if (and myresult (not mycatp)) t nil)))

;;; activate filter and call export function
(defun org-mycal-export ()
  (let ((org-icalendar-verify-function 'org-mycal-export-limit))
    (org-export-icalendar-combine-agenda-files)))

To use these function you can include the above code in your .emacs file and then in case you run Emacs server call

emacsclient -e "(save-excursion (org-mycal-export))"

in your shell to generate the .ics file.

If you want to export also TODO items that have a SCHEDULED timestamp, you can set

(setq org-icalendar-use-scheduled '(todo-start event-if-todo))

in your .emacs.

Another Emacs variable that you might want to look into is: org-icalendar-honor-noexport-tag.

You can now automate this via a cron job to generate updated .ics files.

The next step is to give the file a cryptic name (so that other people have a hard time accessing your file, also make sure that your web server doesn't show an index for your directory, etc.) and copy it to a public accessible web server. Then log into your Google calendar and in the left column under "Other calendars" use "Add"->"Add by url" to point Google at your freshly generated .ics file and you should be all set up. Once you done this Google will every now and then (every few hours?) look for a newer version of your .ics file and include this in your calendar.