- Through the Scheduling Extensions for CalDAV
- Through the CalDAV free-busy-query REPORT
- Through a special .../freebusy.php/... URL
Scheduling Extensions for CalDAV
If your client software supports this (Mozilla Sunbird/Lightning 0.8+ and Apple iCal do. Evolution and Korganiser don't. Others???) then when you attempt to schedule a meeting the software will make a request to DAViCal to extract the availability of the meeting participants around that time.
This lookup is based on the e-mail address of the participant, so it is important that all DAViCal users (and resources) have their e-mail addresses set up. In this context it is more important that the e-mail address is filled and unique rather than that it is set up to actually receive e-mail, so using a non-existant address for scheduling e.g. rooms may be an option.
This is the method that we can expect most clients will use automatically in the future, but it is not so good for cross-domain freebusy requests.
CalDAV free-busy-query REPORT
CalDAV specifies a particular query type to retrieve free/busy information, and from 0.6.0 this is supported. Unfortunately this method is not used by any known client software, though it is implemented in DAViCal.
Access to the freebusy URL usually requires authentication to DAViCal, and the appropriate rights be granted (i.e. free/busy access) to the authenticated user in respect of the calendar (or user) they are accessing free/busy information for.
A configuration setting public_freebusy_url can be turned on to allow for the freebusy URL to be made public. In this way DAViCal could provide freebusy information to (e.g.) a Kerio server, or other service capable of federating the freebusy information.
freebusy.php will show free/busy information starting yesterday and counting 44 days from there. This can be changed by adding parameters to the URL, like this:
The following parameters are recognized:
start: A start date in a format recognized by PHP.
end: An end date in a format recognized by PHP.
period: A period of time in a format defined in RFC2445. Example: P1DT5H30M means 1 day, 5 hours and 30 minutes.
format: Output format, currently accepting only
user: the user whose calendar will be shown.
token: the user's token (calendar) to be shown.
ticket: A ticket granting specific permission to see the freebusy information.
User and token can be set as
The 'standard' way
Since no clients have yet been observed to make CalDAV free-busy-query requests, but Evolution (at least) provides an alternative based around using e-mail addresses, the free/busy information is also available on a direct request. The URL may follow the form identical to the structure for the 'caldav.php' URL (with 'caldav' replaced by 'freebusy' of course), and will return freebusy information to a suitably authorised user.
This format is accepted by a Mozilla Lightning extension from Inverse.
Using an e-mail address
Evolution provides a way of specifying the search for freebusy information which can do a lookup using an e-mail address. In order to support calendars where users may have e-mail addresses in different domains, while sharing the same calendar server, you can specify the freebusy URL using the e-mail address, as:
In this case the e-mail address searched for must be unique, and the freebusy information retrieved will be merged from all of their calendars (excluding PRIVATE events).
The user accessing this URL will still need to authenticate against DAViCal, of course.
Configuration for Korganiser / Kontact
The appropriate section to configure the free/busy retrieval is Settings -> Configure Calendar -> Configure Korganiser (Configure Calendar when using Kontact) -> Free/Busy -> Retrieve -> Server URL. The format of this URL should be:
http:// ... davical server etc ... /freebusy.php/%EMAIL%
If you configure free/busy retrieval through the appropriate settings tab, it will perform a check to determine if the server's parent domain matches the email domain. If it does not, the free/busy times are not retrieved. See this e-mail message for more information:
You can either create a contact and specify the server in the free/busy section, or ensure the parent domain of the server matches the email domain.
Permissions for Free/Busy
If a user has read permission to a calendar, they will quite naturally have the ability to read free/busy information. If you want to bestow permission for Free/Busy without full Read permission you should grant the 'read-free-busy' permission.
If you want to give a particular person access to your freebusy URL without logging into DAViCal to retrieve it you can create a 'ticket' granting the 'read-free-busy' permission and they can use this with the freebusy.php URL to request the information without logging in.