2005-12-30

ZideStore & Free/Busy

Zidestore, the OpenGroupware integration server, can provide free/busy information for groupware users to clients via an HTTP request; this information can be provided in iCal VFREEBUSY format or in XML (Exchange's free/busy "map" format).

This information has now been integrated into WMOGAG.

The free/busy information request URL is: "http://{server:port}/zidestore/so/freebusy".

The data returned depends upon the parameters passed this this request. Both XML and iCalendar requests support "start" and "end" parameters which determine the date range of the free/busy information returned to the client. The date values must be presented in "%Y%m%dT%H%M00Z" form. The date "December 21st, 2005" would be written as "2005-12-21", if you wished to indicate a time (say 5:00pm) as well as a date you would specify "2005-12-21T17:00:00". Both the hour and minute are relevant to the data returned but the seconds field, while it must be specified, is discarded. The specified time must be in GMT, ZideStore does not appear to support specifying a timezone within the parameter (something like: "2005-12-21T17:00:00-10:00").
If no time is specified then the GMT time of "00:00:00 is assumed for both start and end. So a query for an iCalender free/busy with a start and end of: "start=2005-12-20&end=2006-01-15" returns a VFREEBUSY with a DTSTART of "20051220T000000Z" and a DTEND of "20060228T175600Z".

If no start and end time is specified then 121 days of free/busy information is returned, sixty days previous to the current date and sixty days forward from the current date. For instance, if the current date is 2005-12-29 then the free/busy information from 2005-10-29 through 2006-02-28 is returned. If only a start date is specified then from that day through 60 days forward from the current date is returned. If only an end date is specified then from 60 days previous to the current date through that date is returned.

For an iCalendar format response format the name of the user for which you desire free/busy information into two parameters: "name" as the left part of the e-mail address and "server" as the right, or domain, portion of the e-mail address. The username specification for an iCalendar request will look like "name=awilliam&server=whitemice.org" for a user whose e-mail address is "awilliam@whitemice.org". So the request for free/busy information for this user would look like: "http://{server:port}/zidestore/so/freebusy?name=awilliam&server=whitemice.org&start=2005-12-01&end=2006-01-15"

An iCalendar Free/Busy response will look something like:
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//OpenGroupware.org/ZideStore 1.3//
BEGIN:VFREEBUSY
ORGANIZER:MAILTO:adam@morrison-ind.com
ATTENDEE:MAILTO:adam@morrison-ind.com
DTSTAMP:20051229T181800Z
DTSTART:20051201T000000Z
DTEND:20060115T000000Z
FREEBUSY;FBTYPE=BUSY:20051201T203000Z/20051201T213000Z
FREEBUSY;FBTYPE=BUSY:20051206T212000Z/20051206T220000Z
FREEBUSY;FBTYPE=BUSY:20051207T000000Z/20051207T020000Z
FREEBUSY;FBTYPE=BUSY:20051208T210000Z/20051208T220000Z
FREEBUSY;FBTYPE=BUSY:20051214T000000Z/20051214T020000Z
FREEBUSY;FBTYPE=BUSY:20051214T160000Z/20051214T193000Z
FREEBUSY;FBTYPE=BUSY:20051216T110000Z/20051216T130000Z
FREEBUSY;FBTYPE=BUSY:20051220T050000Z/20060101T235900Z
FREEBUSY;FBTYPE=BUSY:20051221T000000Z/20051221T020000Z
END:VFREEBUSY
END:VCALENDAR


For an XML response format the username as a parameter named "u" with a value of the accounts e-mail address, like "u=awilliam@whitemice.org". The XML format request also supports an "interval" parameter. Interval specifies the resolution of the response in minutes and if not specified defaults to 30. A request for XML free/busy information for this user would look like: "http://{server:port}/zidestore/so/freebusy?u=awilliam@whitemice.org&start=2005-12-01&end=2006-01-15&interval=30"

An XML Free/Busy reponse will look something like:

<a:response xmlns:a="WM">
<a:recipient>
<a:item><a:displayname>adam@morrison-ind.com</a:displayname><a:email type="SMTP">adam@morrison-ind.com</a:email><a:type>1</a:type><a:fbdata>000000000...</a:fbdata></a:item>
</a:recipients

In the XML response the "item" tag encloses the information as to whom the encoded free/busy information applies, and the "fbdata" encloses the free/busy map. The "item" is enclosed in "recipient" tags and both the free/busy map ("fbdata") and "recipient" are enclosed in "response" tags. Each character in the "fbdata" represents an interval of the prescribed length. A value of "0" indicates that the interval is free while a value of "2" is used by ZideStore to indicate that the interval is busy. According to the specification (Microsoft article 813268) this is not entirely correct as "2" should indicate tentative and "1" should indicate busy ("3" indicates "Out Of Office" and "4" indicates "Data not available").

The username for a free/busy request must be the first or primary e-mail address ("email1"). For example my "email1" is "adam@morrison-ind.com" and my "email2" is "awilliam@whitemice.org". Requesting "name=adam&server=morrison-ind.com" or "u=adam@morrison-ind.com" works while "name=awilliam&server=whitemice.org" or "u=awilliam@whitemice.org" does not.

If the "u" parameter or "name" and "server" parameters do not resolve to a known user an error does not occur, but either a 'blank' VFREEBUSY (no FREEBUSY lines) or entirely free fbdata map is returned. An incorrectly structured URL where the server cannot determine the username to search for results in XML format free/busy information for the currently authenticated user. For example both "?user=fred&server=morrison-ind.com&start=2005-12-01&end=2006-01-15" ("user" instead of "name") or "ud=fred@morrison-ind.com&start=2005-12-01&end=2006-01-15" ("ud" instead of "u") will result in XML free/busy data for the currently authenticated user.

Note:This document is derived from Helge Hess' Free/Busy page in the OpenGroupware documentation plone.