Chapter 2 Calendar Server WCAP Common Topics

This chapter contains topics of common interest that span multiple commands.

The topics are listed in alphabetical order. The table that follows lists and contains links to these topics:

• Calendar Access Control Information (ACI)

• Calendar appid Parameter for ENS X-Tokens

• Calendar Server WCAP Attachment Support

• Calendar Server WCAP Attendee Parameter

• Changing Language or Character Set for Calendar Server WCAP

• Calendar Server WCAP Encoded Characters

• Calendar Server WCAP Error Handling

• Fetching Component Data Using Calendar Server WCAP

• Fetching Component State Data Using Calendar Server WCAP

• Fetching Deleted Data Using Calendar Server WCAP

• Fetching Recurrence Data Using Calendar Server WCAP

• Formatting Standards for Calendar Server WCAP

• Free-Busy Calendars in Calendar Server WCAP

• Free-busy Calculation for Private Events in Calendar Server WCAP

• Output Format Used by Calendar Server WCAP

• Recurring Components in Calendar Server WCAP

• Sorting Order of Returned Events and Todos in Calendar Server WCAP

• Calendar Server WCAP Time Zones

• Updating Parameter Values in Calendar Server WCAP

• X-Tokens Used by Calendar Server WCAP

Calendar Access Control Information (ACI)

Access Control Information (ACI) determines access control for calendars. Access Control Entries (ACE strings) are individual strings of control characters that are stored in LDAP as one of a calendar's properties. There can be multiple ACE strings that apply to a single calendar. Collectively, all the ACE strings that apply to a calendar are called an Access Control List (ACL). When someone has requested access to a calendar, the system searches the calendar's ACL list to check for access rights. The system uses the first ACE encountered that either grants of denies access. Thus, the ordering of an ACL is significant. ACE strings should be ordered such that the more specific ones appear before the more general ones.

Some access is “built-in”. For example, primary owners have access to everything in their calendars. The system does not need to perform access control checks for primary owners accessing their own calendars.

The WCAP set_calprops.wcap command uses the acl parameter to facilitate storing of ACE strings to a calendar. The acl parameter is a semicolon-separated list of ACE strings. You can set the default acl in the ics.conf file by changing the calstore.calendar.default.acl preference, or by using the cscal command line utility.

The get_userprefs.wcap command fails if any node does not have “allow anyone” access rights for reading and searching. For example, the following LDAP modify record for an ACL entry gives the correct privileges to make the command work correctly.

dn:  o=usergroup
changetype: modify
add: aci
aci: (targetattr="icscalendar ||cn||givenName||sn||uid||mail")
     (targetfilter=(objectClass=icscalendaruser))
     (version 3.0; acl "Allow calendar administrators to proxy-product=ics,
      class=admin,num=2,version=1" allow (proxy) 
      groupdn="ldap:///cn=Calendar Administrators,ou=Groups,o=usergroup";)

Here is an example of an ACE string:

jdoe^c^wd^g

The string has four elements separated by three ^characters. The four elements are:

1. The first element of an ACE tells who the ACE applies to.

   This could be an individual user (specified by user ID), a domain, or a class-type of user. The four types of classes for users are the following:

   • All users, represented by the string “@”.

     • Primary owners of a calendar, represented by the string “@@p”.

     • Owners of a calendar, represented by the string “@@o”.

     • Non-owners of a calendar, represented by the string “@@n”.

2. The second element of an ACE indicates what the ACE applies to.

   The ACE can be applied to:

   • The entire calendar.

     Applies to both components and calendar properties. To indicate the entire calendar, pass in the value a.

     • The components only.

       Applies to calendar components, that is, events and todos. To indicate just the components, pass in the value c.

     • The calendar properties only.

       Applies to calendar properties, for example, display name, or ownerlist. To indicate calendar properties only, pass in the value p.

3. The third element of an ACE indicates what access values the ACE applies to.

   Multiple values can be specified at the same time. To do this, the caller must pass in a string to indicate which bits to check.

   The table that follows lists the Access Control characters used in ACE strings. The third element contains a string with one or more of the Access Control characters.

   Access Control Characters	Description
   d	Grants the user delete access.
   f	Grants the user free-busy access.
   r	Grants the user read access.
   s	Grants the user schedule access. This means that requests can be made, replies accepted, and other ITIP scheduling interactions honored.
   w	Grants the user write access. This includes adding new items, deleting items, and modifying existing items.

   For example, to grant read access, the value r is passed in. To grant write and delete access, the value wd is passed in.

4. The fourth element of an ACE indicates whether to grant or deny access.

   The ACE can either grant or deny access.

   • To grant access, set the value to g.

     • To deny access, set the value to d.

Calendar Access Control Entry (ACE) Summary

Here is a quick summary of the order of an ACE:

who ^ flags ^ how ^ grant

Where:

• who = A string, type (str).

• flags = One of the characters c, p, or a.

• how = An access-string composed of one or more of the access control characters described earlier in this topic.

• grant = One of the characters g, or d

An administrator can override the access control of all WCAP commands if he is logged in as administrator and the server configuration preference service.admin.calmaster.overrides.accesscontrol is set to “yes” in the ics.conf file.

Example 2–1 Examples

This section shows some examples of how the ACE would be set in the acl parameter for the jdoe calendar:

• To grant john read access to both components and calendar properties (acl=john a r g), and to grant susan write and delete access to components only (acl=susan c wd g), the entire command is:

set_calprops.wcap?id=${SESSIONID}
             &calid=jdoe&acl=john^a^r^g;susan^c^wd^g

• To grant all users in a domain schedule, free-busy, and read access to a calendar (@domainname a sfr g), to grant owners write and delete access to components only (@@o c wd g), to grant owners self-administration rights, and schedule, free-busy, and read access to both components and calendar properties (@@o a zsfr g), to deny susan all access to both components and calendar properties (susan a zsfdwr d), and to grant read access to all users (@ c r g), the entire command is:

set_calprops.wcap?id=${SESSIONID}&calid=jdoe
                                 &acl=@domainname^a^sfr^g;
                                      @@o^c^wd^g;
                                      @@o^a^zsfr^g;
                                      susan^a^zfsdwr^d;
                                             @^c^r^g

Mapping User Interface Operations to ACL's

Calendar appid Parameter for ENS X-Tokens

The following WCAP commands accept the appid parameter:

• deletecomponents_by_range

• deleteevents_by_id

• deleteevents_by_range

• deletetodos_by_id

• deletetodos_by_range

• import

• login

• storeevents

• storetodos

This WCAP command parameter is used to set the value of an X-Token that ENS returns with notifications.

Applications passing this parameter in with the appropriate WCAP command can detect which ENS notifications they originated by checking the value of the X-Token X-NSCP-COMPONENT-SOURCE. Note that this X-Token is not returned by WCAP commands, only ENS notifications.

This parameter is a runtime parameter. That is, nothing is stored in the database.

If appid is present, the Event Notification Service (ENS) returns the value of appid as the value of the X-Token X-NSCP-COMPONENT-SOURCE. If the appid parameter is missing, ENS assigns the standard value to the X-Token (WCAP).

The following table shows the effect of the presence of the appid parameter on the value of the X-Token X-NSCP-COMPONENT-SOURCE. For more information about ENS, see theSun Java Communications Suite 5 Event Notification Service Guide.

If you are using Sun Java System Message Queue instead of the Event Notification Service (ENS), refer to that product's documentation at:

http://docs.sun.com/coll/1307.2

Calendar Server WCAP Attachment Support

Attachments can be stored as part of an event using the storeevents command over the http post command. Attachment data resides in an internal data store events separate from the database where events and tasks are stored. Each attachment is assigned a unique ID, called an attachment ID. Events and tasks contain the attachment ID's rather than the actual attachment data. The following is a list of attachment features:

• All commands used to fetch events and tasks can take a fetchattach parameter. This parameter indicates whether or not to return actual attachments stored for the event or task, or return just the information about all the attachments, "0"for no attachments fetched, or "1" for returning specific attachments stored for the event or task.

  When the fetchattach parameter is passed in with a value of "0", WCAP emits the following kind of data:

  • X-S1CS-ATTACH-ID=attach-id

    The server-assigned ID of the attachment.

  • X-S1CS-CLIENT-ATTACH-ID=client-attach-id

    The client-specified ID of the attachment.

  • FMTTYPE=text/plain| image/jpeg

    The content type specified for the attachment.

  • X-S1CS-FILENAME=text.txt|pic.jpeg

  • http://fetchattachments.wcap?uid=uid&rid=rid&attach=attach-id

  The following is an example of the data returned by the fetch commands when you specify "0" as the value of the fetchattach parameter:

  ATTACH;X-S1CS-ATTACH-ID=attach-P001;
  FMTTYPE=image/jpeg
  X-S1CS-FILENAME=pic.jpeg
  :http://fetchattachments.wcap?uid=uid1&rid=rid1&attach-id=attach-P001

• There is a specific fetch command, fetchattachment.wcap, for fetching only the attachments for a particular event or task.

• Using the storeevents command, you can delete the attachments for an event, by sending the deleteattach parameter, without deleting the event.

• Attachments can be sent to attendees outside the Calendar Server deployment in an email as part of the iTIP invitation, depending on the value of the sendattach parameter, in the storeevents command. A value of "0" means do not send the attachment and a value of "1" means to send the attachment.

• The export command uses the fetchattach parameter to determine whether it should send a URL to an attachment ("0"), or the actual attachment itself ("1").

As part of the new attachment support model, the old attachment parameter has been deprecated. However, for backwards compatibility, it remains functional.

There are two parts that comprise the attachment support solution:

• Attachment store: Acts as a repository for storing the attached files.

• Calendar Server attachment support: Responsible for various tasks, which are required to store, fetch, act upon, and delete attachments.

Attachment Store

The attachment store acts as a repository for the Calendar Server attachments.

The following features encapsulate the functionality of the attachment store:

• Supports unique attachment ids for indexing and easy identification of the attachment. The id will be supplied by the store to guarantee uniqueness across applications.

• Holds reference to UID-RID of the event that the supplied file is attached to, possibly in the metadata.

• Uses hard links to depict multiple events/instances that point to the same attachment id.

• Provides APIs to the Calendar Server to store, delete, and fetch attachments.

• Provides a place holder for any meta data (for example, size of the file and name) that could be of use to the Calendar Server.

• Supports cleaning up of orphan attachments.

Life Cycle of Attachment in Calendar Server

The life cycle of an attachment explains the process of creating, sending, storing, and deleting an attachment from the Calendar Server. The following example illustrates the life cycle of an attachment by explaining the procedure to attach a file from your system and delete it in the Calendar Server:

1. Click the New Event link in the Calendar, to create a new event in the Communications Express.

   The New Event window opens up. You need to specify the event details such as Title, Start Time, End Time, Type, Privacy, people to invite and so on for the new event.

2. Click Add Attachment icon in the Attachments section, to add file as an attachment.

   The Attach File window opens up.

   1. Click the Browse button.

   2. Select the file that you want to attach from the File Upload dialog box.

   3. Click the Add icon to add the file in the attachments list.

      You can see the name and size of the file in the attachments list. You can add multiple attachments to the list by clicking the Browse button and selecting the required files. You can also delete the selected attachments from the list by clicking the Delete icon in the Action tab.

   4. Click the Attach icon to add the selected attachments in the Attachments list box in the New event window.

   5. Click the Save icon to save the attachment.

      The saved attachment is displayed as an event against the corresponding timing in the Calendar.

   Calendar Server issues storeevents.wcap command, which provides all the information about the attachment. Calendar Server stores the attachment file in the attachment store and keeps a reference to the attachment within the event structure. For more information on the storeevents command, refer the storeevents.wcap section.

3. Click the event at any point of time to view its details.

   Communications Express issues the fetchevents_by_id and provides the Calendar Server with all the information about the attachment. It also sends fetchattach=0. For more information on fetchevents_by_id command, refer the fetchevents_by_id.wcap section. In response to the fetchevents_by_id command, the server provides information about the attachment such as attachment id, size of attachment, URL to retrieve the attachment, client id if any was supplied, the file name of the original file attached and so on.

   The client displays the attachment in the form of a URL.

4. Click the URL to view the attached file.

   Communications Express issues fetchattachment.wcap command to the server. The server sends back the data about the attachment in the form of HTTP response.

5. Delete the attachment (at any point of time) from the event.

   Communications Express issues the storeevents command and supplies the deleteid parameter along with it. The deleteid parameter contains the ID of the attachment to be deleted. The server deletes the attachment from the back-end attachment store.

Calendar Server WCAP Attendee Parameter

• Calendar Server WCAP Attendee Overview

• Calendar Server Attendee Sub-Parameters

• Calendar Server WCAP Attendee: CUTYPE Parameter

• Calendar Server WCAP Attendee: Method Parameter

Calendar Server WCAP Attendee Overview

Each attendee entry can contain several sub-parameters, such as invitation participation status, whether attendance is required or not, whether the attendee is a group or not, and so forth. All such parameters are encapsulated in a syntax very similar to the ATTENDEE property defined in the iCalendar Specification (RFC 2445). Reading the entire document is recommended in order to have the necessary background information to understand the WCAP attendee syntax. Some differences exist, such as, WCAP uses a different delimiter, ^, to set apart these parameters. (However, WCAP uses the standard iCalendar semicolon delimiter for separating attendees.)

For example, where iCalendar would have the following:

PARSTAT=ACCEPTED;RSVP=TRUE:mailto:abc@xyz.com

WCAP would format it this way:

PARSTAT=ACCEPTED^RSVP=TRUE^mailto:abc@xyz.com

Calendar Server Attendee Sub-Parameters

The following table lists the parameters in the iCalendar ATTENDEE property understood by WCAP. Most of the parameters are optional. Not all are fully supported by Calendar Server, although the information is stored. For group scheduling, only the PARTSTAT and RSVP parameters are relevant.

In addition, WCAP allows the optional use of an additional parameter, SENT-STATUS, which is specific to Calendar Server and is not part of the iCalendar specification. Possible values for SENT-STATUS are: NOT-SENT, and SENT-SUCCEEDED. The default is NOT-SENT. The Group Scheduling Engine inside Calendar Server does not process an attendee with a SENT-STATUS value of SENT-SUCCEEDED.

Calendar Server WCAP Attendee: CUTYPE Parameter

If the attendee is an individual, set CUTYPE=INDIVIDUALin WCAP commands. If one of the attendees is a group, set CUTYPE=GROUP. An additional X-Token, X-S1CS-EXPAND, can be given to specify whether the group is to be expanded or not (TRUE, FALSE).

For example, for a storeevents command:

storeevents.wcap?id-$SEESSIONID&calid=testuser&dtstart=20060402T090000Z&
dtend=20060402T100000Z&method=2&attendee=PARSTAT=NEEDS_ACTION^RSVP=TRUE^
CUTYPE=GROUP^X-S1CS-EXPAND=TRUE^testgroup

When fetched, an expanded group invitation would return and individual record for each group member as well as a record for the group. For example:

ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL
 ;PARTSTAT=NEEDS-ACTION;CN="Test User1"
 ;RSVP=TRUE
 ;X-NSCP-ATTENDEE-GSE-STATUS=2
 ;X-S1CS-EMAIL=testuser1@test.com
 ;MEMBER=testgroup
 :testuser1

ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL
 ;PARTSTAT=NEEDS-ACTION;CN="Test User2"
 ;RSVP=TRUE
 ;X-NSCP-ATTENDEE-GSE-STATUS=2
 ;X-S1CS-EMAIL=testuser2@test.com
 ;MEMBER=testgroup
 :testuser2

X-S1CS-GROUP-ATTENDEE;CUTYPE=GROUP
 ;X-S1CS-EMAIL=testgroup@test.com
 ;X-S1CS-EXPAND=TRUE
 :testgroup

If the same group was invited in non-expanded mode, a fetch would result in only the group record being returned, as shown in the following example:

storeevents.wcap?id-$SEESSIONID&calid=testuser&dtstart=20060402T090000Z&
dtend=20060402T100000Z&method=2&attendee=PARSTAT=
NEEDS_ACTION^RSVP=TRUE^CUTYPE=GROUP^X-S1CS-EXPAND=False^testgroup

ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP
 ;PARTSTAT=ACCEPTED;CN="Test Group"
 ;RSVP=FALSE
 ;X-NSCP-ATTENDEE-GSE-STATUS=2
 ;X-S1CS-EMAIL=testgroup@test.com
 ;X-S1CS-EXPAND=FALSE
 :testgroup

If the EXPAND X-Token is not given in the WCAP command, the system will use the internal default, which is specified in the ics.conf parameter group.invite.expand. The request to expand might be overridden if the member size becomes greater than the value specified in the ics.conf parameter calstore.group.attendee.maxsize.

If the CUTYPE is not set in the command, the system will set CUTYPE internally when it discovers the whether the attendee is an individual or a group.

Calendar Server WCAP Attendee: Method Parameter

The method parameter describes the type of message used: invitation, response, cancellation.

When there are multiple attendee, specify one of the following ITIP methods:

In addition to these ITIP methods, there is another method used by Calendar Server internally (a non-ITIP method):

Even though the method parameter has a default value, it is a required parameter if you are trying to do anything other than PUBLISH. Leaving the parameter off the storeevents or storetodos commands causes the default (PUBLISH) to be the presumed action.

In an invitation, three types of messages can occur:

• An organizer invites attendees.

  When an organizer creates a meeting, there are two ways to invite people:

  • Send a PUBLISH message, creating or modifying a meeting. The method parameter is set to “1”. Note that everything except the attendee information is sent. (Attendees can see the event but not the other attendees.)

  • Send a REQUEST message, creating or modifying a meeting, and requesting a response to the invitation from attendees. The method parameter is set to “2”.

    Only the organizer of the meeting can send a PUBLISH or REQUEST message.

  Attendees respond to invitation.

  An attendee sends a REPLY message, either accepting or declining the invitation. (The method parameter is set to “4”.)

• Organizer cancels the meeting.

  When an organizer cancels a meeting, attendees are notified by sending a CANCEL using one of the deleteevents commands. The method parameter is set to “8”.

The preferred way to handle a cancellation is to use one of the deleteevents commands, rather than storeevents.

The following set of examples demonstrates the WCAP commands for an organizer “org” to invite attendees “attA” and “attB” to a meeting. Attendee “attA” accepts the invitation. Attendee “attB” declines the invitation. The uid for the meeting is “event_u1”. The event is created on both attendees’ calendars. Each responds to the event on their own calendar. The response is sent back to the organizer’s calendar by the Calendar Server Group Scheduling Engine.

The following is an example of an invitation:

storeevents.wcap?id=${SESSIONID of org}&calid=org
                  &dtstart=20020201T200200Z
                  &dtend=20020201T210000Z
                   summary=invite_attA_attB
                  &method=2
                  &attendees=PARTSTAT=ACCEPTED^RSVP=TRUE^org;
                             PARTSTAT=NEEDS-ACTION^RSVP=TRUE^attA;
                             PARTSTAT=NEEDS-ACTION^RSVP=TRUE^attB
                  &fmt-out=text/xml

The following is an example of the acceptance:

storeevents.wcap?id=${SESSIONID ofattA}&calid=attA
                  &uid=event_u1
                  &method=4
                  &attendees=PARTSTAT=ACCEPTED^RSVP=TRUE^attA
                  &fmt-out=text/xml

The following is an example of a declined meeting:

storeevents.wcap?id=${SESSIONID ofattB}&calid=attB
                  &uid=event_u1
                  &method=4
                  &attendees=PARTSTAT=DECLINED^RSVP=TRUE^attA
                  &comments=I_cannot_make_it_Sorry
                  &fmt-out=text/xml

Changing Language or Character Set for Calendar Server WCAP

To insert a request for data to be returned in a language other than the system default, set either the lang or charset parameter. Note that the system default for language is now a server preference that you set in the ics.conf file. See theSun Java System Calendar Server 6.3 Administration Guide for details. The login command uses only the lang parameter.

For the set_calprops command, in most cases, specifying the lang parameter is enough. However, it might be necessary, in some instances, to use the charset parameter instead of the lang parameter. For example, if the user wants the requested data returned in a specified character set, then the user must specify it using charset. One possible charset value is: iso-8859-1. For more information on formatting specifications, see the RFC's referenced in Formatting Standards for Calendar Server WCAP.

Please note that when the user requests data in iCalendar or XML format, data always returns in UTF-8 format, per the RFC specification. Setting charsetdoes not change this.

Here is a list of the valid lang values:

This does not mean that all of these languages are currently supported by the server. Please check with your Sun Java Enterprise System representative to find out which languages are currently supported by the server.

For example, enter the following if you want to insert an event into the calendar:

storeevents.wcap?id=${SESSIONID}&calid=id&summary=summary
                                &location=location
                                &desc=desc
                                &charset=euc-jp

As another example, suppose that the location value is two Japanese characters whose unicode values are \\u3068\\u30889. In this case, the location value is %A4%C8%A4%E9. Note that all non-ASCII characters should be URL-encoded according to the value of the charset parameter, which in this case is euc-jp. The following command is an example of same data sent in Shift_JIS:

storeevents.wcap?id=${SESSIONID}&calid=id
                                &summary=summary
                                &location=location
                                &desc=desc
                                &charset=Shift_JIS

In the above example, the location value is %82%C6%82%E7.

WCAP uses the value of the charset parameter to convert the data from the URL-encoded value into UTF-8 before storing it into the database. It is stored internally in UTF-8.

The charset parameter in this command have the same role as in the storeevents.wcap because the set_calprops command takes non-ASCII data. The charset parameter in this command does not have any other special meaning.

If charset is not specified, WCAP expects the data to be URL-encoded in UTF-8.

Calendar Server WCAP Encoded Characters

In the example, the encoded list of parameters for cal includes some encoded characters. Here are some examples of characters and their encoding:

The %xx string is the hexadecimal value of the character. For example, the & character is 26 in hexadecimal.

Calendar Server WCAP Error Handling

Each call to a WCAP command that returns component data (fetch, delete, and store commands) also returns an error number.

• Calendar Server WCAP Error String

• Calendar Server WCAP Error Codes

Calendar Server WCAP Error String

The error string, errno, returns the non-zero error number for the transaction. The value is 0 if the command succeeded.

Calendar Server WCAP Error Codes

This table lists error codes returned by WCAP commands.

Fetching Component Data Using Calendar Server WCAP

The component_type parameter directs WCAP to return either only events, only todos, or both events and todos. The keyword arguments, respectively, are: event, todo, or all. The parameter is not required. Its default is all, returning both events and todos. If an unrecognized value is passed in, the default value is used.

This parameter is found in all the fetchcomponents_by_* commands.

In addition, deleted components can be retrieved from the deletelog.db in the calendar store using the fetch_deletedcomponents command.

Fetching Component State Data Using Calendar Server WCAP

All fetch commands, except fetchcomponents_by_attendee_error, have the ability to fetch by component state, using the parameter compstate. The default (compstate=ALL) is to fetch all component states, Use this parameter to limit the type of components fetched.

If the parameter is not specified, the default value is ALL.

The following table lists component state values. A component state pertains either to the attendee or the organizer.

Fetching Deleted Data Using Calendar Server WCAP

If you have deleted component data and need to reconstruct it, you can use the fetch_deletedcomponents.wcap command, which causes the system to process the Delete Log Database (ics50deletelog.db in the csdb directory). However, it is not possible to recreate the entire component data since not all of it is logged.

When non-recurring components are deleted, the server removes it from the component database and writes it to the Delete Log database.

When individual instances of a recurring event or task are deleted, the server writes each deleted instance to the Delete Log database. When all instances of the recurring event or todo are deleted, the server deletes the master entry for the component from the component database and writes it to the Delete Log database. A master entry in the Delete Log database contains the following recurrence parameters: rrules, exrules, and exdates.

In a single fetch_deletedcomponents command, either individual instances can be retrieved, or the master entry with its exceptions, but not both.

For more information on the Delete Log database, see the .

Fetching Recurrence Data Using Calendar Server WCAP

The compressed parameter allows you to retrieve a reduced amount of recurrence data. The parameter defaults (compressed=0) to the compressed format, which returns data without the rrules, rdates, exrules, and exdates properties as the default. To receive all the recurrence data back from the following commands, use compressed=1.

This parameter is used by all the fetchcomponents_by_* commands, the fetchevents_by_id and fetchtodos_by_id commands, and the store* commands.

compressed has been deprecated for the current release, and is included for backwards compatibility only. It can be removed from the future releases.

Formatting Standards for Calendar Server WCAP

Find the exact format and definition for all times, strings, parameters, and so forth, by referring to RFC 2445, RFC 2446, and RFC 2447. Unless otherwise noted, all WCAP commands follow these specifications.

The RFC’s can be found at the IETF web site:

• http://www.ietf.org/rfc/rfc2445.txt

• http://www.ietf.org/rfc/rfc2446.txt

• http://www.ietf.org/rfc/rfc2447.txt

As a reminder, the maximum parameter value length is 1024 characters.

For more information on time zones, see Calendar Server WCAP Time Zoneswhich follows later in this section.

Free-Busy Calendars in Calendar Server WCAP

Calendars can be displayed in free-busy format instead of showing details of scheduled events and todos. Free-busy formatted calendars are used to facilitate scheduling of events or todos in the event and todo creation dialogs in the user interface. To prevent other users from viewing event details, calendar owners can grant only free-busy access to their calendars.

This can be accomplished in two separate ways that are not mutually exclusive:

• Free-busy access rights can be granted to users in the calendar’s properties.

• Free-busy access can be assigned to the calendar as a whole using the calendar property fbinclude.

  If fbinclude is set to 0, it overrides any access rights granted to users. That is, if fbinclude=0, then the calendar does not be included in free-busy calculations, no matter what the acl parameter specifies.

  If fbinclude=1, which allows the use of the calendar for free-busy calculations, then the acl access rights are used to determine if the user can see the details of the calendar, the free-busy representation only, or neither.

In free-busy calendars, instead of event or todo details, just the word “Busy” appears by the time block. Blocks of time without any scheduled events are listed also, with the word “Free” next to them. The time slot can also be shown as Busy-tentative, or even Busy-unavailable, depending on the value of the following parameters: transparency, status, PARSTAT.

For example, a calendar called jdoe has the following events:

If user john has only free-busy access to the calendar jdoe, user john gets only a free-busy version of the calendar. The free-busy time for jdoe (from 9:00 to 6:00) would appear as the following:

Notice that john does not know the details of why the user is busy, but knows when the user is busy.

The get_freebusy command allows selection of which calendars to use in the calculation in two ways: using the calid parameter, or the mail parameter. One of the parameters is required, but not both. If both are present, the calid value is used.

When an email address is passed in using the mail parameter, all calendars, for which this user is the primary owner and which have fbinclude=1 in their calendar properties settings, are included in the free-busy calculation.

When the calid parameter is used, specific calendars can be named rather than using all of owners calendars. Note that the calid parameter can take an email address (by specifying mailto:ref822address, where rfc822address is any valid email address that maps to a single calendar in the local LDAP directory).

The command returns the busy data only. The rest of the time slots are presumed to be free.

Free-busy Calculation for Private Events in Calendar Server WCAP

When a free-busy calendar rendition is requested using the get_freebusy command, private events and todos are included or excluded depending on the value of the transparent parameter stored with the events and todos when they were created or modified.

Using either storeevents or storetodos, to keep the event private, set the event or todo parameter to transparent=1. Set it to transparent=0 to allow the event or todo to be included in the free-busy calculation.

As opposed to regular events, all-day events (isAllDay=1) default to private and transparent (transparent=1). For the all-day event to be included in the free-busy calculation, set the parameter to transparent=0.

Output Format Used by Calendar Server WCAP

WCAP commands can request the output format in two content types: text/calendar and text/xml.

To change the output format, set fmt-out to the target value. If fmt-out is not specified, the default format of text/calendar is returned.

Recurring Components in Calendar Server WCAP

• Calendar Server WCAP Recurrence Overview

• Calendar Server WCAP Recurring Components– Creating, Modifying

• Calendar Server WCAP Recurring Components–Deleting

• Calendar Server WCAP Recurring Components– Fetching

Calendar Server WCAP Recurrence Overview

Recurrence handling occurs as follows:

• A recurring series of events or todos has a master entry plus entries for exceptions.

• Changing the rrules of a single instance returns an error. When rrules are modified for a recurring series, the whole series is deleted and recreated.

• Changing dtstart of a recurring series entry causes the whole series to be recreated with the new dtstart, thereby losing all exceptions.

• Inserting a rid that was not part of the original rule is not supported.

• Multiple rrules for any component are not supported.

Calendar Server WCAP Recurring Components– Creating, Modifying

The following parameters are used with the storeevents and storetodos commands to create and modify components:

• rrules - Semicolon-separated list of quoted recurrence-rule strings for recurring events.

• rdates– Semicolon-separated list of ISO 8601 date strings listing recurrence dates.

• exrules– Semicolon-separated list of quoted recurrence-rule strings for dates to exclude.

• exdates– Semicolon-separated list of ISO 8601 date strings listing dates to exclude.

• rid– ISO 8601 Date-Time String giving the recurrence ID of an event.

• mod– Modifier specifying whether the action pertains to all the events or to just this event.

• rchange– A boolean specifying whether or not to replace the rrules parameter. If rchange=1, the store commands map all mod settings (2-4) are mapped to 4. This means that you can not change an rrules for only some of the components in a recurring series. To change the rrules parameter, all components in the recurring series must be changed.

• excludedtstart– An integer specifying whether or not to include the dtstart date in a recurring series if the date does not follow the rrule.

The rrules, rdates, exrules, and exdates parameters always function in replace mode. That is, no matter what the replace parameter value is set to, the values passed in for the recurrence parameters always replace the old parameter values, rather being appended to them.

This means you can not have multiple rrules for the same component.

For more information on the replace parameter, see Updating Parameter Values in Calendar Server WCAP

rrules

The rrules parameter takes a semicolon-separated list of quoted recurrence rule strings. Each string represents a recurrence rule of the event. Each string must be enclosed in quotes. Many parameters are possible for recurrence rules. (See RFC 2445 for a complete description of the syntax.)

Three parameters used by Calendar Server for specifying recurrence are freq, count and until:

• The freq parameter in a rule defines the periodicity of the event, and has the following possible values:

• The count parameter in a rule defines how many times the meeting repeats. If you do not specify the count, the default is the maximum number of recurrences allowed. The default maximum is 60. To change the maximum number, set the server configuration preference calstore.recurrence.bound.

• The until parameter in a rule specifies using an end date as opposed to using the count to limit the number of instances created. Instances are created up to the end date or until 60 instances are created, whichever occurs first.

In the event that neither the count nor the until parameter are specified, the default is 60 instances.

Using the storeevents.wcap command to create an event with only exdates or rdates values, without specifying an rrules results in no events being created. The same behavior can be observed with the storetodos.wcap command.

The following example shows an rrules parameter that specifies the event is to occur daily for 10 instances (COUNT=10;FREQ=DAILY):

rrules="count%3D10%3Bfreq%3Ddaily"

The following example URL passes the example rrules parameter:

http://webcalendarserver/storecomponents.wcap
              ?id=b5q2o8ve2rk02nv9t6
              &calid=jdoe
              &uid=333
              &dtstart=20020301T112233Z
              &rrules="count%3D10%3Bfreq%3Ddaily"
              &dtend=20020301T112233
              &summary=uuuu

rdates

The rdates parameter takes a semicolon-separated list of date-time specifications where each date-time gives a recurrence date of the event.

For example, the following rdates parameter specifies a recurring event with two recurrence dates (3/31/02 11:22:33 and 5/31/02 11:22:33):

rdates=20020331T112233;20020531T112233

The following example URL passes the rdates parameter:

http://webcalendarserver/storecomponents.wcap
              ?id=b5q2o8ve2rk02nv9t6
              &calid=jdoe
              &uid=333
              &dtstart=20020301T112233Z
              &rdates=20020331T112233;20020531T112233
              &dtend=20020301T112233
              &summary=uuuu

If you want to the change the recurrence rule after a certain date, you must set rchange to 1.

exrules

The exrules parameter takes a semicolon-separated list of quoted recurrence rule strings where each rule is an excluded recurrence of the event.

For example, the following exrules parameter specifies a recurring event that does not recur at the times specified by the two rules:

exrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4"

The first rule is for the event not to occur daily for 10 instances. The second rule is for the event not to occur weekly for 4 instances (COUNT=10;FREQ=DAILY and FREQ=WEEEKLY;COUNT=4).

The following example URL passes the example exrules parameter:

http://webcalendarserver/storecomponents.wcap
              ?id=b5q2o8ve2rk02nv9t6
              &calid=jdoe
              &uid=333
              &dtstart=20020301T112233Z
              &exrules="count%3D10%3Bfreq%3Ddaily";
                       "freq%3Dweekly%3Bcount%3D4"
              &rrules="count%3D100%3Bfreq%3Ddaily"
              &dtend=20020301T112233
              &summary=uuuu

exdates

The exdates parameter takes a semicolon-separated list of date-time specifications. Each date-time represents an excluded date of the event.

For example, the following exdates parameter specifies a recurring event that does not occur on the two specified dates (3/31/02 11:22:33 and 5/31/02 11:22:33):

exdates=20020331T112233;20020531T112233

The following example URL passes the example exdates parameter:

http://webcalendarserver/storecomponents.wcap
              ?id=b5q2o8ve2rk02nv9t6
              &calid=jdoe
              &uid=333
              &dtstart=20020301T112233Z
              &exdates=20020331T112233;20020531T112233
              &rrules="count%3D200%3Bfreq%3Ddaily"
              &dtend=20020301T112233
              &summary=uuuu

rid

This parameter specifies a unique recurrence date of an event or todo. Use rid in conjunction with the mod parameter to specify a range of events and todos to be modified.

For example:

http://webcalendarserver/storecomponents.wcap
              ?id=b5q2o8ve2rk02nv9t6
              &calid=jdoe
              &uid=333
              &dtstart=20020301T112233Z
              &rid=20020331T112233
              &dtend=20020301T112233
              &summary=uuuu&mod=1

For a non-recurring event or todo, the rid is 0.

mod

When modifying recurring components, this parameter specifies whether to apply the changes to one or more instances of the event or todo. The following settings are mapped, but currently only the values 1 and 4 are used.

When creating or modifying a recurring component, if changing rrules is allowed (rchange is set to 1), the system assumes a setting of 4, which causes the entire series of events or todos to be deleted and rewritten. If 2 or 3 are specified when trying to change rules or start times, they are mapped to 4. If 2 or 3 is specified for changing a summary or description, the setting are honored, but no exceptions are created for errors.

rchange

The rchange parameter specifies whether recurrences are expanded in storeevents.wcap, and storetodos.wcap. Normally, events and todos calendar components are not expanded, so the parameter defaults to 0, which implies the series is recreated.

However, you might not want to expand recurrences when you are modifying multiple events. For example, suppose a meeting recurs every Friday starting Jan. 1, 2002. Use the following URL to change the summary of each event after Feb. 1, 2002 to changed-event.

The following example sets the rchange parameter to 0, to make the modification without adding additional events:

http://webcalendarserver/storeevents.wcap
              ?id=b5q2o8ve2rk02nv9t6
              &calid=jdoe
              &uid=abcxyz
              &dtstart=20020201T112233Z
              &rrules="byday%3Dfr%3Bfreq%3Dweekly"
              &summary=changed-event
              &rid=20020201T112233Z
              &mod=4
              &rchange=0

Note that when you are modifying a recurrence series, do not pass in rrules unless you are trying to recreate the series with a new rule.

excludedtstart

When creating a recurring series according to the rrule, this integer specifies whether to include the dtstart date if the date does not follow the rrules. For example, if on a Monday, you were creating a recurring series of meetings that were to be held every Wednesday, the dtstart would be Monday, but that does not fit the set of dates (all Wednesdays) generated using the rrules. Therefore the server must decide whether to include the dtstart date or not based on the value of excludedtstart.

A value of 0 indicates the dtstart date is included in the recurring series and a value of 1 indicates the dtstart date is not included in the recurring series. The default is 0.

Calendar Server WCAP Recurring Components–Deleting

When you delete a recurring component, specify the recurrence ID and whether to delete the recurrences as well as the original event or todo.

Use the mod parameter to select which occurrences to delete:

Example 2–2 Examples Using deleteevents_by_id

To delete just the single instance of the event, the mod parameter should be set to 1. For example, this URL would delete just the event that occurs on the date March 1, 2002 11:22:33 AM GMT.

http://webcalendarserver/deleteevents_by_id.wcap
              ?id=23423423434abc
              &calid=jdoe
              &uid=001
              &rid=20020301T112233Z
              &mod=1

To delete all instances of the event, the mod parameter should be set to 4. For example, this URL would delete ALL instances of the event (uid 001).

http://webcalendarserver/deleteevents_by_id.wcap
              ?id=23423423434abc
              &calid=jdoe
              &uid=001
              &rid=20020301T112233Z
              &mod=4

Calendar Server WCAP Recurring Components– Fetching

The following parameters are found in the fetchcomponents_by_* commands, and the fetchevents_by_id and fetchtodos_by_id commands:

• compressed– A boolean specifying whether to return all of the recurring entry’s data, or to exclude the following parameters:rrules, rdates, exrules, exdates.

  ---

  Note –

  This parameter is deprecated in the current release, and is included only for backwards compatibility. It might be removed from future releases.

  ---

• recurring– A boolean parameter specifying whether or not to return all components in compressed form (master entry and exceptions). This parameter is also present in the fetch_deletedcomponents command.

Sorting Order of Returned Events and Todos in Calendar Server WCAP

Fetch commands that support the fetchorder parameter allow you to specify the order in which the events and todos are returned.

Three sorting choices can be specified:

• Ascending order

• Descending order

• Special (or legacy) sorting order–This sorting choice returns things in mostly ascending order.

The sorting logic is as follows:

• For events, put in order according to dtstart. If two events have the same dtstart date, then compare dtend for the two events. Return the one that fits the desired sort order. If they are the same, compare uid and return the components from the least value to the highest.

  • For todos, all completed tasks are returned after all sorted not-due tasks. For two not-due tasks, compare dtdue. Return in the desired sort order. If they are the same, compare uid and return components from the least value to the highest. For descending sorts, some overdue tasks could be truncated because of the maxResults limit.

  • For recurring components sorted in ascending order, the master record is returned first and then the exceptions. Depending on the maxResults limit, some exceptions could be truncated. In this case, error 81 is given. (See Calendar Server WCAP Error Handling.)

  • For recurring components sorted in descending order, exceptions are returned first and then the master record. Depending on the maxResults limit, it is possible for a master record to be truncated. In this case, error 81 is given. (See Calendar Server WCAP Error Handling.)

Calendar Server WCAP Time Zones

To support a universal standard, Calendar Server uses the date and time strings in Greenwich Mean Time (GMT) or Coordinated Universal Time (UTC), called Zulu time. The server stores and returns all date and time strings from the database in Zulu time. WCAP converts the Zulu times to the appropriate time zone settings depending upon the value of the tzid and tzidout parameters.

The tzid parameter is used for date and time strings passed in with the dtstart, dtend, and rid parameters, which are not already in Zulu time. WCAP uses the value of the tzid parameter to calculate the Zulu time. If the tzid parameter is not passed in, the server’s default time zone is used to calculate Zulu time.

For commands that return events and todos, the data is returned in Zulu time, unless the tzidout parameter is passed in. In this case the Zulu time is translated into the time zone specified in the tzidout parameter.

For example, if the fetch_components_by range command specifies a date range of 20020506T100000 to 20020507T100000, with a tzid=America/Los_Angeles, WCAP translates that to Zulu time for database lookup. If the tzidout parameter was also passed in (for our example, tzidout=America/New_York), then the resulting output would be translated to that time zone and returned. If the tzidout parameter is missing, the component data is returned in Zulu time.

The tzidout parameter can be used with the storeevents and storetodos command when the fetch parameter is set to 1 (fetch=1).

The time zones information is kept in a plain text file (timezones.ics) in VTIMEZONE format.

The server never uses the system time zone information to calculate the current date and time. It uses the time elapsed in seconds since the Epoch (00:00:00 UTC, January 1, 1970) to calculate current date and time. Then depending on the user’s time zone settings, the date is displayed to reflect the correct time zone.

The following commands use both the tzid and tzidout parameters:

• fetchcomponents_by_alarmrange.wcap

• fetchcomponents_by_lastmod.wcap

• fetchcomponents_by_range.wcap

• fetchevents_by_id.wcap

• fetchtodos_by_id.wcap

• storeevents.wcap

• storetodos.wcap

In addition, the following commands use the tzid parameter (but not the tzidout):

• deleteevents_by_id.wcap

• deletetodos_by_id.wcap

• get_freebusy.wcap

• set_calprops.wcap

Updating Parameter Values in Calendar Server WCAP

Two commands, storeevents and storetodos, allow you to update (replace, append, or delete) parameter values. When updating current values for a component, you can either replace the current values with the new ones being passed in, append the new values to the current values, or pass in empty parameter values to delete the parameter.

The ability to append parameter values applies only to parameters that can accommodate multiple values (that is, parameters that use semicolon-separated values, such as the attendees parameter). The default is to append (replace=0) the new values to the current values. If you want to replace the current values with the new values being passed in, include the replace parameter in the command, with the value set to 1 (replace=1). If you do not include the replace parameter in the command, the system assumes the default setting (replace=0) and appends the new values to the old values.

With one exception, the recurrence and alarm parameters can only be replaced, not appended. Specifically, the parameters are: rrules, rdates, exrules, exdates, alarmAudio, alarmDescription,alarmFlashing, alarmPopup, and alarmStart. The alarmEmails parameter is the only one that allows multiple values, and thus is the only exception. Therefore you can append an alarm email recipient to the list by specifying replace=0.

In all cases, a parameter can be deleted by passing in an empty parameter and setting replace to 1. For example, to delete the alarmPopup parameter, pass in the following: alarmPopup=&replace=1. Using replace=1 can also be used to delete string fields. For example, to delete the description, you would use desc=&replace=1.

X-Tokens Used by Calendar Server WCAP