Calendar-WS
(formerly Calendar Access Project):
Functional Specifications - Summary

Introduction

Several campus and departmental applications at UC Berkeley need to be able to find, add, delete, and modify 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.

To make this possible, this project is developing interfaces that will offer those applications programmatic access to CalAgenda calendars.

Customers

A number of campus customers have requested programmatic interfaces which would permit them to integrate their applications with CalAgenda Calendars. We are now working with these customers to define their requirements for these interfaces. Representative examples of these campus customers and their applications include:

• The Career Center, which wants its student and alumni customers to be able to schedule appointments with career counselors online, through integration of its online appointments system with career counselors' CalAgenda calendars.
• Haas School of Business, whose MBA and MFE students are the primary student users of the CalAgenda service. Haas wants to add course schedules and other HSB events to its students' calendars, as well as integrate CalAgenda calendar events with schedules on the MyHaas portal.
• The Office of Student Life, which wants its online reservation request system to be able to manage events on the calendars for campus outdoor venues, such as the Faculty Glade.
• Student Information Systems, which is developing a pilot system to add course schedules to students' calendars. This service may be a critical element in justifying funding for a future expansion of the CalAgenda service to all UC Berkeley students.

Simplicity and generality are among the design goals for the programmatic interfaces for these initial customers. As such, these interfaces are intended to be able to substantially meet the needs of additional campus customers in the future, as well, although they may require some minor modification to do so.

Requirements overview

At a high level, the programmatic interfaces will need to permit applications to perform the following four types of actions on the calendar:

(Please see the Web Services Interface for detailed discussions of each of these actions.)

• Find and retrieve events
• Add a new event
• Delete an existing event
• Modify an existing event

Implementation overview

We currently anticipate offering these programmatic interfaces via Web Services, using the SOAP specification. SOAP is a standards-based method for communicating between two different pieces of programming code, and has the advantages of relative simplicity, widespread use, and extensive documentation.

Using SOAP will also provide compatibility with the widest range of programming languages and development tools used in our customers' applications. Toolkits for interacting with SOAP-based Web Services are available for many languages, such as C, C++, C#, Perl, Python, Java, JavaScript, Visual Basic, PHP, and Cold Fusion, among others. Many of these toolkits are free: either open source or included at no extra cost with commercial development environments.

These SOAP-based Web Services will be offered in a Remote Procedure Call ("RPC") paradigm, in which actions to be performed on calendars are offered via a set of remotely invocable procedures. This paradigm is familiar to customers, easier for them to use, and quicker to implement on the server side. Compared with its alternative, a document-style paradigm, the RPC paradigm concedes some flexibility, however.

Finally, these Web Services interfaces will be described using the Web Service Definition Language (WSDL) specification. WSDL descriptions will serve as a key component of the interfaces' documentation. Their existence can also benefit customers whose SOAP toolkits can generate client code, or take advantage of simpler programming models, when WSDL descriptions are available.

Implementation decisions & open issues

The following are some proposed implementation decisions, together with some open issues relating to some of those decisions:

• Four types of access to CalAgenda calendars will be granted to customer applications:
  1. Modify a user's calendar directly. A customer application may authenticate as a specific calendar user, then directly modify the calendar of that user.
  2. Modify other users' calendars as a "designate". A customer application may authenticate as a specific calendar user, then directly modify the calendars of any other users (people or resources) that have granted the appropriate "designate" and viewing rights to that user.
     
     To do so, the customer application would need to identify the user for which it wishes to act as a designate, either at initial login or subsequently.
  3. Invite other users to events. A customer application may authenticate as a specific calendar user, then invite other users to attend a newly created or modified event proposed by that user.
     
     Those invitations will appear in other calendar users' "In Trays," where they can be individually accepted or refused. Depending on each users's display settings, the time blocks associated with "unconfirmed" events may also be displayed in their calendars, even though these events have not yet been accepted.
  4. Modify other users' calendars as a sysadmin for a domain. A customer application may authenticate as a specific calendar user, then directly modify the calendars of any other users (people or resources) within a calendar "domain." (A "domain" will generally correspond to a single department or unit using the CalAgenda service.)
     
     To do so, the customer application would need to identify the calendar domain for which it wishes to act as a syadmin, either at initial login or subsequently. In addition, the Web Service interface will need to ensure that an application can only act on calendars for which it is authorized to do so.

• Customer applications that need to have designate access (option 2, above) to selected calendars will also have to set up the appropriate designate and viewing rights in each calendar that is to be accessed. In addition, these rights will need to be managed over time. Some ways in which this might be done include:
  • Using the Oracle Calendar client. The users of those calendars can manually set up or change designate rights by selecting various options in the Oracle Calendar client software for Windows, Mac OS, and the like. System administrators or support providers may also be able to do this, if they are at least temporarily given access to user accounts.
    
    This option may be feasible for applications which need to access the calendars of a relatively small, well-managed group of persons and resources.
  • Using tools on the CalAgenda servers. Using command-line administration utilities on the CalAgenda servers, or scripts or programs which call those utilities, CalAgenda's administrators could provide customer applications with designate access to selected calendars.
  • Via a Web interface. A hypothetical Web-based application, perhaps managed by the CalAgenda service could provide an interface through which users might "subscribe to" events offered by various campus applications, or otherwise grant permission to those applications to act as a designate for their calendars.
• It is currently proposed that the Web Services interface to CalAgenda will be accessible only via the encrypted HTTPS protocol, rather than via HTTP. In this way, Web Services sessions, including user passwords, will be encrypted between customer applications and the Web Services interface to campus calendars.
  
  The workability of this requirement for customer applications, as well as the possibility of alternatives to help keep authentication credentials secure, remains to be explored. One concern is that although many SOAP toolkits support SSL, some do not.
• As is the case with many other Web Services, the initial release of the currently proposed service will not maintain session state.
  
  This means that customer applications might potentially need to authenticate as frequently as each and every time they wished perform a new, discrete action, such as each time they needed to add a new event to a calendar. This would simplify programming for both customer applications and (particularly) the service.
  
  We do not currently believe that the overhead of the additional time required to do would be significant. However, if for performance considerations or based on customer requirements, maintenance of session state appears to be necessary, the service design should not preclude its addition.
• The service should provide detailed results regarding the success or failure of requested actions. These results should be in a format which allows customer applications to take appropriate follow-up actions based on the outcome of previously-requested actions, while remaining relatively simple for customer applications to process. If instances of repeating or recurring events are involved, the results format might also need to identify those instances individually. The initial results format is identified in the Web Services Interface.

Implementation alternatives

Oracle Corporation, the vendor of Oracle Calendar, the product currently used by the campus to provide the CalAgenda calendaring service, offers three programming interfaces that can be used to access calendars.

The following is a listing of these vendor-provided interfaces, as well as a discussion of why these interfaces were deemed unsuitable for offering programmatic access to CalAgenda calendars, thus prompting the campus's development of its own interface:

• A set of command-line administration utilities.

  This interface is unsatisfactory for use by customer applications because:

  • These utilities must be run with specific privileges directly on the Oracle Calendar server host.
  • When run with those privileges, these utilities provide comprehensive access to all CalAgenda calendars.

  As such, they are suitable for use by CalAgenda's administrators, but not by external applications.

• The Oracle Calendar Software Development Kit (CSDK), which provides application programming interfaces (APIs) in C and Java for accessing calendars over the Internet. Oracle makes this kit freely available for use by developers.

  This interface is unsatisfactory for use by customer applications because:

  • The CSDK is complex, and thus would require considerable work on the part of each developer to learn, as well as to 're-learn' whenever their CSDK-based code needed to be maintained at a future time.
  • Developers would also need to create this CSDK-based code in C or Java. If they did not know those languages, they would need to learn them.
  • Each customer application would need to write custom code to integrate this CSDK-based code with its existing code. Often, this would require integrating C or Java code with code written in different programming languages, such as PHP or Perl.
  • Any changes in the CSDK API over time might require each campus developer to change their code for compatibility with these changes, or to be able to access new features.

• A Web Services interface, which on the server side acts as a wrapper around the CSDK. This simplified interface provides access to selected CSDK functionality via SOAP remote procedure calls. This interface also includes Java classes intended to further simplify programming on the Web Services client side.

  This interface is the closest of the three Oracle-provided interfaces to being ready for use by our customers. However, it is currently unsatisfactory for the following reasons:

  • Designate access is missing. In the Oracle-provided Web Services interface, a Web Services client can only authenticate as, and then perform actions affecting the calendar of, a specific user or resource. This would require customer applications to know the passwords for each person's or resource's calendar they wished to modify!
    
    The underlying reason for this requirement is that the Oracle-provided interface lacks an option for a Web Services client to act as a "designate," permitting it to access other user or resource calendars whose settings allow such access. This is a critical issue, as designate access to calendars is expected to be a key requirement of some of our customers.
    
    Oracle does offer one alternative: the equivalent of "root" access (via a "ProxyAuth" mechanism). However, this alternative provides too much access, as it would give any customer application the ability to modify every personal and resource calendar on the CalAgenda service, not just those calendars to which the application has designate access rights.
  • The ability to invite attendees to an event is missing. Oracle's Web Services interface does not currently provide a mechanism for inviting other users ("attendees") to an event, either when initially creating the event or when modifying the event. The ability to invite attendees is expected to be a key requirement of some of our customers.
  • No "convenience methods" are provided. Oracle's Web Services interface requires that you construct and submit various objects to its remotely invocable procedures, such as event and query objects.
    
    On the other hand, our customers have requested a simpler programming interface, consisting of a set of "convenience methods" which can be invoked without having to construct and submit objects. For instance, a customer application might be able to add an event to a calendar merely by invoking an 'add event' convenience method and supplying just three arguments: the event's title and its beginning and ending times, together with any authentication information required by the interface.
  • WSDL descriptions are missing. Oracle does not publish WSDL descriptions of its Web Services interfaces. Instead, its documentation is primarily focused on the use of its own client-side Java classes (below). Oracle does provide summary documentation of its Web Services interface, but that documention is cursory and for the most part limited to highly skeletal examples of SOAP messages invoking procedures in this interface.
    
    While from those examples it does appear to be technically feasible to work with Oracle's Web Services interface from other programming languages and Web Services toolkits, the lack of WSDL descriptions of that interface's procedures makes it substantially more difficult to do so.
  • Oracle expects that developers will use its own client-side Java classes. The Oracle-provided Web Services interface, and its documentation, is highly focused on the use of a set of client-side Java classes.
    
    Oracle's Java classes are extremely well thought out, and can help simplify many tasks for developers. As Oracle notes, its Calendarlet "classes attempt to hide the many details of using web services technology in a Java environment." Other classes provided by Oracle, such as iCalendar and CalendarUtils, greatly simplify building the calendar, event, and query objects required to make requests to Oracle's Web Services interface and to process some of the results returned from that interface.
    
    However, taking advantage of these classes requires using both the Java programming language and the Apache SOAP Web Services toolkit for Java. This is likely to be unacceptable to some of our customers, whose applications and development environments are focused on other programming languages.

  We have been in communication with Oracle regarding these concerns regarding its current Web Services offering, and the vendor is aware of these issues. Oracle has told us that among the enhancements they are planning to incorporate into the next release of its Web Services interface, which is due in the first quarter of 2005, are publication of WSDL descriptions and the ability to invite attendees to meetings. This means that, within about six months, two of our customers' requirements might potentially be met by Oracle's offering.

  However, designate access and convenience methods, two other key requirements of our customers, are not currently expected to be offered, even in that forthcoming release. For this reason, we plan to proceed with the development of a campus-provided Web Services interface to CalAgenda.

  We expect that our campus-developed Web services interface for accessing calendars - and the experience of our customers' application developers in using it - will be of interest to Oracle when this vendor initiates work on future generations of its Web Services interface. In part on the basis of what we expect will be compelling, "real world" feedback we can offer to Oracle, perhaps our customers' requirements might yet be fully met by a future release of that vendor's Web Services offering. At that time, we could then transition our customers to that product.