ACS Events Service Requirements
by W. Scott MeeksI. Introduction
This document records the requirements for a new ACS Events service package. This package is intended to provide basic functionality which can be used in a consistent manner by other service and application packages. The events service specifies relationships (possibly recurring) between a set of time intervals time, an activity, and an arbitrary number of parties. An activity can be associated with an arbitrary number of ACS objects.
II. Vision Statement
The ACS Events package will provide support for other services and applications that require representing this sort of relationship between time, parties, activities, and objects. Such applications include the generation of calendar objects, room reservations, event registration, and possibly workflow.
The service needs to support recurring events. Many applications need to represent blocks of time within a given day that are intended to be be repeated regularly on subsequent days. The service should support representing the most common types of recurrences: daily, weekly, monthly, et cetera. It should also provide for custom recurrences.
Having a single service for this functionality provides a number of business advantages:
- It saves work and increases quality; applications that deal with time don't have to "re-invent the wheel" but instead can use a common, tested code base.
- It improves consistency; the same API will be used in different applications.
- It simplifies integration; since a common data model is used to represent events, different applications can more easily share related information.
For example, the events service could support a room reservation application that is integrated with an application which maintains users's personal and group calendars. Suppose Stephanie uses the room reservation application to reserve the Boston 1st floor conference room on 11/11 from 1pm to 2pm for Ern, Allen, and Alan. The events service will add a new event for this time slot, add a mapping to Ern, Allen, and Alan, and an activity for the meeting. This activity will map to the conference room. Now to get a calendar item to appear on Ern, Allen, and Alan's calendars, the reservation application can simply pass the event to the calendar application which adds a mapping between the activity and a new calendar item.
III. ACS Events Package Overview
There are four main areas of functionality in the events package: events, time intervals, activities, and recurrences. The service depends upon the ACS object and parties systems.
III.A Events
An event is an activity associated with a temporal interval or several such intervals. Events may have additional attributes as well. Examples of events include: "hitchhiking from 4pm to 5pm", "attending the InSync concert from 11pm to 1am at the Enormodome", et cetera. Events are represented by designating the associated activity together with a set of time intervals indicating when that activity is to occur.
An event can optionally be mapped to a set of parties representing groups or individuals that have some connection to the event.
The service provides an API for manipulating events.
An event is a relationship which maps parties and an activity to a set of time intervals. The relationship between a particular event can be one to many with parties. Time intervals can be open ended.
Activities contain a name, a description, and an optional link to related information. Ativites can be mapped one to many to ACS objects. The object mapped to a particular activity can be another activity or event.
III.B Time Interval Sets
A time interval set is a range of moments at which an event can occur. A single time interval is of the form "from 3:00pm to 3:17pm on 11/20/2000". A time interval set is of the form "from 3:00pm to 3:17pm and from 4:30pm to 4:45pm on 11/20/2000". A set of time intervals has two advantages: (i) it allows for the representation of temporally gappy events such as conferences, which end one day and pick up again the next, and (ii) if implemented properly, it allows a simplification of the above account of events, as now an event can be identified with a pair of an activity together with a time interval set.
The service provides an API for manipulating time interval sets.
III.C Activities
An activity is a thing that a person or people do, usually represented by a gerundic phrase, such as "biking", "reserving a room", "travelling to Bhutan to achieve enlightenment", et cetera. Activities are represented via a name and a description. An activity can optionally be mapped to a set of ACS objects.
The service provides an API for manipulating activities.III.D Recurring Events
Consider an event, say, an activity A performed on day D at time T. The ACS Events service allows applications to generate new events which are the same activity A performed on different days in the future, but at the same time of day T; such events are said to be recurrences of the primary event. Recurrences can happen on a daily, weekly, monthly, yearly or custom basis. The start and end dates of recurrences can be uniformly offset.
III.E Dependencies
The service depends on the ACS object model and on our parties system. Event is a subtype of acs_object. The ACS Events service maps between the event object, a time interval set, an activity, and an arbitrary number of parties.
IV. Use-cases and User-scenarios
Determine the types or classes of users who would use the system, and what their experience would be like at a high-level. Sketch what their experience would be like and what actions they would take, and how the system would support them.
V. Related Links
- System/Package "coversheet" TBD
- Design document TBD
- Developer's guide TBD
- User's guide TBD
- 3.4 calendar package documentation
- Reservations module
- Problem Set 2 revised for ACS 4.0
- Test plan TBD
VI.A Data Model Requirements
10.10 Events
10.10.10 The data model represents activities associated with sets of time intervals.
10.10.20 Events can optionally be associated with parties.
10.10.30> Events can optionally recur.
10.20 Time Interval Sets
10.20.10 A time interval consists of a start time and an end time.
10.20.20 A time interval set consists of a set of associated time intervals.
10.20.30 Individual time intervals can be open ended. That is, the beginning time, ending time, or both may be null. The exact meaning of a null time is application dependent. However, as a suggestion, null end time could indicate events such as holidays or birthdays that have no particular start time associated with them. Null start time could indicate a due date. Both times null could indicate some item that needs to be scheduled in the future but does not yet have a set time.
10.30 Activities
10.30.10 An activity has a name and a description.
10.30.20 An activity can be associated with a set of ACS objects.
10.30.30 An event object can be a valid target for an activity. This could indicate time dependencies, e.g. for workflow or project management.
10.50 Recurring Events
10.50.10 The data model provides a table which describes how to generate recurrences from a base event.
10.50.20 Recurring on a daily basis should be supported.10.50.30 Recurring on a weekly basis should be supported. For weekly recurrences, it should be possible to specify exactly which days of the week.
10.50.40 Recurring every month on a particular date should be supported.
10.50.50 Recurring every month on a particular day of a particular week should be supported.
10.50.60 If a date in the 4th or 5th week of a month has been selected, then an option should be presented allowing an item to recur on a particular day of the last week of a month.
10.50.70 Recurring yearly on a particular date should be supported.
10.50.80 The data model should allow an application to provide a custom recurrence function.
10.50.90 It should be possible to specify an end date for recurrences.
10.50.100 It should be possible to specify no end date for recurrences.
10.50.110 The service should enforce reasonable limits on the amount of data used to represent recurring events. In other words, it should not be possible to fill the DB with thousands of rows representing a single recurring event, even if it recurs indefinitely.
10.50.120 The service should provide a view for querying on those recurrences that aren't fully populated in the DB.
VI.B API Requirements
20.10 Event API
20.10.10 The service supports adding an event.
20.10.15 The service supports setting the time interval set of an event.
20.10.20 The service supports setting the activity of an event.
20.10.30 The service supports adding or deleting a party mapping to an event.
20.10.40 The service supports deleting a complete event.
20.20 Time Interval Set API
20.20.10 The service supports adding a time interval set.
20.20.20 The service supports adding a time interval to a set.
20.20.30 The service supports updating the start or end dates of a time interval.
20.20.40 The service supports deleting a time interval from a set.
20.20.50 The service supports counting the number of time intervals in a set.
20.20.60 The service supports determining if a given interval overlaps a particular time interval set.
20.30 Activity API
20.30.10 The service supports creating an activity.
20.30.20 The service supports deleting an activity.
20.30.30 The service supports updating the name of an activity.
20.30.40 The service supports updating the description of an activity.
20.30.50 The service supports adding or deleting an object mapping to an event.
20.50 Recurrence API
20.50.10 The service supports adding recurrences of an event.
20.50.20 The service supports deleting recurrences of an event.
20.50.30 The service supports uniformly offsetting the start or end times of time intervals of recurrences of an event.
20.50.40 The service supports determining if an event recurs.
VII. Design and Implementation Notes
VII.A 3.4 Calendar Package
The 3.4 calendar package provides some ideas for the design and implementation of the events service. One way to look at the service is as a distillation of the components of the calendar data model and implementation which would be common to any event-based application. In particular, I anticipate the table for recurring information will be very similar to the calendar data model for recurring items.
VII.B Problem Set 2
Another way to look at this events service is as an elaboration of the scheduling service in Problem Set 2 revised for ACS 4.0. The main differences are allowing multiple time intervals, and a one to many relationship with parties and objects. Thus the data model will have the core event_id, and repeat_id in the event subtype of acs_object. Time Intervals will be in a separate table. The parties column and object column will be split out into separate mapping tables.
VII.C Recurring Events
There is a very important tradeoff to be made in the implementation of recurring events. Calendar Design Tradeoffs details this tradeoff as applied to the 3.4 calendar package.
There are two main choices for supporting recurring events. One choice is to insert only a single row for each recurring event, regardless of the number of times it will recur. This row contains all the information necessary to compute whether or not that event would recur on a particular day. The alternative is to insert a row for each recurrence.
I favor the second approach for the following reasons. First, one tradeoff is time vs. space. Computation, particularly if it might need to be done in Tcl and not solely in the database, is relatively expensive compared to storing additional information in the database. In many cases, the only information that will need to be stored for recurrences is the date and time of the recurrence.
Another reason is that the first approach, to insert only a single row, seems to require a significantly more complex design. Thus the design, implementation and eventual maintenance time would be greater.
This approach will also make it much easier to handle exceptions to recurrences and individualizing the objects associated with instances of events.
However, there are drawbacks to this approach. First, it will be more difficult to handle events that recur indefinitely. Second (but related) is that safeguards will need to be put in place to prevent pathological (accidental or intentional) cases from swamping the database.
Another issue is that when populating the DB with recurring event instances, there is an application-level choice that the service needs to support. This is the decision as to whether the new event instances are mapped to the same object or to newly created objects. For example, for the reservation application, the instances should be mapped to the same room object. Alternately, for the calendar application, the instances should be mapped to new calendar events so that each instance can be modified individually.
VIII. Revision History
| Document Revision # | Action Taken, Notes | When? | By Whom? |
|---|---|---|---|
| 0.1 | Creation | 11/13/2000 | W. Scott Meeks |
| 0.2 | Revision, remove timezones, add multiple timespans | 11/14/2000 | W. Scott Meeks |
| 0.3 | Rename "scheduling" to "event handling". Add activities. Renaming and updating requirements. | 11/15/2000 | W. Scott Meeks |
| 0.4 | Remove approval in favor of requiring applications to use acs-workflow. | 11/17/2000 | W. Scott Meeks |
| 0.5 | Name of package changes from "Event Handling" to "ACS Events". | 11/17/2000 | W. Scott Meeks |
| 0.6 | Clean up, clarification, rewording | 12/08/2000 | Joshua Finkler |
smeeks@arsdigita.com Last modified: $Date: 2024/09/03 08:43:03 $
