Free Busy

From Davical
Jump to navigationJump to search

Template:Languages Template:TOCright DAViCal provides three ways to make Free/Busy information available:

  • 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.

freebusy.php URL

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.

Using freebusy.php

By default 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: http://davical.example.com/freebusy.php/username/home?start=20100104T213119Z&end=20110216T213353Z

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 text/calendar.
  • 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 freebusy.php?user=username&token=home or freebusy.php/username/home.

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.

For example:

http://calendar.example.net/freebusy.php/user1/home/

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:

http://calendar.example.net/freebusy.php/username@domain.tld

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.