Chapter 9   Web Calendar Access Protocol (WCAP) Overview


This chapter describes the Web Calendar Access Protocol (WCAP) 2.0, which is a high level command-based protocol that clients use to communicate with iPlanet Calendar Server 5.0. This chapter has the following sections:

• Introduction

• What's New in This Version

• Command Overview

• Command Formats

Introduction

---

The default Client UI protocol for iPlanet Calendar Server 5.0 is now SHTML (see the "iPlanet Calendar Express Customization Guide" for a detailed description of the new protocol). However, you may choose to use WCAP for compatibility with your previously customized Calendar Express clients. WCAP continues to support the iPlanet Calendar Server 2.0 protocol.

WCAP is a command based system consisting of client requests and server responses for transmitting calendaring data. WCAP 2.0 returns calendaring data via HTTP. In most cases, iPlanet Calendar Server 5.0 receives data through URL-encoded arguments.

WCAP 2.0 returns output in an HTTP message. The returned content body of the HTTP messages can consist of calendar data in the following formats:

• text/calendar format (iCalendar).

• text/xml format.

  This XML format follows the iCalendar DTD.

• text/js with embedded JavaScript objects.

  This was the default for the iPlanet Calendar Server 2.0 user interface. It has been deprecated for iPlanet Calendar Server 5.0 in favor of the .shtml approach.

WCAP 2.0 commands consist of four general categories of usage:

• User Configuration Information

• Web Calendaring Data

• Communication-sending for group scheduling

• Miscellaneous commands

What's New in This Version

---

The following four commands are new to this version:

• check_id

  Allows administrators to check if session is still valid.

• fetchcomponents_by_alarmrange

  Queries for components that have alarms to trigger over a specific time period.

• fetchcomponents_by_attendee_error

  Queries for components that had errors while sending group scheduling messages.

• get_freebusy

  Returns calendar freebusy time.

Four new parameters were added to existing commands:

• acl

  Added to set_calprops to record ACE strings for access control. For more information on access control entries, see Chapter 10 "WCAP Commands.

• alarmAudio

  Added to storeevents and storetodos to enable audio reminders.

• alarmFlashing

  Added to storeevents and storetodos to enable flashing reminders.

• alarmPopup

  Added to storeevents and storetodos to enable popup dialog reminders.

• compstate

  For all fetch commands, compstate allows you to fetch by component state. userid

  For get_userprefs and set_userprefs, administrators can retrieve and set any user's preferences.

• convertCalid

  In set_userprefs, to allow setting the subscribed list of calendars (icsSubscribed), and the subscribed list of groups (icsSet).

• method

  For group scheduling, the storeevents and storetodos commands contain an additional parameter, method, which specifies the ITIP method.

One command has changed fundamentally in the way it works:

• set_calprops now works in update mode, rather than replace mode as in iPlanet Calendar Server 2.x. This means that you no longer have to specify every parameter in the command. You need only specify the parameters you wish to change. All other properties will remain unchanged by your update.

The existing parameter tzid has been added to the following existing commands:

• deleteevents_by_id

• deletetodos_by_id

• fetchcomponents_by_alarmrange

• fetchcomponents_by_lastmod

• fetchcomponents_by_range

• fetchevents_by_id

• fetchtodos_by_id

Existing parameter tzid has changed in two existing commands:

• storeevents

• storetodos

See also New in iPlanet Calendar Server 5.0 in Chapter 10 "WCAP Commands".

Command Overview

---

Table 9-1 describes the high level list of commands supported in WCAP 2.0. For a detailed description of each command, see Chapter 10 "WCAP Commands".

Table 9-1 WCAP Command Overview 

WCAP Command	Description
addlink	Add event links from one calendar to another.
change_password	Change the user's password.
createcalendar	Create a new calendar.
deletecalendar	Delete an existing calendar.
deletecomponents_by_range	Delete both events and todos in a calendar(s) over a specific time period.
deleteevents_by_id	Delete events given a specific calid and uid/recurrence-ID pair.
deleteevents_by_range	Delete events in a calendar(s) over a specific time period.
deletetodos_by_id	Delete todos given a specified calid and userid/recurrence-ID pair.
deletetodos_by_range	Deletes todos in a calendar(s) over a specific time period.
export	Exports a calendar to a file.
fetchcomponents_by_alarmrange	Queries for components that have alarms to trigger over a specific time period.
fetchcomponents_by_attendee_error	Queries for components that had errors while sending group scheduling messages.
fetchcomponents_by_lastmod	Queries for components that have changed, during the specified time range.
fetchcomponents_by_range	Queries for components over a specific time period, with filtering attributes.
fetchevents_by_id	Queries for one or more events by a unique identifier (UID, Recurrence ID, modifier).
fetchtodos_by_id	Queries for one or more todos by a unique identifier (UID, Recurrence ID, modifier).
get_all_timezones	Returns all the timezones the server supports.
get_calprops	Returns calendar properties.
get_freebusy	Returns calendar freebusy time.
get_guids	Returns a set of random UIDs.
get_userprefs	Returns user preferences and some server settings.
import	Imports a calendar from a file to a user's calendar.
login	Authenticates a user and redirects to first HTML view.
logout	Terminates the current user's session and return to login screen.
ping	Administrator only: Pings the calendar server.
search_calprops	Searches for a calendar with the specified parameter values.
set_calprops	Sets calendar properties.
set_userprefs	Sets user preferences.
storeevents	Stores events that are specified in application/urlencoded manner. For storing an even by passing properties in a URL.
storetodos	Stores todos that are specified in the application/urlencoded manner.
upload_file	Uploads a file to the server.
version	Returns the WCAP version that the server supports.
write_file	Writes a file to the database.

Session Identifiers

For many WCAP commands, you must specify the session identifier (id) that is returned by the login command. The session identifier ensures that data is accessible only to authenticated users with the required level of privilege or ownership.

When logging into the system, a user provides authentication of identity. The default authentication mechanism uses plain-text passwords and user names. iPlanet Calendar Server generates the session identifier only when authentication is successful. The identifier then serves as proof of authentication in subsequent calendaring operations.

You can customize the authentication mechanism to use a local or external authentication scheme. See Chapter 3 "CSAPI Reference", for the section csIAuthentication.

Command Formats

---

The plug-in architecture of iPlanet Calendar Server allows it to support multiple command formats. Both client and server can use a variety of data formats to meet various ISP needs.

The command protocol uses HTTP, and follows the standards defined by the WC3 URL specifications.

WCAP in iPlanet Calendar Server consists of JavaScript objects formatted as XML or iCalendar, communicated as HTML documents over HTTP on both the client and server side. The client supports version Internet Explorer 4.0 and above, and Navigator 4.05 and above.

Client Request Formats

Clients submit command requests to the iPlanet Calendar Server in either Universal Resource Identifier (URI) data format, or with an HTML form.

Command Format	Description
URI	Requests from client submitted using standard URI syntax.
HTML Form - urlencoded	Requests from client submitted using native JavaScript objects.
HTML Form - text/xml	Requests from client submitted using JavaScript objects formatted as XML.
HTML Form - text/calendar	Requests from client submitted using JavaScript objects formatted as iCalendar.

URI Format

Use the following format to submit a URI request:

http://webcalenderserver/COMMAND?PARAM=VAL&PARAM=VAL...

Multiple items are delimited by semicolons. If a string contains a semicolon character, replace the semicolon with its quoted-printable equivalent, %3B. For example, to represent the string "gh;i" in a list of IDs, use the following:

http://webcalendarserver/fetchcomponents_by_range.wcap?uid=abc;def; gh%3bi;jkl

---

Note	This is a change from WCAP 1.0 used in iPlanet Calendar Server 2.0. Previously, the quoted-printable equivalent for a semicolon was =3B.

---

See also Encoded Characters, in Chapter 10 "WCAP Commands".

HTML Form

Submit a form with method=[GET|POST] and action=command (where command is the command to execute). Parameters need to be formatted as specified in the encoding.

Client Side Event Notification

All client side JavaScript code in the parent frame of the response page is required to implement a method called CalcommandCallback(), where command is the name of the command requested. This callback will be invoked when the HTML response is completed loading.

The above commands when used with HTTP GET are simply for data retrieval.

The above commands when used with HTTP POST are for data modifications (including creation/deletion).

Server Response Formats

iPlanet Calendar Server responds to client requests by serving HTML containing JavaScript objects.You can configure a response format preference for a server, a user, or an individual request.

The client may request output in one of three different formats:

Response Format	Description
HTML with JavaScript objects - text/js	Responses are in HTML and contain JavaScript objects. This is the default output format for all WCAP commands.
HTML with JavaScript objects - text/calendar	Responses are in HTML, containing JavaScript formatted as iCalendar objects.
HTML with JavaScript objects - text/xml	Responses are in HTML, containing JavaScript formatted as XML objects