Calendar-WS:
Web Services Interface to CalAgenda - Revision 1 of May 2005

Please send your feedback on this document to the CalAgenda Web Services stakeholders mailing list, .

Introduction
Connecting to the Web Services interface
Authenticating to the Web Services Interface
Remote Procedures in the Web Services Interface
String Formats Used in Arguments to These Remote Procedures
Results Returned by These Procedures
Calendar Formats Returned in Results
Error Descriptions Returned in Results

Introduction

This document identifies a simple Web Services interface through which campus and departmental applications at the University of California, Berkeley can programmatically add, delete, and find meetings, reservations, and other events in the campus calendars for various people and resources. These calendars are provided by the campus's shared calendaring system, CalAgenda.

The interface described in this document reflects the first iteration ('revision 1') of this service. Your ongoing feedback regarding this interface - particularly feedback on how well it serves the needs of your own applications - is cordially invited.

Connecting to the Web Services interface

As discussed in the accompanying Functional Specifications: Summary document, this interface is offered via SOAP- and WSDL-based Web Services, in an RPC paradigm. Translated, that means that a campus or departmental application can use this interface by writing a few lines of code - using an appropriate Web Services toolkit for its programming or scripting language - to call a set of remote procedures and process the resultant responses.

For more details about how your application can connect to this service, please see the accompanying Programming Notes document.

Authenticating to the Web Services Interface

To view and edit data in CalAgenda calendars, your application will authenticate as a user of the CalAgenda service. Special user accounts for this purpose will be created upon request. Several test accounts are also available for your use.

Specifically, your application will provide either the CalNet Directory Service UID or the CalAgenda username of that user (see the userId format for details) and the associated CalAgenda password as two of the arguments that it sends to the remote procedures in this Web Services interface.

Your application can also optionally provide the Calendar ID for another user or resource calendar, on which it wishes to act as a designate. Your application will need to repeatedly provide this authentication (and designate information), each time it calls a remote procedure, as no session information is maintained.

Your application can view and change events on the calendar linked to the CalNet UID (or CalAgenda username) and password that it provides. More usefully, your application can also view and change any other user or resource calendars on the CalAgenda service to which that user account has been given designate access.

In the future, at least two additional types of access could potentially be offered via this Web Services interface:

The ability to invite campus affiliates to calendar events; and
The ability to act as a "sysop" (privileged) user, to view and edit user and resource calendars without having to first set up designate access to those calendars.

This would be integrated with one or more external mechanisms for managing authentication and authorization.

For more information on this Web Services interface in general, including an overview of the types of access it offers today, and may offer in the future, please see the the accompanying Functional Specifications: Summary document.

Remote Procedures in the Web Services Interface

These remote procedures are formally described in the WSDL description for the Web Services interface to the CalAgenda service, which resides at https://calendar-ws.berkeley.edu:8004/calendaraccess/services/CalendarAccessImpl.wsdl.

The following is a detailed, supplementary description of these procedures, including the parameters they accept, the results they return, and their current limitations, if any.

Note: Common to each procedure below (except pingServer) are three authentication-related parameters. These are indicated in italics below.

Verifying Connections

pingServer()
Returns an XML results document, as in this pingServer example

This procedure, which does not accept any parameters, can be used to verify that the connection is working end-to-end: both an application's connection to the Web Services interface, and the Web Services interface's connection, in turn, to the CalAgenda server.

Finding and Retrieving Events

getEventsByRange( userId, password, calendarId, beginningDateTime, endingDateTime, includeICal )
Returns an XML results document, as in these getEventsByRange examples

This procedure can be used to obtain the list of calendar events falling within a specified time period from a user or resource calendar.

Parameter name	Parameter type	Required (must be non-empty)?	Description
userId	String (in userId format)	Yes	Calendar user who will be performing this action
password	String	Yes	Password for the calendar user who will be performing this action
calendarId	String (in calendarId format)	No	ID identifying the calendar of another user or resource, on which the first calendar user, above, wishes to act as a designate.
beginningDateTime	String (in date/time format)	Yes	Date/time of beginning of period to be searched for events
endingDateTime	String (in date/time format)	Yes	Date/time of ending of period to be searched for events
includeICal	String (in yes/no format)	No	Whether matching events should be returned in the detailed and verbose iCalendar format, in addition to the more concise, default events listing format, which is based on a restricted subset of xCalendar.

getEvent( userId, password, calendarId, eventUid, includeICal )
Returns an XML results document, as in these getEvent examples

This procedure can be used to obtain details regarding the calendar event matching a unique event ID, if any, in a user or resource calendar.

Parameter name	Parameter type	Required (must be non-empty)?	Description
userId	String (in userId format)	Yes	Calendar user who will be performing this action
password	String	Yes	Password for the calendar user who will be performing this action
calendarId	String (in calendarId format)	No	ID identifying the calendar of another user or resource, on which the first calendar user, above, wishes to act as a designate.
eventUid	String (in unique event ID format)	Yes	Unique ID of event to be retrieved
includeICal	String (in yes/no format)	No	Whether matching events should be returned in the detailed and verbose iCalendar format, in addition to the more concise, default events listing format, which is based on a restricted subset of xCalendar.

Adding Events

addEvent( userId, password, calendarId, title, start, end, location, details )
Returns an XML results document, as in this addEvent example

This procedure can be used to add a single calendar event to a user or resource calendar.

In the initial iteration ('revision 1') of this interface, events will be added without regard for possible conflicts (time overlaps) with other events, except where a resource or user calendar's settings explicitly prevent such conflicts from occurring. Potential conflicts stemming from an event that your application has just added are identified in the results document, so your application will be able to take appropriate action whenever any potential conflicts arise.

In addition, in the initial iteration of this interface, there is no mechanism for specifying repeating events. Each instance of a repeating event must be added individually.

Parameter name	Parameter type	Required (must be non-empty)?	Description
userId	String (in userId format)	Yes	Calendar user who will be performing this action
password	String	Yes	Password for the calendar user who will be performing this action
calendarId	String (in calendarId format)	No	ID identifying the calendar of another user or resource, on which the first calendar user, above, wishes to act as a designate.
appSpecificEventIdentifier	String	No	An identifier for the application creating this event, which will be added to the event's unique ID. This allows applications to identify the events they created.
title	String	No	Event title
start	String (in date/time format)	Yes	Date/time of event start
end	String (in date/time format)	Yes	Date/time of event end
location	String	No	Event location
details	String	No	Details regarding the event (The details field could also be used by an application for its own tagging purposes)

Deleting Events

deleteEvent( userId, password, calendarId, uid )
Returns an XML results document, as in this deleteEvent example

This procedure can be used to delete the single event matching a unique event ID, if any, from a user or resource calendar.

In the initial iteration ('revision 1') of this interface, all instances of the specified event will be deleted.

Parameter name	Parameter type	Required (must be non-empty)?	Description
userId	String (in userId format)	Yes	Calendar user who will be performing this action
password	String	Yes	Password for the calendar user who will be performing this action
calendarId	String (in calendarId format)	No	ID identifying the calendar of another user or resource, on which the first calendar user, above, wishes to act as a designate.
eventUid	String (in unique event ID format)	Yes	Unique ID of event to be deleted

String Formats Used in Arguments to These Remote Procedures

userId String Format

The userId string format uniquely identifies a user account on the CalAgenda service. It can be expressed in any one of the following three formats:

The CalNet Directory UID of a CalAgenda user.

Example:

209826
A CalAgenda username, with firstname, initials, and lastname components separated by forward slash characters ("/") as delimiters, in the format firstname/initials/lastname.

Examples:
Orange//Grundo
Orange/T/Grundo
Orange//de la Grundo
A CalAgenda user ID. (Deprecated.)

Example:

ogrundo

Only a small number of CalAgenda users will have a user ID, which is typically provided by the service's administrators upon request. Although this option is supported for the sake of completeness by the Web Services interface, it is deprecated: use a CalNet UID or a CalAgenda username instead.

calendarId String Format

The calendarId string format consists of a string uniquely identifying a specific user or resource calendar on the CalAgenda service. This string can be in any of four formats: any one of the three userId formats described above, which uniquely identify a user calendar, or a string uniquely identifying a resource calendar.

A resource calendar string begins with the prefix r:, followed by the resource calendar's name in CalAgenda.

Examples of strings identifying resource calendars include:

r:Evans 236 Conference Room
r:BioEng Computer Projector

You can search for the exact name of a resource calendar to use in any parameter which accepts a calendarId string in at least two ways: First, in the desktop Oracle Calendar application for Windows and Mac OS X, by selecting "Search Directory..." from the "Tools" menu, and then clicking the "Resources" tab or icon. Second, in the Web-based interface to CalAgenda, by clicking the "New Meeting" icon, and then the "People & Resources" tab.

Date/Time String Format

The string format for the date and time string matches a standard profile of the International standard for date and time representation, ISO 8601. This format has the advantage of being clear, compact, and unambiguous, as well as as conforming to the calendaring/scheduling date and time representation in the iCalendar specification, below.

This format consists of a four-digit year, a two-digit month, a two-digit day-of-month, the character 'T', a two-digit hour (in a 24-hour clock), a two-digit minute, and a two-digit second. Optionally, this string can end in the character 'Z' to signify the Coordinated Universal Time (UTC) timezone. If the 'Z' is omitted, the date and time is assumed to be in the US/Pacific ('America/Los_Angeles') timezone.

Expressed using Java's date format patterns, this format is:

yyyyMMdd'T'HHmmss (without the single quotes around 'T')
(for times in the US/Pacific timezone)

yyyyMMdd'T'HHmmss'Z' (without the single quotes around 'T' or 'Z')
(for times in UTC, which is eight hours later than US/Pacific Standard Time, and seven hours later than US/Pacific Daylight Savings Time)

As one example, October 15, 2004, at 9:30 am, in the US/Pacific timezone, would be expressed as the string:

20041015T093000

That same date and time, in the UTC timezone would be expressed as the string:

20041015T173000Z

For more information about the ISO 8601 standard for date and time representation, please see Markus Kuhn, A Summary of the International Standard Date and Time Notation and Jukka "Yucca" Korpela, Info on ISO 8601, the date and time representation standard

For more information about time zones and the names used to refer to them in calendar data representations, such as iCalendar and xCalendar, please see Sources for Time Zone and Daylight Saving Time Data.

Unique Event ID String Format

Oracle Calendar stores each event in CalAgenda with a globally unique event ID (UID).

Unique event IDs consist of three parts: a timestamp in date/time format, in the UTC time zone; followed by a set of hexadecimal digits ("0-9a-f") and optional hyphen ("-") characters; followed by an identification string. Each of these three parts is delineated from the next by a hyphen ("-") character.

Below are examples of three different types of unique event IDs that your application may encounter:

20040514T233537Z-402-66-4c8d-Oracle
(Oracle Calendar-generated)

20040602T222224Z-fce774b7b5-edu.berkeley.ist.calendaraccess
(Web Services interface-generated)

20040602T013000Z-edc874ddc9-yourappidentifierhere
(Application-generated, with your application's unique identification string substituted for yourappidentifierhere)

There are at least two ways that your application can obtain unique IDs for events in revision 1 of this Web Services interface:

When your application creates a new event by calling the addEvent procedure, its new unique ID is returned.

Your application can then cache or store this ID, if it wishes to do so.
Your application can also obtain unique IDs by calling the getEventsByRange procedure to retrieve an event or set of events falling within a specified time period.

It can then use those IDs when calling the getEvent procedure to retrieve details of an event, or when calling the deleteEvent procedure to delete an event.

In addition, your application can include its own identification string(s) in the unique IDs for newly-created events, as a replacement for the default identification string included in those UIDs. To include your application's own identification string at the end of a newly-created event's UID, call the addEvent procedure with a non-empty appSpecificEventIdentifer argument.

In this way, your application can 'tag' any or all of the events that it creates, so that it can identify them later. Your application's own identification string will appear as part of the UIDs in the event listings retrieved by the getEventsByRange and getEvent procedures.

Yes/No String Format

The format for "Yes/No" strings is simple: the strings "y" or "yes" in any character case (including "Y", "Yes", "YeS", "YEs", "yEs", "yES", and "YES") signify a 'yes' or 'affirmative' value.

Any other value, including an empty string, indicates a 'no' or 'negative' value. (However, for clarity, your application may wish to use 'n' or 'no', in any character case, as a convention to unambiguously signify a 'no' or 'negative' value.)

Results Returned by These Procedures

All results from the calls above are returned in the form of an XML document in the http://calagenda.berkeley.edu/calendaraccess/results namespace. A schema for this document will made available in the future. Until then, the following examples are intended to serve as partial documentation of the format of this results document.

The results document will be contained within the body section of the SOAP message returned by the Web Services interface. Your application can extract individual components of this document via direct XML parsing - the recommended method - or via the use of regular expressions or string functions.

Below are some examples of representative results returned from calls to various procedures in the initial ('revision 1') Web Services interface. Note: line breaks and other whitespace, such as spaces used for indentation, may appear in different places in the actual results returned from these procedures, than they do in the examples below.

pingServer: Example Results

Below are representative results from a successful call to pingServer to verify that a connection is working. ("mochi.berkeley.edu" is the hostname of a test server; in production this hostname would instead be "calagenda.berkeley.edu"):

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='1'>
    <r:result mime-type='text/plain' item='1'>
      The Oracle Calendar server mochi.berkeley.edu is alive and responding to requests
      from this Web Services interface. The server reports its version as [4.0 and above].
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>pingServer</r:procedure-call>
    <r:as-user></r:as-user>
    <r:acting-as-sysop></r:acting-as-sysop>
    <r:as-designate-for-calendar></r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

getEventsByRange: Example Results

Below are representative results from a successful call to getEventsByRange, which returned three events in the specified time period:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='1'>
    <r:result mime-type='text/xml; charset=utf-8' item='1'>
      <vc:vcalendar xmlns:vc='http://calagenda.berkeley.edu/calendaraccess/xcal-vcalendar-subset'
        number-of-events='3'>
        <vc:vevent x-event-type='appointment'>
          <vc:summary>Open Mike Competition</vc:summary>
          <vc:location>The Basement Lounge</vc:location>
          <vc:description>Only experienced lounge singers need apply.</vc:description>
          <vc:dtstart tzid='America/Los_Angeles'>20041123T103000</vc:dtstart>
          <vc:dtend tzid='America/Los_Angeles'>20041123T120000</vc:dtend>
          <vc:uid>20050415T231422Z-10342ec5524-our-app-event-identifier</vc:uid>
        </vc:vevent>
        <vc:vevent x-event-type='holiday'>
          <vc:summary>Thanksgiving Holiday</vc:summary>
          <vc:dtstart>20041126</vc:dtstart>
          <vc:dtend>20041126</vc:dtend>
          <vc:uid>20040530T173802Z-5ce-1-30be-Oracle</vc:uid>
        </vc:vevent>
        <vc:vevent x-event-type='holiday'>
          <vc:summary>Thanksgiving Holiday</vc:summary>
          <vc:dtstart>20041125</vc:dtstart>
          <vc:dtend>20041125</vc:dtend>
          <vc:uid>20040530T173526Z-5a4-1-1709-Oracle</vc:uid>
        </vc:vevent>
      </vc:vcalendar>
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>getEventsByRange</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar></r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

Below is a second representative example of results returning three events from a successful call to getEventsByRange, with the value of the includeICal argument set to 'y' or 'yes'. These results include two alternate representations of the same calendar events, with a limited subset of xCalendar as the first, default representation and iCalendar as the second, optional representation:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='2'>
    <r:result mime-type='text/xml; charset=utf-8' item='1'>
      <vc:vcalendar xmlns:vc='http://calagenda.berkeley.edu/calendaraccess/xcal-vcalendar-subset'
        number-of-events='3'>
        <vc:vevent x-event-type='appointment'>
          <vc:summary>Open Mike Competition</vc:summary>
          <vc:location>The Basement Lounge</vc:location>
          <vc:description>Only experienced lounge singers need apply.</vc:description>
          <vc:dtstart tzid='America/Los_Angeles'>20041123T103000</vc:dtstart>
          <vc:dtend tzid='America/Los_Angeles'>20041123T120000</vc:dtend>
          <vc:uid>20050415T231422Z-10342ec5524-our-app-event-identifier</vc:uid>
        </vc:vevent>
        <vc:vevent x-event-type='holiday'>
          <vc:summary>Thanksgiving Holiday</vc:summary>
          <vc:dtstart>20041126</vc:dtstart>
          <vc:dtend>20041126</vc:dtend>
          <vc:uid>20040530T173802Z-5ce-1-30be-Oracle</vc:uid>
        </vc:vevent>
        <vc:vevent x-event-type='holiday'>
          <vc:summary>Thanksgiving Holiday</vc:summary>
          <vc:dtstart>20041125</vc:dtstart>
          <vc:dtend>20041125</vc:dtend>
          <vc:uid>20040530T173526Z-5a4-1-1709-Oracle</vc:uid>
        </vc:vevent>
      </vc:vcalendar>
    </r:result>
    <r:result mime-type='text/calendar' item='2'>BEGIN:VCALENDAR
      VERSION:2.0
      PRODID:-//ORACLE//NONSGML CSDK 9.0.4.2 - Java SDK Demo 9.0.4//EN
      BEGIN:VEVENT
      X-ORACLE-IMEETING-SENDEMAILNOTIFICATION:TRUE
      X-ORACLE-EVENTINSTANCE-GUID:I1+129739+1+1+450918862
      X-ORACLE-EVENT-GUID:E1+129739+1+450918862
      X-ORACLE-EVENTTYPE:APPOINTMENT
      UID:20050415T231422Z-10342ec5524-our-app-event-identifier
      TRANSP:OPAQUE
      SUMMARY:Open Mike Competition
      STATUS:CONFIRMED
      SEQUENCE:0
      PRIORITY:0
      LOCATION:The Basement Lounge
      DESCRIPTION:Only experienced lounge singers need apply.
      DTSTART:20041123T183000Z
      DTSTAMP:20050415T231428Z
      DTEND:20041123T200000Z
      CREATED:20050415T231422Z
      CLASS:PUBLIC
      END:VEVENT
      BEGIN:VEVENT
      X-ORACLE-IMEETING-SENDEMAILNOTIFICATION:TRUE
      X-ORACLE-EVENTINSTANCE-GUID:I1+1486+1+1+423250748
      X-ORACLE-EVENT-GUID:E1+1486+1+423250748
      X-ORACLE-EVENTTYPE:HOLIDAY
      UID:20040530T173802Z-5ce-1-30be-Oracle
      TRANSP:TRANSPARENT
      SUMMARY:Thanksgiving Holiday
      STATUS:CONFIRMED
      SEQUENCE:0
      PRIORITY:5
      DTSTART;VALUE=DATE:20041126
      DTSTAMP:20050415T231428Z
      DTEND;VALUE=DATE:20041126
      CREATED:20040530T173908Z
      CLASS:PUBLIC
      END:VEVENT
      BEGIN:VEVENT
      X-ORACLE-IMEETING-SENDEMAILNOTIFICATION:TRUE
      X-ORACLE-EVENTINSTANCE-GUID:I1+1444+1+1+423250592
      X-ORACLE-EVENT-GUID:E1+1444+1+423250592
      X-ORACLE-EVENTTYPE:HOLIDAY
      UID:20040530T173526Z-5a4-1-1709-Oracle
      TRANSP:TRANSPARENT
      SUMMARY:Thanksgiving Holiday
      STATUS:CONFIRMED
      SEQUENCE:0
      PRIORITY:5
      DTSTART;VALUE=DATE:20041125
      DTSTAMP:20050415T231428Z
      DTEND;VALUE=DATE:20041125
      CREATED:20040530T173632Z
      CLASS:PUBLIC
      END:VEVENT
      END:VCALENDAR
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>getEventsByRange</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar></r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

Note that in listings for full-day events, such as the two Thanksgiving holiday events above, the values of the starting and ending date/time strings, dtstart and dtend, consist of the same ISO 8601 date without a time part. These dates are in yyyyMMdd format, as shown in the examples of 20041125 and 20041126. In the revision 1 Web Services interface, at least, your application will need to be prepared to handle this variation on date/time strings when it receives listings for full-day events.

getEvent: Example Results

Below are representative results returned from a successful call to getEvent that identified a single matching event:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='1'>
    <r:result mime-type='text/xml; charset=utf-8' item='1'>
      <vc:vcalendar xmlns:vc='http://calagenda.berkeley.edu/calendaraccess/xcal-vcalendar-subset'
        number-of-events='1'>
        <vc:vevent x-event-type='appointment'>
          <vc:summary>Open Mike Competition</vc:summary>
          <vc:location>The Basement Lounge</vc:location>
          <vc:description>Only experienced lounge singers need apply.</vc:description>
          <vc:dtstart tzid='America/Los_Angeles'>20041123T103000</vc:dtstart>
          <vc:dtend tzid='America/Los_Angeles'>20041123T120000</vc:dtend>
          <vc:uid>20050415T225033Z-10342ec5524-our-app-event-identifier</vc:uid>
        </vc:vevent>
      </vc:vcalendar>
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>getEvent</r:procedure-call>
    <r:as-user>?/ND=1/G=Designate/S=One/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar>?/RS=Evans Hall 221 Conf Room/</r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

Below is a second representative example of results that would be returned from a successful call to getEvent, with the value of the includeICal argument set to 'y' or 'yes'. These results include two alternate representations of the same matching calendar event, with a limited subset of xCalendar as the first, default representation and iCalendar as the second, optional representation:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='2'>
    <r:result mime-type='text/xml; charset=utf-8' item='1'>
      <vc:vcalendar xmlns:vc='http://calagenda.berkeley.edu/calendaraccess/xcal-vcalendar-subset'
        number-of-events='1'>
        <vc:vevent x-event-type='appointment'>
          <vc:summary>Open Mike Competition</vc:summary>
          <vc:location>The Basement Lounge</vc:location>
          <vc:description>Only experienced lounge singers need apply.</vc:description>
          <vc:dtstart tzid='America/Los_Angeles'>20041123T103000</vc:dtstart>
          <vc:dtend tzid='America/Los_Angeles'>20041123T120000</vc:dtend>
          <vc:uid>20050415T225033Z-10342ec5524-our-app-event-identifier</vc:uid>
        </vc:vevent>
      </vc:vcalendar>
    </r:result>
    <r:result mime-type='text/calendar' item='2'>BEGIN:VCALENDAR
      VERSION:2.0
      PRODID:-//ORACLE//NONSGML CSDK 9.0.4.2 - Java SDK Demo 9.0.4//EN
      BEGIN:VEVENT
      X-ORACLE-IMEETING-SENDEMAILNOTIFICATION:TRUE
      X-ORACLE-EVENTINSTANCE-GUID:I1+129689+1+1+450917433
      X-ORACLE-EVENT-GUID:E1+129689+1+450917433
      X-ORACLE-EVENTTYPE:APPOINTMENT
      UID:20050415T225033Z-10342ec5524-our-app-event-identifier
      TRANSP:OPAQUE
      SUMMARY:Open Mike Competition
      STATUS:CONFIRMED
      SEQUENCE:0
      PRIORITY:0
      LOCATION:The Basement Lounge
      DESCRIPTION:Only experienced lounge singers need apply.
      DTSTART:20041123T183000Z
      DTSTAMP:20050415T225129Z
      DTEND:20041123T200000Z
      CREATED:20050415T225033Z
      CLASS:PUBLIC
      END:VEVENT
      END:VCALENDAR
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>getEvent</r:procedure-call>
    <r:as-user>?/ND=1/G=Designate/S=One/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar>?/RS=Evans Hall 221 Conf Room/</r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

addEvent: Example Results

Below are representative results returned from a successful call to addEvent which include the unique event ID of the just-added event.

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='2'>
    <r:result mime-type='text/plain' item='1'>
    	20050414T225514Z-10342ec5524-our-app-event-identifier
    </r:result>
    <r:result mime-type='text/xml; charset=utf-8' item='2'>
      <c:possible-conflicts xmlns:c='http://calagenda.berkeley.edu/calendaraccess/possible-conflicts'
      number-of-possible-conflicts='0'>
      </c:possible-conflicts>
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>addEvent</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar></r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

Because addEvent can potentially create a new event whose time period is identical to, or overlaps, one or more other events, the unique event IDs of any potentially conflicting events are also returned in the results, as shown in the second representative example below.

This will allow your application to call getEvent to to retrieve details regarding each potentially conflicting event, and then to take the appropriate action, such as deleting or rescheduling the conflicting events; deleting the newly-created event; or doing nothing, thus allowing two or more events to occupy the same time period:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='2'>
    <r:result mime-type='text/plain' item='1'>
    	20050414T225514Z-10342ec5524-our-app-event-identifier
    </r:result>
    <r:result mime-type='text/xml; charset=utf-8' item='2'>
      <c:possible-conflicts xmlns:c='http://calagenda.berkeley.edu/calendaraccess/possible-conflicts'
      number-of-possible-conflicts='1'>
        <c:possible-conflict-with>
          20040514T233537Z-402-66-4c8d-Oracle
        </c:possible-conflict-with>
      </c:possible-conflicts>
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>addEvent</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar></r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

deleteEvent: Example Results

Below are representative results returned from a successful call to deleteEvent which include the unique event ID of the just-deleted event:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='success'>0</r:results-status>
  <r:error>
    <r:description></r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results number-of-items='1'>
    <r:result mime-type='text/plain' item='1'>
    	20050415T224655Z-10342ec5524-our-app-event-identifier
    </r:result>
  </r:results>
  <r:request>
    <r:procedure-call>deleteEvent</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar>?/RS=Evans Hall 221 Conf Room/</r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

Calendar Events Formats Returned in Results

By default, the results returned from a successful call to the getEventsByRange and getEvent procedures will include a concise listing of calendar events. This events listing is in an XML format, specific to this Web Services interface, that is based on a limited subset of the xCalendar draft specification.

In addition, by specifying a value of 'y' or 'yes' in the includeICal argument to these two procedures, your application can request that a second, more detailed (and verbose) listing of events also be returned, in the IETF standards-based iCalendar format.

Selecting this option will provide considerably more detail about calendar events, and may also make it easier to import the event listing into calendaring and scheduling software products which support the iCalendar format. However, selecting this option will also significantly increase the size of the results returned.

iCalendar Format

iCalendar (sometimes referred to as "iCal") is an Internet specification for "electronic calendaring and scheduling information." The specification is described in Internet Calendaring and Scheduling Core Object Specification (RFC 2445).

xCalendar Format

xCalendar (sometimes referred to as "xCal") is an Internet Draft for representing iCalendar information in an XML vocabulary. This draft can be found as iCalendar DTD Document (xCal).

Although the original xCalendar draft has expired, work has continued within the calendaring and scheduling community, through the CALSCH IETF Working Group, on both the iCalendar specification and its XML representations. As a reflection of this work, Guideline for use of XML with iCalendar elements, a more recent Internet Draft, provides a guideline for constructing XML representations of iCalendar data.

Default Events Listing (xCalendar Subset) Used in the Web Services Interface

A very limited subset of the draft xCalendar specification is used as the default representation for the lists of calendar events returned from calls to the getEventsByRange and getEvent procedures in this Web Services interface.

Although this representation should be almost completely upwardly compatible with xCal, it is not a strict subset, because at least one attribute specific to the Web Services interface has been added. Nonetheless, we expect that it should be straightforward to transform the interface's own simple representation of calendar events into both xCal and iCalendar. A schema for this representation, and possibly also an XSLT stylesheet to facilitate transformations to the iCalendar format, will be provided at a future date.

Note: the attribute specific to the Web Services interface that was added to the xCal subset is the x-event-type attribute of the vevent element. By checking this attribute, applications can distinguish between types of events: appointment, daily note, day event, and holiday.

One other difference of note: in the concise, default listings of calendar events returned by the getEventsByRange and getEvent procedures in this Web Services interface, dates and times are always converted to and presented in the local (i.e. US/Pacific, aka America/Los_Angeles) time zone, rather than the UTC time zone. This is done as a convenience for your application, since we anticipate that campus and departmental applications will be working with local time under most or all circumstances.

Error Descriptions Returned in Results

There are two primary categories of errors that your application may encounter when attempting to view and edit CalAgenda calendars via this Web Services interface:

Errors related to your SOAP client code, in its attempt to exchange messages with this Web Services interface to CalAgenda.

These types of errors will be returned by your Web Services toolkit.
Errors which occur when attempting to view or edit events in CalAgenda calendars by calling the procedures offered by this Web Services interface.

These types of errors will be described within the error element in the XML results document returned by those remote procedures.

Below are several representative examples of this type of error. Note that, where errors are generated by code in the Oracle Calendar Software Development Kit ("CSDK"), which underlies this Web Services interface, the Oracle CSDK-provided error code and an explanation of this error will also be returned.

You can also view a list of some common errors your application may encounter.

This error resulted from calling the addEvent procedure with an attempt to add a new event on a non-existent date, such as February 30, 2005:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='error'>1</r:results-status>
  <r:error>
    <r:description>Beginning date of event '20050230T103000' does not match any of the expected date patterns.</r:description>
    <r:oracle-calendar-error>
      <r:code></r:code>
      <r:explanation></r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results></r:results>
  <r:request>
    <r:procedure-call>addEvent</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar></r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

This error resulted from calling the addEvent procedure while trying to act as a designate for a non-existent resource calendar:

<?xml version='1.0' encoding='UTF-8'?>
<r:calendaraccess-results xmlns:r='http://calagenda.berkeley.edu/calendaraccess/results'
  schema-version='1'>
  <r:results-status description='error'>1</r:results-status>
  <r:error>
    <r:description>Setting identity to user [?/RS=221 Evans Conf Room/] failed.</r:description>
    <r:oracle-calendar-error>
      <r:code>CAPI_STAT_DATA_USERID_EXT_NONE</r:code>
      <r:explanation>No users were identified by the string.</r:explanation>
    </r:oracle-calendar-error>
  </r:error>
  <r:results></r:results>
  <r:request>
    <r:procedure-call>addEvent</r:procedure-call>
    <r:as-user>?/ND=1/OU4=209826/</r:as-user>
    <r:acting-as-sysop>no</r:acting-as-sysop>
    <r:as-designate-for-calendar>?/RS=221 Evans Conf Room/</r:as-designate-for-calendar>
  </r:request>
</r:calendaraccess-results>

Calendar-WS: Web Services Interface to CalAgenda - Revision 1 of May 2005

Contents

Introduction

Connecting to the Web Services interface

Authenticating to the Web Services Interface

Remote Procedures in the Web Services Interface

Verifying Connections

Finding and Retrieving Events

Adding Events

Deleting Events

String Formats Used in Arguments to These Remote Procedures

userId String Format

calendarId String Format

Date/Time String Format

Unique Event ID String Format

Yes/No String Format

Results Returned by These Procedures

pingServer: Example Results

getEventsByRange: Example Results

getEvent: Example Results

addEvent: Example Results

deleteEvent: Example Results

Calendar Events Formats Returned in Results

iCalendar Format

xCalendar Format

Default Events Listing (xCalendar Subset) Used in the Web Services Interface

Error Descriptions Returned in Results

Calendar-WS:
Web Services Interface to CalAgenda - Revision 1 of May 2005