OpenGroupware.org / KDE H. Hess
OpenGroupware.org
November 3, 2004
Storage of Groupware Objects in WebDAV (GroupDAV)
Status of this Memo
This document is an informal draft and WORK IN PROGRESS.
OpenGroupware.org and KDE are actively working to refine the document
based on real world experience with the Kontact WebDAV resource and
the OGo ZideStore server.
Other vendors are invited to provide feedback and comments.
Copyright Notice
Copyright (C) H. Hess.
Abstract
This document outlines a specific way to use the HTTP / WebDAV
protocol to store groupware data like events, todos and contacts.
The goal is trivial implementation in both, clients as well as
servers.
Table of Contents
1. Introduction
2. Basic Resource Model
3. Typical GroupDAV Entities
3.1 Events
3.1.1. Recurring Events
3.1.2. Alarms
3.2 Tasks
3.2.1. Recurring Tasks
3.2.2. Connected Tasks
3.3. Contacts
3.4. Journals
3.5. Mails
4. Handling of UIDs
5. Operations
5.1. Listing Items in a Collection
5.2. Retrieving Items
5.3. Deleting Items
5.4. Creating Items
5.5. Changing Items
6. Locking
7. Folder Discovery
7.1. Event Folders
7.2. Task Folders
7.3. Contact Folders
8. Folder Management
9. Error Codes
10. FreeBusy Support
11. TimeZone Issues
12. Optional DASL Query for Bulk Fetch
13. Property Promotion and DASL Queries
14. Authentication
15. Access Control
16. Server Change Notifications
17. Other Protocols
18. Security Considerations
19. Namespace Registration
20. Normative References
Authors' Addresses
Appendices
A. Acknowledgements
B. Changes
1. Introduction
Similiar to CalDAV [7] the concept presented here uses HTTP [2] as
a protocol to store groupware/pim related entities. Unlike CalDAV
this draft includes not only calendar resources but also applies for
other types of entities, like contacts or notes. It also differs in
the scope, GroupDAV only allows for coordinated storage of items and
does not provide higher level scheduling or query operations.
This draft also tries to describe a pure application of WebDAV [3]
which requires as little protocol specific enhancements as possible
and focuses on the functionality already provided by WebDAV.
Neither the GroupDAV server nor the client are required to fully
implement the full WebDAV specification. The server SHOULD support
a complete WebDAV implementation.
The goal is to provide a protocol which is trivial to implement by
real world servers yet provides a good level of functionality. The
initial implementation which supports contacts, tasks and events
was built in just 2 days by two OpenGroupware.org contributors on the
server side and two KDE contributors on the client side.
2. Basic Resource Model
The basic model of GroupDAV is that of WebDAV [3]. Leaf resources
which contain the groupware records can be grouped in collections.
Collections itself can be grouped in a collections hierarchy. The
construction of the hierarchy is arbitary and has no specific
restrictions.
For GroupDAV we define a way to specify an entity specific collection
type (for example 'calendar folder') which allows for calendar or
addressbook discovery on the client.
A collection typed this way should only contain items of that
specific type. While it is allowed to contain items of other types,
the groupware client is only supposed to deal with items that match.
Note that the behaviour for items of other types is undefined, so you
cannot use that fact to store additional information in a 'hidden'
file inside a collection, some clients may pick them up and display
the files as documents.
Client SHOULD keep a local cache of the items retrieved from the
server and keep the HTTP ETag / If-Match headers to keep them in sync
with the server. Besides enabling the client for offline operation,
this also improves performance and scalability.
In the case of the reference implementation all data is stored and
worked upon locally which basically removes all online load from the
server and provides excellent scalability.
3. Typical GroupDAV Entities
The described mechanisms are mostly generic and apply to any WebDAV
resource. This draft suggest a way to work with entities which are
"typical" in real world clients and servers.
A lot of available clients expose those entities to the user:
o events
o tasks
o contacts
o journals
o mails
The authors agreed that a protocol which is supposed to easen the
development of client plugins and server APIs should provide a
generic solution for all the entities.
A special real world issue is that a lot of clients, including
Mozilla Calendar, KOrganizer and Apple iCal, treat events and tasks
as a single resource while a lot of servers export them as separate
collections. For example the OpenGroupware.org ZideStore server
exports two private calendar collections but only a single private
task collection.
This draft assumes that you only keep one entity per folder and
workaround that in the client (if necessary). Kontact choose to offer
a setting which allows the user to configure groups of folders.
3.1. Events
Events are represented as individual iCalendar VEVENT entities. The
resource stored on the server MUST contain a valid iCalendar file
containing exactly one VEVENT record.
Since collections on the server can contain private items of other
users, the user may only have access to the start and end time of an
event. Instead of creating a special permission for this case, the
server should deliver a valid iCalendar VFREEBUSY file containing
exactly one busy record.
The client should not allow VFREEBUSY items to be opened in an event
editor and the server MUST reject all write or deletion attempts to
such a resource with a 403 HTTP status code.
The MIME type for iCalendar event resources is text/calendar.
Example resource:
BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:-//OpenGroupware.org/ZideStore 1.3//
VERSION:2.0
BEGIN:VEVENT
CLASS:PRIVATE
STATUS:CONFIRMED
SUMMARY:KDE PIM Sprint
DTEND:20040930T100000Z
DTSTART:20040923T090000Z
TRANSP:OPAQUE
UID:skyrix://move//21520
CREATED:20030710T120000Z
LAST-MODIFIED:20041101T023931Z
DTSTAMP:20041104T195835Z
END:VEVENT
END:VCALENDAR
TODO: what happens to x-?
3.1.1. Recurring Events
Recurring events in general are hard and interoperability between
iCalendar clients is not ensured. Further, recurring events require
an attached timezone to properly evaluate recurrences crossing
daylight saving boundaries.
For example Kontact stores all events in UTC and evaluates
recurrences in the presentation layer which gives wrong results for
events in different timezones.
To complicate things quite a lot of servers (including
OpenGroupware.org) transform a recurrence to a set of individual but
connected events on creation. That is, the recurrence rule is usually
lost and those servers only allowed time restricted recurrences.
There are good reasons for doing recurrences this way which are out
of scope for this draft. The draft needs to deal with both setups to
provide real world interoperability.
As per this draft the server SHOULD allow all valid iCalendar
recurrence rules. If it does not support a recurrence rule the server
MUST signal the error using an appropriate error code.
The client can submit all valid iCalendar recurrence rules but it
MUST expect that the entity is split into multiple entities. It MUST
expect that the server returns an unsupported rrule error code. It
MUST expect that the rrule is lost in the storage.
TODO: add a field to signal that items are connected, add an
operation to delete all items of a sequence.
3.1.2. Alarms
Testing has shown that interoperability for iCalendar alarms is low.
Indeed it is open for discussion when alarms should be stored on the
server and when on the client. The user does not want to get the
alarm triggered by its local client and by the server, and by other
clients he is running on the same store at the same time.
Further, real world server support for alarms is very inconsistent.
Due to this reasons the client SHOULD store alarms locally and SHOULD
NOT transmit them to server. The server is MAY reject iCalendar
resources containing alarms but MUST signal that using a proper error
code.
3.2. Tasks
Tasks are represented as individual iCalendar VTODO entities. The
resource stored on the server MUST contain a valid iCalendar file
containing exactly one VTODO record.
The MIME type for iCalendar event resources is text/calendar.
Example resource:
BEGIN:VCALENDAR
PRODID:-//SKYRIX groupware server//NONSGML skyjobs2ical 1.0.0//EN
VERSION:2.0
METHOD:PUBLISH
BEGIN:VTODO
UID:skyrix:///10910
SEQUENCE:4
SUMMARY:test
DUE;VALUE=DATE:20040916
PERCENT-COMPLETE:0
STATUS:IN-PROCESS
CLASS:PUBLIC
PRIORITY:3
END:VTODO
END:VCALENDAR
TODO: what happens to x-?
3.2.1. Recurring Tasks
Recurring tasks are supported by few servers. Indeed recurring tasks
as per iCalendar leave a lot of open questions. For example iCalendar
only stores a single status per task while all tasks need to have
different completion status to be useful.
Clients SHOULD not post recurring tasks to the server. If they do
submit recurring tasks, they MUST expect a split of the task into
individual tasks and perform a proper state refresh.
3.2.2. Connected Tasks
Some clients (Kontact is in this category) allow for relationships
between tasks. A lot of servers imply a certain application specific
model on task relationships which often leads to a mismatch between
server and client in real world.
Servers MUST send an error code if the client posts a relationship it
cannot represent. The client MUST be able to handle such error codes.
3.3. Contacts
Contacts are represented as individual vCard entities. The resource
stored on the server MUST contain a valid vCard file containing
exactly one vCard record.
The MIME type for vCard contact resources is text/x-vcard.
Example resource:
BEGIN:vCard
VERSION:3.0
PRODID:-//OpenGroupware.org//LSAddress v5.1.19
PROFILE:vCard
N:Hess;Helge;;;
FN:Helge Hess
EMAIL;TYPE=internet,pref:helge.hess@opengroupware.org
NICKNAME:helge
UID:skyrix://move//10280
END:vCard
TODO: what happens to x-?
3.4. Journals
TODO. We currently do not specify a way to store Journals.
3.5. Mail
The draft currently leaves out email. It was considered to specify a
way to connect email servers using HTTP / WebDAV, similiar to the
HTTPMail effort used by Microsoft to connect Outlook to Hotmail.
Mail over HTTP would provide several interesting capabilities and
would streamline development of mail clients.
Yet, since the IMAP4 standard is already established and IMAP4 was
considered a viable mail protocol by all attendees, we decided to
leave out mail.
4. Handling of UIDs
The draft needs to deal with two kinds of identifiers, the URLs which
point to the resource and need to be unique and the iCalendar or
vCard UIDs embedded in the resource.
With GroupDAV the server is not required to parse the submitted
entity for a UID. Further the server is not required to keep the used
resource URL for new items. A server SHOULD preserve the UID
contained in a resource, but the client should be aware that not all
servers might allow for that (because they are a legacy system which
does not provide a storage for that identifier).
It is quite common that a server has its own way to identify the
items stored in the database. For RDBMS based servers this is usually
a primary key which is generated by a database sequence
(OpenGroupware.org is in this category).
So to avoid the storage of an additional identifier just for GroupDAV
the server is allowed to return a new URL for new items using the
Location header.
To allow the client to search for UIDs stored in the server, the
server would need to expose the UID as a WebDAV property for use in
DASL queries. While this is possible in some implementations (eg
OpenGroupware.org ZideStore) it would complicate basic
implementations significantly.
5. Operations
Below you find a set of common operations. Note that all operations
are built around the HTTP etag concept to ensure consistent updates
and to make synchronisation easier.
The server MUST properly support HTTP etags to be compliant with this
draft. The client MUST store the etag as opaque data and is not
supposed to parse the value (eg for revision comparisons).
The server MUST deliver strong etags since the tags are to be used in
if-match headers (which in turn requires strong etags).
Construction of an etag is easy for all servers. Either the server
keeps a sequence number which is increased in the storage on each
change (this is the case for OpenGroupware.org) or the server uses a
last-modified date to signal changes.
Note that the latter approach (based on modification dates) should be
avoided if the server only supports date granularity of one second.
Most servers can perform several hundred updates in one second so
etags based on utime moddates will not be unique enough. Such a large
amount of updates is perfectly common not only in large installations
but also in synchronization of PDA devices.
To lower the XML overhead on the network the server and the client
SHOULD support the gzip or deflate content-encoding. The client
signals that it can process compressed responses using the usual HTTP
Accept-Encoding header.
5.1. Listing Items in a Collection
Retrieving all items of a collection is done using the regular WebDAV
PROPFIND operation. The server SHOULD support a PROPFIND <allprop/>
query. The server MUST only support a PROPFIND query on the
DAV:getetag property (to avoid the requirement for a full WebDAV
implementation). The server MAY support arbitary other properties and
SHOULD provide a full WebDAV implementation.
The draft is designed with clients that use an offline cache in mind.
On synchronisation such clients need to perform an efficient set
comparison operation to find out what items where changed, what items
where created or deleted in the server and what items where created
or deleted on the client.
Implementors of this draft are expected to use the DAV:href element
and the DAV:getetag properties to accomplish that.
Note that the list response might include collection resources. Those
are not relevant for item processing and can be silently dropped by
the client.
Example Request:
PROPFIND /groupdav/Calendar/ HTTP/1.1
Authorization: Basic abcABCbase64
Content-Length: 12345
Content-Type: text/xml; charset=utf-8
Accept: text/xml
Depth: 1
Host: move
User-Agent: Kontact/3.4
<?xml version="1.0" encoding="utf-8"?>
<propfind xmlns="DAV:"><prop><getetag/></prop></propfind>
Example Response:
HTTP/1.0 207 Multi-Status
Server: SOPE 4.2/WebDAV
Content-Length: 12345
Content-Type: text/xml; charset=utf-8
Content-Encoding: identity
Date: Thu, 04 Nov 2004 19:14:02 GMT
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>http://move/groupdav/Calendar/21520</D:href>
<D:propstat>
<D:prop><D:getetag>"21520:3"</D:getetag></D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>http://move/groupdav/Calendar/21530</D:href>
<D:propstat>
<D:prop><D:getetag>"21530:9"</D:getetag></D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
Conforming clients MUST NOT use the DAV:getlastmodified property for
synchronisation. If the server only supports last modified dates to
track changes, it MUST encode the date in the etag.
5.2. Retrieving Items
The client can retrieve items using the HTTP GET action on the URL of
the resource as retrieved using the PROPFIND list query. Clients
SHOULD NOT expect that the URL of the item is on the same hosts like
the URL of the folder!
The server MUST send the etag associated with the response. This
ensures a consistent etag in the client since the server does not
guarantee that the store does not change between the PROPFIND and the
follow up GET operations!
The server MUST send a proper HTTP 404 status if the resource was
removed from the storage.
The client SHOULD send a proper Accept HTTP header to ensure proper
content negotiation in the server. Eg the OpenGroupware.org ZideStore
server is able to represent a resource in a variety of representation
which it selects based on the user agent.
The server MUST return a proper content type for the resource. The
client SHOULD ignore responses for content types it does not expect
(eg if a folder contains maintenance resources of different types).
Example Request:
GET /groupdav/Calendar/21520 HTTP/1.1
Authorization: Basic abcABCbase64
Content-Length: 0
Accept: text/calendar
Host: move
User-Agent: Kontact/3.4
Example Response:
HTTP/1.0 200 Ok
Server: SOPE 4.2/WebDAV
Content-Length: 12345
Content-Type: text/calendar; charset=utf-8
Content-Encoding: identity
Date: Thu, 04 Nov 2004 19:14:02 GMT
ETag: "21520:3"
BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:-//OpenGroupware.org/ZideStore 1.3//
VERSION:2.0
BEGIN:VEVENT
CLASS:PRIVATE
STATUS:CONFIRMED
SUMMARY:KDE PIM Sprint
DTEND:20040930T100000Z
DTSTART:20040923T090000Z
TRANSP:OPAQUE
UID:skyrix://move//21520
CREATED:20030710T120000Z
LAST-MODIFIED:20041101T023931Z
DTSTAMP:20041104T195835Z
END:VEVENT
END:VCALENDAR
A bulk operation using a DASL query is also considered. Bulk
operations usually fit servers which use an RDBMS very well since
they can run efficient set queries and only need to open a single
database transaction per request.
On the other side a bulk operation can run slower and saturate or
block a server for other clients.
The reference implementation currently uses individual GET operations
which are easier to implement. It is not considered a performance
issue since only the initial fill of the offline cache results in a
large number of fetches.
5.3. Deleting Items
Deletion uses the standard DELETE method. The client SHOULD specify
an If-Match header containing the etag which represents the state of
the resource when the client did the last fetch. If the deletion
fails, the clients knows that someone else has changed the resource
on the server and can show an appropriate conflict panel (after
refreshing the etag of the updated resource).
In case a resource was deleted by someone else on the server and on
the client, the client will receive an HTTP 404 status on the attempt
to delete the resource. Which can be ignore, since the state is
consistent.
Example Request:
DELETE /groupdav/Calendar/21520 HTTP/1.1
Authorization: Basic abcABCbase64
Content-Length: 0
Host: move
User-Agent: Kontact/3.4
If-Match: "21520:3"
Example Successful Response:
HTTP/1.0 204 No Content
Server: SOPE 4.2/WebDAV
Content-Length: 0
Date: Thu, 04 Nov 2004 19:14:02 GMT
Example Failed Response (resource changed in the meantime):
HTTP/1.0 412 Precondition Failed
Server: SOPE 4.2/WebDAV
Content-Length: 0
Date: Thu, 04 Nov 2004 19:14:04 GMT
Example Failed Response (resource was deleted on the server):
HTTP/1.0 404 Not Found
Server: SOPE 4.2/WebDAV
Content-Length: 0
Date: Thu, 04 Nov 2004 19:14:04 GMT
5.4. Creating Items
The HTTP PUT operation is used to create new items. To ensure that a
new item is created and that an existing item is not overridden, the
client SHOULD specify the If-None-Match header with a wildcard (*)
value. This ensures that the request only succeeds if the resource
does not exists (otherwise any etag would match the wildcard).
The client MUST refresh the list after a PUT to account for side
effects in the server, like the flattening of a recurrence rule.
In case the server stores the new resource under a different URL, the
server MUST specify the new location in the PUT response using the
HTTP Location header.
That way the server can enforce its own resource naming scheme and is
often used by RDBMS based servers which rely on a sequence to
generate object identifiers (OpenGroupware.org is in this category).
To ensure proper storage the client MUST specify the correct content
type of the resource to be created.
Example Request:
PUT /groupdav/Calendar/8271-1281-2871-2712.ics HTTP/1.1
Authorization: Basic abcABCbase64
Content-Length: 12345
Content-Type: text/calendar; charset=utf-8
Host: move
User-Agent: Kontact/3.4
If-None-Match: *
BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:-//OpenGroupware.org/ZideStore 1.3//
VERSION:2.0
BEGIN:VEVENT
CLASS:PRIVATE
STATUS:CONFIRMED
SUMMARY:KDE PIM Sprint
DTEND:20040930T100000Z
DTSTART:20040923T090000Z
TRANSP:OPAQUE
UID:8271-1281-2871-2712
CREATED:20030710T120000Z
LAST-MODIFIED:20041101T023931Z
DTSTAMP:20041104T195835Z
END:VEVENT
END:VCALENDAR
Example Response:
HTTP/1.0 201 Created
Server: SOPE 4.2/WebDAV
Content-Length: 0
Date: Thu, 04 Nov 2004 19:14:02 GMT
Location: http://move//groupdav/Calendar/21540
5.5. Changing Items
The HTTP PUT operation is used to change existing items. To ensure
that a modification does not overwrite a modification by a different
user the client SHOULD specify the If-Match header with the etag of
the resource state the client modification is based on. This implies
that the client needs to store the etag when retrieving the resource.
This is only specified as SHOULD because the precondition processing
complicates the server and the override mode is often considered
sufficient.
The client SHOULD refresh the list after a PUT to account for side
effects in the server (like recurrence rule processing).
To ensure proper storage the client MUST specify the correct content
type of the resource to be created.
Example Request:
PUT /groupdav/Calendar/21520 HTTP/1.1
Authorization: Basic abcABCbase64
Content-Length: 12345
Content-Type: text/calendar; charset=utf-8
Host: move
User-Agent: Kontact/3.4
If-Match: "21520:3"
BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:-//OpenGroupware.org/ZideStore 1.3//
VERSION:2.0
BEGIN:VEVENT
CLASS:PRIVATE
STATUS:CONFIRMED
SUMMARY:KDE PIM Sprint
DTEND:20040930T100000Z
DTSTART:20040923T090000Z
TRANSP:OPAQUE
UID:skyrix://move//21520
CREATED:20030710T120000Z
LAST-MODIFIED:20041101T023931Z
DTSTAMP:20041104T195835Z
END:VEVENT
END:VCALENDAR
Example Response:
HTTP/1.0 204 No Content
Server: SOPE 4.2/WebDAV
Content-Length: 0
Date: Thu, 04 Nov 2004 19:14:02 GMT
6. Locking
The WebDAV specification allows the server to implement locking
using the LOCK and UNLOCK method. This is not required for GroupDAV
servers and clients should not rely on that being available.
GroupDAV clients and servers ensure storage consistency using ETag
and the If-Match HTTP headers, that is, they use an optimistic
locking approach.
This approach was choosen because WebDAV locks require tracking of
locks in the storage or in a session which makes the server
significantly more complex. Further locks reduce concurrency and
therefore scalability and require multiple HTTP transactions.
The etag approach matches the RDBMS transaction concept very well
(servers can SELECT the etag and primary key and a subsequent UPDATE
will only succeed if the transaction is still valid).
7. Folder Discovery
Most clients allow the user to browse a hierarchy of folders which
contain groupware resources on the server. GroupDAV uses a custom
DAV:resourcetype tag to signal the specific type of a folder.
This information can be used to display an appropriate icon for
calendar or task folders. In addition it can be used in the user
interface to preselect a default editor for new items (eg the event
editor for event folders).
Note that the folder discovery can be client and server specific.
Besides discovery the WebDAV collection hierarchy has no operational
effect on the storage processing of GroupDAV which is limited to one
WebDAV collection.
The additional resource type tag should not break valid WebDAV
clients. Yet interoperability testing showed that at least the Apple
WebDAV filesystem breaks on the additional tag. Cadaver did not and
neither did the KIO WebDAV slave.
7.1. Event Folders
Event folders, folders containing vcalendar resources which contain
exactly one vevent, are tagged using the
"{http://groupdav.org/}vevent-collection" resource type.
Example:
<resourcetype xmlns="DAV:" xmlns:G="http://groupdav.org/">
<collection />
<G:vevent-collection />
</resourcetype>
7.2. Task Folders
Task folders, folders containing vcalendar resources which contain
exactly one vtodo, are tagged using the
"{http://groupdav.org/}vtodo-collection" resource type.
Example:
<resourcetype xmlns="DAV:" xmlns:G="http://groupdav.org/">
<collection />
<G:vtodo-collection />
</resourcetype>
7.3. Contact Folders
Contact folders, folders containing a resource which is exactly one
vcard record, are tagged using the
"{http://groupdav.org/}vcard-collection" resource type.
Example:
<resourcetype xmlns="DAV:" xmlns:G="http://groupdav.org/">
<collection />
<G:vcard-collection />
</resourcetype>
8. Folder Management
The draft currently does not specify a way to manage folders. It
should be considered that for some servers the WebDAV folder tree
is just a view on the server database and does not necessarily exist
physically.
Due to this the WebDAV MKCOL operation is not required to work on
such servers and should be reported as unsupported using the usual
WebDAV mechanisms.
9. Error Codes
TODO: specify the error codes.
o recurrence rule unsupported
o recurrence rule produces too many entities
o could not parse timezone
o alarm not supported
10. FreeBusy Support
There are two basic approaches to implement freebusy in servers. Some
servers (like OpenGroupware.org) provide an URL entry point which is
able to generate a vfreebusy entity for a calendar on the fly.
Other servers rely on the client to create a vfreebusy and publish
that to a specific URL using HTTP PUT.
GroupDAV has no specific support for freebusy resources. We suggest
that the server SHOULD provide an URL to retrieve the freebusy
records of an account.
11. TimeZone Issues
Work in the OSAF icalsify list has shown a lot of misunderstanding
what exactly timezones are in the scheduling/iCalendar context and
when and why timezones are necessary and keeping dates in UTC is
insufficient.
TODO: explain.
12. Optional DASL Query for Bulk Fetch
As mentioned in the GET operation description it would be useful if
the server would provide a way to fetch multiple items in a single
fetch operation. Unfortunately this is not covered in the basic HTTP
specification (it does provide TCP socket keep alive though, remember
that the considered overhead is not the TCP connect overhead but the
transaction overhead in RDBMS based servers).
The Exchange WebDAV API solves the issue by adding a new HTTP method
called BPROPFIND (as well as BPROPPATCH, BDELETE etc). In GroupDAV we
tried to avoid that.
Servers MAY implement the query. It is optional and a lot of servers
will not implement it since a DASL implementation is a significant
amount of additional work. A server MUST return a 501 (method not
implemented) if the DASL query cannot be run. The client then MUST
resort to use separate HTTP operations to accomplish the same effect.
It might be tempting to use a simple GET on a single iCalendar file
containing all appointments since this is already implemented by a lot
of clients. Note that this approach MUST NOT be used by a GroupDAV
server to fetch data since the client needs to associate an etag with
each resource for consistent updates and synchronisation.
TODO: it is recommended to use the <or/> even for a single item because
server might not understand full DASL
Example Request:
SEARCH /groupdav/Calendar/ HTTP/1.1
Authorization: Basic abcABCbase64
Content-Length: 12345
Content-Type: text/xml; charset=utf-8
Accept: text/xml
Depth: 1
Host: move
User-Agent: Kontact/3.4
<?xml version="1.0"?>
<searchrequest xmlns:D="DAV:" xmlns:G="http://groupdav.org/">
<basicsearch>
<select><prop><getetag /><G:vcalendar /></prop></select>
<from><scope><href /><depth>1</depth></scope></from>
<where>
<or>
<eq><prop>
<href>http://move/zs/dav/helge/Calendar/21520</href>
</prop></eq>
<eq><prop>
<href>http://move/zs/dav/helge/Calendar/21530</href>
</prop></eq>
</or>
</where>
</basicsearch>
</searchrequest>
Example Response:
HTTP/1.0 207 Multi-Status
Server: SOPE 4.2/WebDAV
Content-Length: 12345
Content-Type: text/xml; charset=utf-8
Content-Encoding: identity
Date: Thu, 04 Nov 2004 19:14:02 GMT
<?xml version="1.0" encoding="utf-8"?>
<multistatus xmlns="DAV:" xmlns:G="http://groupdav.org/">
<response>
<href>http://move/groupdav/Calendar/21520</href>
<propstat>
<prop>
<getetag>"21520:3"</getetag>
<G:vcalendar>
BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:-//OpenGroupware.org/ZideStore 1.3//
VERSION:2.0
BEGIN:VEVENT
CLASS:PRIVATE
STATUS:CONFIRMED
SUMMARY:KDE PIM Sprint
DTEND:20040930T100000Z
DTSTART:20040923T090000Z
TRANSP:OPAQUE
UID:skyrix://move//21520
CREATED:20030710T120000Z
LAST-MODIFIED:20041101T023931Z
DTSTAMP:20041104T195835Z
END:VEVENT
END:VCALENDAR
</G:vcalendar>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
<response>
<href>http://move/groupdav/Calendar/21530</href>
<propstat>
<prop>
<getetag>"21530:3"</getetag>
<G:vcalendar>
BEGIN:VCALENDAR
METHOD:REQUEST
PRODID:-//OpenGroupware.org/ZideStore 1.3//
VERSION:2.0
BEGIN:VEVENT
CLASS:PRIVATE
STATUS:CONFIRMED
SUMMARY:OGo Meeting
DTEND:20040930T200000Z
DTSTART:20040923T130000Z
TRANSP:OPAQUE
UID:skyrix://move//21530
CREATED:20030710T120000Z
LAST-MODIFIED:20041101T023931Z
DTSTAMP:20041104T195835Z
END:VEVENT
END:VCALENDAR
</G:vcalendar>
</prop>
<status>HTTP/1.1 200 OK</status>
</propstat>
</response>
</multistatus>
13. Property Promotion and DASL Queries
The basic protocol does not require the server to promote selected
values of an item as WebDAV properties. This is a difference to other
approaches like CalDAV and restricts functionality. Property
promotion of values like startdate and enddate of a vevent is
especially important for thin clients, eg web interfaces which do not
keep state.
As an example a webpage displaying a week of events should be allowed
to perform a DASL query to select only the events of that week.
That HTTP / WebDAV / DASL already provide specified protocols for
that functionality is actually a major advantage over IMAP4 based
approaches which require the client to always retrieve the full
collection contents.
Since the implementation of a server which implements the described
functionality is not trivial and only significant for a certain class
of applications, this was left out of this draft.
14. Authentication
GroupDAV clients MUST use regular HTTP authentication. Clients and
servers SHOULD allow HTTPS connections to ensure secure transmittion
of basic authentication information.
Servers MUST support basic authentication and are not required to
support any other authentication scheme.
15. Access Control
When working with items in the store, all the available HTTP access
control mechanisms apply. When attempting a PUT or DELETE the server
MUST respond with the HTTP status 403 (Forbidden) to signal that the
client has no write or delete access on the requested resource.
The same goes for missing read access which should return a 403
status.
As a special case, we discussed the use of VFREEBUSY entities to
represent events which only allow access to the time and participant
(a private appointment in the OpenGroupware.org context).
Currently the draft does not specify how to retrieve or change
permissions on GroupDAV items. The obvious choice seems the be the
proposed IETF standard for WebDAV access control [6].
TODO: add readonly proposal from Bugzilla.
16. Server Change Notifications
The spec does not yet specify a way to trigger client refreshes from
the server. This capability would significantly increase the
complexity of servers and is therefore considered out of scope.
Options for server based notifications include the HTTP SUBSCRIBE
mechanism as available in the Exchange WebDAV API as well as using
the XMPP protocol which seems to be favored by the CalDAV effort.
17. Other Protocols
Since the Kontact client already supports a wide range of existing
servers the KDE team brought in experience with a lot of available
server protocols. This includes the Exchange WebDAV protocol, the
SOAP protocol used by Novell Groupwise, an XML-RPC based protocol
specific to a PHP groupware solution, an IMAP4 based storage protocol
and finally another solution XML protocol specific to some Java
server.
None of the existing protocols was considered suitable for a protocol
supposed to provide interoperability between multiple servers and
clients. The SOAP, XML-RPC and pure XML based protocols are too
specific for a certain server while the IMAP4 one is rather exotic
and has several issues which are out of scope for a discussion in
this document.
The simplistic iCalendar-over-HTTP approach as currently supported by
most clients, including Apple iCal, Mozilla Calendar and KOrganizer
does not provide sufficient granularity to catch conflicts and report
per event errors.
CalDAV is an interesting effort to extend WebDAV with full scheduling
capabilities. The hope of the authors is to have GroupDAV and CalDAV
as complementary protocols.
18. Security Considerations
All HTTP security and authentication solutions apply for GroupDAV.
Client should support HTTPS to ensure a secure transport.
TODO: collect more issues / infos.
19. Namespace Registration
GroupDAV currently uses the "http://groupdav.org/" XML namespace.
20. Normative References
[1] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[2] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999.
[3] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D. Jensen,
"HTTP Extensions for Distributed Authoring -- WEBDAV", RFC
2518, February 1999.
[4] Dawson, F. and Stenerson, D., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)", RFC 2445,
November 1998.
[5] Reschke, J., Reddy, S., Davis, J. and A. Babich, "WebDAV
SEARCH", draft-reschke-webdav-search-06 (work in progress),
August 2004.
[6] Clemm, G., Reschke, J., Sedlar, E. and J. Whitehead, "Web
Distributed Authoring and Versioning (WebDAV) Access Control
Protocol", RFC 3744, May 2004.
[7] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring and
Scheduling Extensions to WebDAV (CalDAV)", draft 03, October
2004
Authors' Addresses
Helge Hess
OpenGroupware.org
Universitaetsplatz 12
39104 Magdeburg
Germany
EMail: helge.hess@opengroupware.org
Appendix A. Acknowledgements
Till Adam, Marcus Mueller, Cornelius Schumacher and Helge Hess worked
on the proof of concept implementation using the Kontact client and
the OpenGroupware.org server.
Julian Reschke for reviewing the draft.
Martijn Van Beers for pointing out issues.
Appendix B. Changes
B.1 Changes in -01
2005-03-12:
- fixed content-type elements to explicitly specify the charset
- fixed title of 5.1
2005-03-11:
- fixed ordering of propstat result elements
2005-01-24:
- changed example URLs not to use ZideStore specific URLs
TODO: do we need a section on URLs?
- fixed a typo in 01-C01, S 5
- fixed etag values (value must be in quotes)
- fixed WebDAV locking, WebDAV does not require locking
- removed comment about open RDBMS transactions in the context of
WebDAV locking (which has no transactional semantics)
- fixed that WebDAV ACL is a proposed standard, not a draft
- use "http://groupdav.org" namespace instead of "GROUPWARE:"
- added requirement for strong etags
- properly refer to DAV:href as an 'element' (was: 'property')
2005-01-07:
- fixed mime types of text/vcalendar => text/calendar
Initial document based on the experiences from the KDE/OGo sprint
2004/10.
