13.15 iCalendar Export

A large part of Org mode’s interoperability success is its ability to easily export to or import from external applications. The iCalendar export back-end takes calendar data from Org files and exports to the standard iCalendar format.

The iCalendar export back-end can also incorporate TODO entries based on the configuration of the org-icalendar-include-todo variable. The back-end exports plain timestamps as ‘VEVENT’, TODO items as ‘VTODO’, and also create events from deadlines that are in non-TODO items. The back-end uses the deadlines and scheduling dates in Org TODO items for setting the start and due dates for the iCalendar TODO entry. Consult the org-icalendar-use-deadline and org-icalendar-use-scheduled variables for more details.

For tags on the headline, the iCalendar export back-end makes them into iCalendar categories. To tweak the inheritance of tags and TODO states, configure the variable org-icalendar-categories. To assign clock alarms based on time, configure the org-icalendar-alarm-time variable.

The iCalendar format standard requires globally unique identifier—or UID—for each entry. The iCalendar export back-end creates UIDs during export. To save a copy of the UID in the Org file set the variable org-icalendar-store-UID. The back-end looks for the ‘ID’ property of the entry for re-using the same UID for subsequent exports.

Since a single Org entry can result in multiple iCalendar entries—timestamp, deadline, scheduled item, or TODO item—Org adds prefixes to the UID, depending on which part of the Org entry triggered the creation of the iCalendar entry. Prefixing ensures UIDs remains unique, yet enable synchronization programs trace the connections.

C-c C-e c f (org-icalendar-export-to-ics)

Create iCalendar entries from the current Org buffer and store them in the same directory, using a file extension ‘.ics’.

C-c C-e c a (org-icalendar-export-agenda-files)

Create iCalendar entries from Org files in org-agenda-files and store in a separate iCalendar file for each Org file.

C-c C-e c c (org-icalendar-combine-agenda-files)

Create a combined iCalendar file from Org files in org-agenda-files and write it to org-icalendar-combined-agenda-file file name.

The iCalendar export back-end includes ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties from the Org entries when exporting. To force the back-end to inherit the ‘LOCATION’, ‘TIMEZONE’ and ‘CLASS’ properties, configure the org-use-property-inheritance variable.

When Org entries do not have ‘SUMMARY’, ‘DESCRIPTION’, ‘LOCATION’ and ‘CLASS’ properties, the iCalendar export back-end derives the summary from the headline, and derives the description from the body of the Org item. The org-icalendar-include-body variable limits the maximum number of characters of the content are turned into its description.

The ‘TIMEZONE’ property can be used to specify a per-entry time zone, and is applied to any entry with timestamp information. Time zones should be specified as per the IANA time zone database format, e.g., ‘Asia/Almaty’. Alternately, the property value can be ‘UTC’, to force UTC time for this entry only.

The ‘CLASS’ property can be used to specify a per-entry visibility class or access restrictions, and is applied to any entry with class information. The iCalendar standard defines three visibility classes:

‘PUBLIC’

The entry is publicly visible (this is the default).

‘CONFIDENTIAL’

Only a limited group of clients get access to the event.

‘PRIVATE’

The entry can be retrieved only by its owner.

The server should treat unknown class properties the same as ‘PRIVATE’.

Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific applications.