org-google-sync.org : 2013-05-18 10:16
[worg.git] / org-tutorials / org-google-sync.org
1 #+TITLE:   Google Calendar Synchronization
2 #+AUTHOR:    Arun Persaud
3 #+EMAIL:     arun@nubati.net
4 #+DATE:      <2011-02-28 Mon>
5 #+DESCRIPTION:
6 #+KEYWORDS:
7 #+LANGUAGE:  en
8 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
9 #+INFOJS_OPT: view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js
10 #+SELECT_TAGS: export
11 #+EXCLUDE_TAGS: noexport
12 #+LINK_UP:
13 #+LINK_HOME:
14
15 * Overview
16   To get a real synchronization between org-mode and Google Calendar
17   you need to sync two ways. We cover one way of handling the
18   synchronization in the next two sections and also mention some other
19   ways of synchronization at the end.
20 * From Google Calendar into org using .ics files
21   Google Calendar offers access to each calendar via a hidden/secret
22   url. That is, a url that only you know about and is very hard to
23   guess for other people. You can use this to download your calendar
24   in an iCalendar (.ics) format, which we then can rewrite into
25   something usable for org-mode. For this conversion there luckily
26   already exists a script written by Eric S. Fraga[fn:1]. This is the latest version:
27
28 #+INCLUDE: "../code/awk/ical2org.awk" src awk
29
30 With this you can test your Google Calendar to org-mode
31 synchronization by following these steps:
32
33 1. Download the above script and save it as 'ical2org'.
34    Make sure that the script is in your PATH and don't forget to set
35    the executable flag (chmod u+x ical2org). You can also customize the
36    script a bit by changing the variables in the config section of the script.
37 2. Find your private URL for your calendar
38   + Log into Google Calendar
39   + Goto Settings
40   + Click on the calendar you want to export to org-mode
41   + At the bottom of the page find the 'private address' section and your ical link
42     Use the 'reset private urls' if you need to, that is if you don't
43     see a unique url.
44 3. Download the url
45    This can be done for example using 'wget <url>'
46 4. Transform into org-file
47    Use the downloaded script via 'ical2org < icsfile > orgfile'. Where
48    icsfile is the path to the file you downloaded from Google and
49    orgfile is the org-mode file you want to create.
50 5. Add the orgfile to your agenda and test
51
52 If this all works you can automate the task via cron. Create a script
53 such as the following that will automatically download and convert
54 your calendar. Make sure that this file is only readable by you (chmod
55 700 <file>), since it will contain the url to your Google calendar.
56
57 #+begin_src sh
58 #!/bin/bash
59
60 # customize these
61 WGET=<path to wget>
62 ICS2ORG=<path to ical2org>
63 ICSFILE=<path for icsfile>
64 ORGFILE=<path to orgfile>
65 URL=<url to your private Google calendar>
66
67 # no customization needed below
68
69 $WGET -O $ICSFILE $URL
70 $ICS2ORG < $ICSFILE > $ORGFILE
71 #+end_src
72
73 automate this via cron by adding something like the following to your
74 crontab:
75
76 #+begin_example
77 5,20,35,50 * * * * <path to above script> &> /dev/null #sync my org files
78 #+end_example
79
80 This will sync every 15 minutes starting at 5 minutes past the hour.
81
82 * From org to Google Calendar
83
84   There are at least two possible paths to get the information into Google:
85
86   1. export from org mode to .ics; upload .ics to a public web server
87      giving it a hidden/secret name; tell Google to import this .ics
88      file
89   2. use googlecl to import event when you create them into Google
90      calendar (update entries won't be reflected in Google). See [fn:2]
91
92   The first one has the disadvantage that the item won't show up in
93   your "main" calendar and therefore you can't easily share them with
94   others. Nevertheless, this route is relatively easy and therefore
95   we'll discuss it below.  The second option (as described in the link)
96   should work well, if you don't need to change things.
97
98   Also keep in mind that your mileage will vary, since everything
99   described on this page works for some people, but perhaps not for
100   you... if this is the case, feel free to ask on the org-email list
101   and perhaps we can add missing features.
102
103   Back to the topic. To implement 1., we need org to export an .ics
104   file, which can be achieved using the function:
105   org-export-icalendar-combine-agenda-files.
106   This will export all entries in you agenda. If you only want to
107   export certain ones, you can set up a filter. For this we will
108   define a filter function and then tell Emacs to use this filter.
109   The filter shown here, will exclude items with a category "google"
110   (for example from the ical2org script) and "private" and also only
111   export entries that have a date and a time range set (that is, a
112   start and a end time stamp). You can modify the function though to
113   do anything you want!
114
115 #+begin_src emacs-lisp
116
117   ;;; define categories that should be excluded
118   (setq org-export-exclude-category (list "google" "private"))
119
120   ;;; define filter. The filter is called on each entry in the agenda.
121   ;;; It defines a regexp to search for two timestamps, gets the start
122   ;;; and end point of the entry and does a regexp search. It also
123   ;;; checks if the category of the entry is in an exclude list and
124   ;;; returns either t or nil to skip or include the entry.
125
126   (defun org-mycal-export-limit ()
127     "Limit the export to items that have a date, time and a range. Also exclude certain categories."
128     (setq org-tst-regexp "<\\([0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\} ... [0-9]\\{2\\}:[0-9]\\{2\\}[^\r\n>]*?\
129   \)>")
130     (setq org-tstr-regexp (concat org-tst-regexp "--?-?" org-tst-regexp))
131     (save-excursion
132       ; get categories
133       (setq mycategory (org-get-category))
134       ; get start and end of tree
135       (org-back-to-heading t)
136       (setq mystart    (point))
137       (org-end-of-subtree)
138       (setq myend      (point))
139       (goto-char mystart)
140       ; search for timerange
141       (setq myresult (re-search-forward org-tstr-regexp myend t))
142       ; search for categories to exclude
143       (setq mycatp (member mycategory org-export-exclude-category))
144       ; return t if ok, nil when not ok
145       (if (and myresult (not mycatp)) t nil)))
146
147   ;;; activate filter and call export function
148   (defun org-mycal-export ()
149     (let ((org-icalendar-verify-function 'org-mycal-export-limit))
150       (org-export-icalendar-combine-agenda-files)))
151 #+end_src
152
153   To use these function you can include the above code in your .emacs
154   file and then in case you run Emacs server call
155
156 #+begin_src sh
157   emacsclient -e "(save-excursion (org-mycal-export))"
158 #+end_src
159
160   in your shell to generate the .ics file.
161
162   If you want to export also TODO items that have a SCHEDULED timestamp, you can set
163
164 #+begin_src sh
165   (setq org-icalendar-use-scheduled '(todo-start event-if-todo))
166 #+end_src
167
168   in your .emacs.
169
170   Another Emacs variable that you might want to look into is:
171   org-icalendar-honor-noexport-tag.
172
173   You can now automate this via a cron job to generate updated .ics
174   files.
175
176   The next step is to give the file a cryptic name (so that other
177   people have a hard time accessing your file, also make sure that
178   your web server doesn't show an index for your directory, etc.) and
179   copy it to a public accessible web server. Then log into your Google
180   calendar and in the left column under "Other calendars" use
181   "Add"->"Add by url" to point Google at your freshly generated .ics
182   file and you should be all set up. Once you done this Google will
183   every now and then (every few hours?) look for a newer version of your .ics file and
184   include this in your calendar.
185
186 * Other methods of syncing
187
188 ** org-caldav
189
190 David Engster writes:
191
192 #+BEGIN_QUOTE
193 I have written a package 'org-caldav' which can sync items to a remote
194 calendar server using the CalDAV protocol. The main purpose of this
195 package is to make better use of Org in combination with Android-based
196 mobile devices (yes, there is mobileOrg, but I have several problems
197 with it; that's a topic for another day, though).
198
199 I think org-caldav is now "good enough" to allow some testing by
200 adventurous people. I put the code up on github here
201
202 https://github.com/dengste/org-caldav
203 #+END_QUOTE
204
205 * Footnotes
206 [fn:1] http://article.gmane.org/gmane.emacs.orgmode/26848
207 [fn:2] http://article.gmane.org/gmane.emacs.orgmode/27214