This document was originally intended as a spec for free-busy implementation in 0.6 but that feature has been cut from 0.6. This may be used for a spec for a later implementation.

1. Overview

In 0.6, Chandler will do Free-busy sharing with other Chandler clients and with any other calendar clients also using CalDAV. This specification describes mostly how the client works. However, there are notes about the server functionality so that we can see the minimum server functionality required to support. Free-busy sharing might be cut from 0.6 to simplify sharing.

2. Requirements

Availability: A user's free-busy information must be available even when the user's personal computer is offline or behind a firewall. Thus we use a server repository to share and access free-busy information. Free-busy information must be available even for users whose whole calendars are not synchronized. Interoperability: Chandler should interoperate with Sunbird and other CalDAV clients and servers in browsing free-busy information. Thus we use CalDAV.

Discovery: We need a reasonable way to discover the location of the free-busy information for another user. Ideally, the Chandler user could type in an email address and Chandler would magically find the free-busy information even when the CalDAV server location is unrelated to the email address. However, in 0.6 we can limit this functionality to working only for a single server location (Pilikia) and for users with accounts on that server.

3. Scope

System scope: From a system point of view, the scope of free-busy sharing in 0.6 is limited to only getting free-busy information from CalDAV servers. If the user's email address account portion (e.g. the 'lisa' of 'lisa@osafoundation.org') is the same as the name of their account on Pilikia, we will automatically find the right location from which to get free-busy time.

Note that Pilikia might not be the server we actually use -- we might swap another server in when we have the minimal functionality added to Slide (which is not the WebDAV server currently running on Pilikia)

Issue: If the user doesn't have an account on Pilikia, do we provide a user interface to enter a URL? All we need is a URL, e.g. "http://isamet.com/~cyrus/calendar", to a Calendar collection on a CalDAV server.

Issue: Will there be any lightweight Contact information stored in 0.6 so that we can associate an email address with one or more free-busy locations? We might do this without any GUI impact, by simply saving the Free-busy URL along with the mail address and never allow editing. GUI: The mini-calendar interface will be used to graphically display free-busy information even from several users.

No Permissions: We are not doing free-busy permissions in 0.6 -- thus server-side support for the 'view-free-busy' permission is not required. Free-busy information will be publicly viewable for all calendars shared on Pilikia.

No Publishing: We will not require an extra step for users to publish their free-busy information in 0.6 (we can do so later in other releases by having the client upload VFREEBUSY components to the server). Because we use a CalDAV server, any events the user shares will be rolled up into a free-busy time report.

Issue: We have had some discussion over whether it will be easier to have a separate step to publish free-busy, or to include it in the same step as sharing. On the one hand, if publishing free-busy is separate from sharing the GUI will likely be easier to understand. On the other hand, that separation causes additional logic and failure cases to the synchronize process, because it prevents the server from being able to calculate the free-busy time directly from the shared calendar. For example, if Esther has permission to add events to Mitch's calendar, these new events won't show up in the free-busy information if that information is stored and uploaded separately. Until Mitch's Chandler client logs in and downloads the new events and adds them to the free-busy published information, the free-busy information would be out of synch.

4. User Interface/Interactions

4.1. Getting to view free busy

The way to view Free-busy is to launch the schedule workflow from the Schedule button on the toolbar. The first step in this workflow is to enter a number of URLs to free-busy information.

Sidenote: A common UI to view free-busy is to start from a meeting invitation where the user types in the email addresses of the invitees. In Chandler, this would be driven from the detail view of a Content Item which is both an Event and a Mailed item. Only when the Item is both a Mail and Event would there be an affordance to view free-busy. However, for Chandler 0.6, we have concerns over the difficulties in mapping email addresses to free-busy URLs.

We can also explore allowing the user to enter email addresses and map to free-busy URLs in cases where Chandler knows how to do that mapping, or enter account names instead of full URLs and Chandler can look up the account location on the CalDAV server.

Issue: How do we know what time-range to get free-busy for?

4.2. Free-busy Display

When the free/busy information shows up, it normally shows the busy time of the current user as well as the busy time of the attendees, for a one week period surrounding the time of interest. Confirmed events show up in solid lines and tentative events show up with dashed lines, similar to the display in a user's own calendar.

Issue: The busy time of the current user should be omitted if the user is scheduling a meeting on behalf of somebody else -- but that functionality isn't yet nailed down for 0.6. Possibly when the user puts another person's email address in the "From" field that's our trigger that they're scheduling on behalf of another. For now, anyway, we can just show the busy time of the current user even if the user didn't enter their own URL.

How does the display differ from our normal display, because there won't be titles available for busy blocks of time?

Issue: Do we allow free-busy viewing in increments other than a week? Single day view? Toggle? Each user's free-busy time shows up in a different color. Colors are automatically chosen, with the "current user" in the default color (currently white). The other users' addresses need to be listed somewhere as a key to understanding the free-busy information. If some user can't be found, who was on the original "to" list, we show that user greyed out with the words "Information Not Available" if you hover over their name.

Issue: What do we do for permissions errors?

Note that account setup and granting permission is out of scope of this spec and may be addressed separately in 0.6 because it's key for sharing as well as for free-busy.

4.3. Navigating Free-busy

We will have a button some place for "forward one week" and "back one week". When the user presses one of these buttons we issue new REPORT requests (see protocol interactions) and repaint the view.

4.4. Finish Schedule Workflow

When the user has found a period that appears free, they need to be able to select it and finish the workflow. Chandler would then need to create a new Mail+Event item, with the selected time filled in already. We also need to populate the new Mail+Event item with the email addresses of all the scheduled people in the To field.

5. Protocol Interactions

5.1. Publish Free-busy

There are no protocol interactions required in 0.6 to publish Free-busy information.

5.2. Download Free-busy

When the user wants to view free busy, we have to follow the download free-busy steps separately for every single user:

1. Find free-busy location either through GUI or lookup (see open issue in Scope)
2. Check server for CalDAV support (see Verify CalDAV Support)
3. Issue REPORT for time-range currently displayed in GUI (see open issue in UI)

CalDAV^? Support"> 5.2.1. Verify CalDAV Support

Issue PROPFIND request to the server to find out if it supports CalDAV and to find out if this collection supports the "free-busy-query" REPORT request.

In theory, we could issue an OPTIONS request first to see if the server supports WebDAV and CalDAV, then PROPFIND to see if the collection supports free-busy queries. However, since we're starting from what's supposed to be a Calendar URL, we can simply confirm that this collection supports the REPORT we want. We issue a PROPFIND request to the collection, confirm that it returns a supported-report-set containing the "free-busy-query" element in the CalDAV namespace.

Issue: We could even skip this step if the REPORT unsupported error is clear enough -- basically check support by simply running the request.

5.2.2. Issue REPORT request

The REPORT request:

REPORT /~lisa/calendar / HTTP/1.1
Host: pilikia.osafoundation.org
Depth: 1
Content-Type: text/xml
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<C:free-busy-query xmlns:C="urn:ietf:params:xml:ns:caldav">
  <C:time-range start="20040902T090000Z"
                end="20040902T170000Z"/>
</C:free-busy-query>

Note that to do this report we only need to know the user's account name, because we'll put all the calendars on OSAF's server in the same location. We do need to know the time range we're interested in and we don't know yet exactly how to get that from the current state of the GUI.

The response to this request will be an iCalendar file embedded inside a WebDAV Multi-Status response. The iCalendar file will contain free-busy blocked times with no recurrances and no information for each busy block other than the start/end time (no title or location information, for example).

Issue: We don't yet know exactly how to request or display which free-busy blocks are Tentative vs. Confirmed -- that's a protocol issue.

Issue: Design should confirm whether we want to see Tentatively-blocked time -- I assume we do.

5.2.3. Error Handling

These are the possible protocol errors that we'd want to report to the user:

• Server does not support REPORT -- "The free-busy URL is not a calendar or does not provide Free/busy information."
• Resource not Found -- "That calendar does not exist, check the URL and try again"?

6. Other Logic/Interactions

6.1. What time range to look at

When a Chandler user views an event, there are a few different date/time ranges they could possibly have in mind, all the way to "something not yet apparent through their actions". I propose we extract an appropriate time range for viewing free-busy from the actions they have done so far and the views currently open:

1. If there is a detail view open for a Calendar event and it has a start time/day filled in, we request free-busy time for all participants for the Sunday-> Saturday period surrounding that start time. If that start time is empty, however...
2. Use the date currently selected in the mini-calendar.

Issue: I think that's all we need to do for now because there's no way to select a date-range and because the mini-calendar is guaranteed to have a date selected (defaults to today) -- but need to confirm.

6.2. Caching Information

While a user is viewing a free-busy view, we need to cache the URLs for each of those users. We might also want to cache whether the URL is valid or not so we don't keep uselessly checking for users for whom the URL returns "not found" or "report not supported".

Do we cache free-busy time for weeks that the user has viewed before but is not now viewing, in case they navigate forward and back?

Do we cache free-busy URLs for the duration of a session? Do we store them permanently?