Events Module v. 3.4 Design

I. Essentials

User Directory: /www/events/
Sitewide Administration Directory: /www/admin/events/
Subsite Administration Directory: /www/events/admin/
TCL Script Directory: /tcl/
Requirements Document: /www/arsdigita/doc/requirements/events.html
Data Model: /www/arsdigita/doc/sql/events.sql
Page Flows: /arsdigita/doc/page-flow/events_interaction_admin_1 and /arsdigita/doc/page-flow/events_interaction_users
ER Diagram: /arsdigita/doc/er-diagrams/small_events_er

II. Introduction

Online registration offers little benefit or incentive for people to actually enroll for an event. Why have online registration then? The power of online registration lies not in its ability to empower registrants but event administrators. For example, online registration can enable event planners to:

Make it easy to offer repeated events
Make it easy to collect, aggregate, and view registrations
Provide convenient means for communicating with registrants
Provide means for coordinating registrants

Online registration does not, however, save registrants much in the way of time or effort. Furthermore, people who truly wish to attend an event are not likely to find filling out a paper registration form a tremendous deterrent to attending that event. Thus, the design of the events module aims to optimize enterprise event creation and management while still providing full registration capabilities for users. The events module is not merely a registration collector--it is a complete event planning and management system that helps organizations to create events and aggregate, communicate with, and coordinate event registrants.

III. Historical Considerations

The roots of the events module stem from the old chatauqua registration code on the now defunct register.photo.net site. ArsDigita used to collect at register.photo.net registrations for lectures it would hold using a model of talks and lectures. A talk was a presentation on a certain subject, and a lecture was a specific instance of a talk. People would decide they were interested in a certain talk and sign up for one of those talks' lectures. For example, ArsDigita might hold a talk entitled, Web Tools For Online Communities. A lecture for which someone could register would be Web Tools For Online Communities, occurring at Berkeley, CA on November 19,1999. This model worked well for ArsDigita because its talks tended to remain upon a fixed set of subjects, while its lectures would vary in time and location.

Eventually, ArsDigita decided that it wanted a more generic events registration system that integrated with the ACS. However, it wished to keep its flexibility of being able to easily create repeating events just the way that it could easily offer repeating lectures based upon the same talk. Therefore, the events module was formed around the concept of activities and events, where events are instances of activities just as lectures are instances of talks. Consequently, rather than restricting administrators to only creating talks, the events module enables people to create activities such as a conference and events such as a conference in Boston, MA from August 17-21, 2000. Thus, the events module kept chatauqua's ability to offer repeated lectures easily and generalized it to activities and events.

In addition to providing means for creating and managing activities and events, the events module also yields tools for processing event registrations, aggregating registration information, and communicating with event registrations. These tools enable Web site operators to efficiently oversee their events.

IV. Competitive Analysis

Key3Media

Because the events module focuses on enabling event administrators rather than event registrants, it offers significant advantages against most online registration offerings, which traditionally view Web-based registration as simply another way to collect registration information. Registration sites which do not offer special capabilities for event planners lose out on much of the power and efficiency that comes from offering events online. For example, Key3Media is a large company which handles online registration for a number of events, including Comdex, JavaOne, and Linux Business Expo. But, Key3Media treats online registration as nothing more than another means to collect information as part of a complicated setup for registering people.

Key3Media collects registration information for events through both paper and Web applications. Web applications go directly into a database; paper applications are entered into the database by Key3Media employees. Once Key3Media processes an application, it sends a confirmation message to the application's registrant. Online registrants receive an online confirmation, and paper applicants receive a paper confirmation.

Upon completing signups for an event, Key3Media exports all of its registration information into a file -- typically a Microsoft Excel spreadsheet -- and gives the file to another company. This company serves as a "holding tank" for the registration data and eventually passes the records to a third company. This third company may be the Key3Media client running the event or perhaps a company building a Web site for the client's event, and it uses the registration data as it wishes.

Key3Media's solution for handling event registration seems to work fine for collecting information. But, its solution does little to help event planners communicate with registrants, coordinate registrants, and aggregate information about registrants. Key3Media cannot inform a client for what other of the client's events a person has registered. Key3Media cannot help registrants collaborate and communicate. Key3Media cannot offer a centralized, unified, and integrated interface to event management. The events module, by focusing on event planners, does offer all these features in addition to facilitating easy online event-registration.

One significant reason for choosing Key3Media is that it will process both paper and electronic registrations. Because the events module is a Web-based application, it cannot intrinsically handle paper applications. However, event administrators may still take advantage of the planning and organizing capabilities of the events module while contracting out registration-handling to a company like Key3Media.

Evite.com

Although most Web sites that offer online registration do not support much functionality for event planners, there are a number of sites springing up which offer users some basic abilities to plan and organize personal functions. Evite.com (http://www.evite.com) is one such popular site.

Evite.com focuses on helping users to plan events for which they would like to invite guests. It does this by offering a simple interface for individuals to:

plan a series of events
invite people to those events
RSVP to events to which they are invited
see who is coming to their events
remind themselves about events

In many ways, Evite.com and other, similar sites (http://socialeventplanner.com, http://invites.yahoo.com, http://www.pleasersvp.com, and so on) understand that their sites are useful because they enable people to plan and organize events. Evite even supports, to some extent, the four goals outlined for the events module.

Evite supports repeating events as well as the distinction between activities and events. For example, a user can create invitations for a "Birthday" event and have this Birthday event repeat every year. Birthdays, then, are like activities in the events module, and the annual Birthday parties are like events within the events module. Evite.com, though, does not support creating arbitrary activities like the events module.

Evite helps users handle registrations by allowing users to setup lists of guests to invite to their events. Once a user has setup a guest list for an event, Evite sends e-mail to each person on the user's guest list, notifying him that he has been invited to an event. Evite also allows these invitees to RSVP so that users may see who is coming to their events. Evite lacks, however, a number of the aggregation and advanced registration-handling functions of the events module. Evite also does not let users create events for which arbitrary users can register -- event registrants must first be invited.

Communicating with invitees through Evite takes place through Evite's address book features. Users may store email contacts and create groups of contacts within their address book. Then, they can send e-mail to individual e-mail addresses or to groups of e-mail addresses. This functionality seems fairly limited as it does not provide much support for communicating within the context of an event. For example, users cannot ask to e-mail "all the people who attended these three events" -- as they could within the events module.

If Evite offers limited communications capabilities, it supports even fewer community-building options. Unlike the events module, which supports a host of community capabilities through other ACS modules, Evite merely lets invitees see who else is coming to a particular event.

Evite.com and other event planning sites on the Internet are optimized to help individuals plan social events like a Memorial Day barbeque. The events module was designed to handle enterprise event planning and registration -- and is consequently much more powerful than a site like Evite.com. People may still use the events module, though, to implement something like Evite.com; its data model and Web pages intrinsically support virtually all of the functionality of Evite.

V. Design Tradeoffs

One of the guiding principles in designing the events module was to make it simple to offer repeating events based upon activities. This feature greatly enables organizations that offer activities on a periodic basis--as most organizations do. However, this design is not the most efficient one for those who do not generally offer recurring activities.

The event module's interface involves creating separate activities, events, and venues in order to preserve the flexibility of offering repeating events. But, this process is overly cumbersome for people who just want to offer a one-time event. A more efficient solution would be to simply provide the event creator with one simple form asking for all the details about an event. This solution would not, though, readily facilitate repeating events.

VI. Data Model Discussion

The events module's data model consists of four main sections:

tables for managing the events
tables for collecting custom fields
tables for managing events organizers
tables for managing events registrants

Managing Events

Activities

An organization is not necessarily an entire company -- it can be a company department or office or project or any other group of people. Therefore, activities are owned by ACS user groups. Each user group represents an organization of people. An activity also has a creator, a name, a description, and a flag indicating if it is available. Finally, an activity can link to a url for more information:

create table events_activities (
	activity_id	integer primary key,
	-- activities are owned by user groups
	group_id	integer references user_groups,
        creator_id      integer not null references users,
	short_name	varchar(100) not null,
	default_price   number default 0 not null,
	currency	char(3) default 'USD',
	description	clob,
        -- Is this activity occurring? If not, we can't assign
        -- any new events to it.
        available_p	char(1) default 't' check (available_p in ('t', 'f')),
        deleted_p	char(1) default 'f' check (deleted_p in ('t', 'f')),
        detail_url 	varchar(256), -- URL for more details
	default_contact_user_id integer references users
);

Events

Information about the events are stored in the tables events_events, events_prices, and events_venues. events_events tracks data such as an event's start and end times, where it occurs, and how many people may register for it.

create table events_events (
        event_id              integer not null primary key,
        activity_id	      integer not null references events_activities,
	venue_id	      integer not null references events_venues,
	-- the user group that is created for this event's registrants
	group_id	      integer not null references user_groups,
	creator_id	      integer not null references users,
        -- HTML to be displayed after a successful order.
        display_after         varchar(4000),
        -- Date and time.
        start_time            date not null,
        end_time              date not null,
	reg_deadline	      date not null,
        -- An event may have been cancelled.
        available_p	      char(1) default 't' check (available_p in ('t', 'f')),	
        deleted_p	      char(1) default 'f' check (deleted_p in ('t', 'f')),
        max_people	      integer,
	-- can someone cancel his registration?		
	reg_cancellable_p     char(1) default 't' check (reg_cancellable_p in ('t', 'f')),
	-- does a registration need approval to become finalized?
	reg_needs_approval_p  char(1) default 'f' check (reg_needs_approval_p in ('t', 'f')),
	-- notes for doing av setup
	av_note		      clob,
	-- notes for catering
	refreshments_note     clob,
	-- extra info about this event
	additional_note	      clob,
	-- besides the web, is there another way to register?
	alternative_reg	      clob,
        check (start_time < end_time),
	check (reg_deadline <= start_time)
);

This data model contains, through events_prices, extensions for selling admission to events. The presentation pages, however, do not currently implement this feature. These extensions can tie in with the ecommerce module.

create table events_prices (
    price_id            integer primary key,
    event_id            integer not null references events_events,
    -- e.g., "Developer", "Student"
    description         varchar(100) not null,
    -- we also store the price here too in case someone doesn't want
    -- to use the ecommerce module but still wants to have prices
    price		number not null,
    -- This is for hooking up to ecommerce.	
    -- Each product is a different price for this event.  For example,
    -- student price and normal price products for an event.
--  product_id          integer references ec_products,
    -- prices may be different for early, normal, late, on-site
    -- admission,
    -- depending on the date
    expire_date	      date not null,
    available_date    date not null
);

The table events_venues retains knowledge about all the different locations in which an event might take place.

Collecting Custom Fields

One of the hallmark features of the events module is its ability to let event administrators collect customized information from events registrants. Organizations are usually interested in obtaining more than just a name and e-mail address. For example, a company might request registrants to provide their resumes. The company could do this in the events module by creating a custom field for its event called resume.

create table events_event_fields (
	event_id	not null references events_events,
	column_name	varchar(30) not null,
	pretty_name	varchar(50) not null,
	-- something generic and suitable for handing to AOLserver, 
	-- e.g., boolean or text
	column_type	varchar(50) not null,
	-- something nitty gritty and Oracle-specific, e.g.,
	-- char(1) instead of boolean
	-- things like "not null"
	column_actual_type	varchar(100) not null,
	column_extra	varchar(100),
	-- Sort key for display of columns.
	sort_key	integer not null
);

Managing Organizers

Each event should have at least one organizer role. An organizer role is an official position for that event. For example, a lecture might have the organizer role of "speaker." Organizers are people who fill an organizer role position.

create table events_event_organizer_roles (
       role_id			integer 
				constraint evnt_ev_org_roles_role_id_pk 
				primary key,
       event_id			integer 
				constraint evnt_ev_org_roles_event_id_fk 
				references events_events
				constraint evnt_ev_org_roles_event_id_nn
				not null,  
       role			varchar(200) 
				constraint evnt_ev_org_roles_role_nn
				not null,
       responsibilities		clob,
       -- is this a role that we want event registrants to see?
       public_role_p		char(1) default 'f' 
				constraint evnt_ev_roles_public_role_p
				check (public_role_p in ('t', 'f'))
);

create table events_organizers_map (
       user_id			   constraint evnt_org_map_user_id_nn
				   not null
				   constraint evnt_org_map_user_id_fk
				   references users,
       role_id			   integer 
				   constraint evnt_org_map_role_id_nn
				   not null 
				   constraint evnt_org_map_role_id_fk
				   references events_event_organizer_roles,
       constraint events_org_map_pk primary key (user_id, role_id)
);

Managing Registrations

For each person who registers for an event, the software helps organizations understand who is coming to their events and why. It also helps an organization accommodate its attendees' needs and group them together.

The events module organizes registrations in the following way: a registration represents a person who has expressed interest in attending the event. There is one registration for each person who wants to attend. Registrations can have different states. For example, a registration may be wait-listed because there are already too many registrations for a particular event. Or, a registration may be canceled.

An order is a set of registrations. Typically, when a person registers himself for an event, he will create one order containing his single registration. But, there may be an individual who wishes to register multiple people at once. In that case, the individual would make one order containing multiple registrations. Thus, this data model allows people to make multiple registrations. The Web pages do not yet implement this feature, though.

create table events_orders (
       order_id		integer not null primary key,
--       ec_order_id	integer references ec_orders,
       -- the person who made the order
       user_id		integer not null references users,
       paid_p		char(1) default null check (paid_p in ('t', 'f', null)),
	payment_method	varchar(50),
	confirmed_date	date,
	price_charged	number,
	-- the date this registration was refunded, if it was refunded
	refunded_date	date,
	price_refunded	number,	
       	ip_address	varchar(50) not null
);

create table events_registrations(
        -- Goes into table at confirmation time:
	reg_id		integer not null primary key,
	order_id	integer not null references events_orders,
	price_id	integer not null references events_prices,
	-- the person registered for this reg_id (may not be the person
	-- who made the order)
	user_id		integer not null references users,
	-- reg_states: pending, shipped, canceled, waiting
	--pending: waiting for approval
	--shipped: registration all set 
	--canceled: registration canceled
	--waiting: registration is wait-listed
	reg_state	varchar(50) not null check (reg_state in ('pending', 'shipped', 'canceled',  'waiting')),
	-- when the registration was made
	reg_date	date,
	-- when the registration was shipped
	shipped_date	date,
	org		varchar(4000),
	title_at_org	varchar(4000),
	attending_reason  clob,
	where_heard	varchar(4000),
	-- does this person need a hotel?
        need_hotel_p	char(1) default 'f' check (need_hotel_p in ('t', 'f')),
	-- does this person need a rental car?
        need_car_p	char(1) default 'f' check (need_car_p in ('t', 'f')),
	-- does this person need airfare?
	need_plane_p	char(1) default 'f' check (need_plane_p in ('t', 'f')),
	comments	clob
);

VII. Legal Transactions

/events/admin/

The following legal transactions can occur from the events administration pages located under /events/admin:

activities

Activities may be created, edited, and marked as discontinued. They cannot be deleted through the user interface. Default activity custom fields may be created, deleted, and swapped with other fields within the same activity. Default activity organizer roles may be created, edited, or removed.

venues

Venues may be created, edited, or deleted.

events

Events may be created, edited, and marked as discontinued. They cannot be deleted through the user interface. Default event custom fields may be created, deleted, and swapped with other fields within the same activity. Default event organizer roles may be created, edited, or removed. A user group is created for each event--these should not be deleted. Events may store agenda files, which are removable.

registrants

Event admins may add comments to registrations . They may change a registration's state. They cannot delete a registration. If they approve a registrant, the registrant is added to the event's user group.

e-mail

The events module sends e-mail through the ACS Spam Module. Therefore, any spam sent through the events module's user interface causes legal spam transactions.

/admin/events/

The following legal transactions can occur from the site-wide administration pages located under /admin/events/:

event administrator

A site-wide administrator can add a user (including himself) to the events administration user group, making that user an event administrator.

user groups

A site-wide administrator can add a user to any or all of the user groups which own event activities--thus enabling that user to administrate those user groups' activities.

/events/

The following legal transactions can occur from the user pages located under /events/:

register

A user may register for an event. This will store the user's registration, his order, his personal information in the users_contact table, as well as any custom information the event collected from him. If the user is automatically approved upon registration, he is added to the event's user group.

update registration

A user may update his registration or personal information.

cancel registration

A user may change his registration state to "canceled." He may not manually change his registration state to any other state.

VIII. API

The events module implements the following procedures which other developers might find useful:

PL/SQL Procedures

delete_user_group(v_group_id IN integer): This procedure deletes a user group. It was intended as a helper procedure for events_delete_event.

events_delete_event(v_event_id IN integer): This procedure deletes an event, along with the event's registrations as well as user group.

Scripting (TCL ) Procedures

events_user_admin_p: returns 1 if current user is an events administrator.

events_event_name {event_id}: Returns the event's name. Returns an empty string if event_id is not valid

events_group_add_user {event_id user_id}: Add's user_id to the user group of event_id's event. Returns 1 if successful, else returns 0.

events_group_create {name date location}: Given an event's name, date, and location, creates a user_group for that event and returns the new group's group_id. Returns 0 if an error occurs

events_pretty_venue {venue_id}: returns a pretty location based upon a venue_id. If the venue_id is invalid, returns an empty string

events_pretty_venue_name {venue_id}: returns a pretty location and that location's name based upon a venue_id. If the venue_id is invalid, returns an empty string

events_state_widget {{default ""} {size_subtag "1"} {sel_name "state"}}: returns a select box of U.S. States. default is the default state to select. size_subtag is the size of the select box. sel_name is the form variable name of the states.

events_venues_widget {{default "" } {size_subtag "size=4"}}: returns a select box of venues. default is the default venue to select. size_subtag is the size of the select box.

events_pretty_event {event_id}: Returns a pretty description of the event. Returns an empty string if event_id is not valid

events_member_groups_widget {user_id {group_id ""}}: returns a select box of all the user groups to which the user represented by user_id belongs. If group_id is set, that group is selected by default

events_user_contributions {user_id purpose}: Returns list of events for which this user has registered. If purpose is "site_admin," the events will be linked to their admin pages.

events_new_stuff {since_when only_from_new_users_p purpose}: returns a list of new event registrations since since_when and optionally only from new users if only_from_new_users_p is "t." If purpose is "site_admin," then the registrations will be linked to admin pages.

IX. User Interface

The vast majority of the events module's Web interface is located in its admin directory. From these pages, an event administrator can manage his events and event registrants.

The Main Admin Page

The main administration page provides a summary of current event registrations and links to the key functions he can perform:

Managing activities
Managing venues
Viewing order histories
Spamming (e-mailing) registrants

Managing Activities and Events

As previously stated, one of the goals of the events module was to facilitate repeating events through the use of activities and events. Separate admin pages for managing activities and events accomplish this goal. Furthermore, the event admin page links to pages which fulfill other goals for the events module: The event admin page links to pages displaying order-histories, helping administrators handle registrations. It also links to pages for e-mailing registrants, providing for easy communication to registrants. Finally, it links to the event's user group, letting the administrator coordinate registrants.

One of the links from the main administration page is for managing venues. Venues are locations where events occur. Since an organization or person's events will usually take place within a certain set of venues, the events module provides a means of creating and managing these locations. Then, when an event administrator creates an event, he can easily select an existing venue for his event -- and save himself the work of typing in all the relevant information for that venue again.

Managing Registrations

The Order History pages provide most of the functionality for managing registrations. From these pages, event administrators can view aggregated registration information and answer questions such as, "how many people registered for that event," or "how many people placed registrations on this date?"

Event administrators can also view a single registration and perform actions upon it, like approving it.

E-mailing Registrants

When a person places a registration in the events module, he has to provide his e-mail address. This means that event administrators can e-mail groups of registrants and individual registrants from the admin pages -- perhaps, for example, to advertise an upcoming, similar event.

Coordinating Registrants

Because the events module is part of the ArsDigita Community System (ACS), it has access to all of the community-building features within the ACS. Each event, as explained earlier, has a corresponding ACS user group. All registrants for a particular event are automatically placed into their respective event's user group. This means that event administrators can easily provide, using other ACS modules, the ability for an event's registrants to communicate and collaborate together in a variety of ways. For example, the event administrator could add a bboard to an event's user group. Then, the individuals within that user group could post messages for each other. The link to managing the event's user group comes from the event admin page.

User Registration

Although the power and convenience of online registration benefits events administrators the most, registrants should still find it simple to register for an event. Thus, the user interface for placing a registration is fairly straightforward. The events module tries to fill in as much personal information as possible for the registrant if he is already an ACS user of the registration Web site. Then, the user must simply provide the rest of the registration material in which the even planners are interested.

X. Acceptance Test

You should make sure that you can create an event, register for it, and review registrations.
Suggested method:

Create a venue
Create an activity
Create an event for that activity
Add organizers to that event
Register for an event
Cancel a registration
Review order histories

XI. Future Improvements

There are several areas within the events module targetted for future improvement. First of all, the data model for the events module supports functionality which the Web pages do not yet implement. These main features are support for various event prices, support for online payment for events, and support for multiple registrations per order. Adding these features will enable organizations to charge registrants for their events, charge different types of registrants different amounts of money, and allow one person to place multiple registrations on behalf of other people.

Another key area which ArsDigita plans to extend is support for sub-communities. Currently, the events module is not "scoped" -- individual user groups cannot have their own instance of the events module. However, since ArsDigita is in the process of reworking how it implements module scoping, it is waiting to finish the new scoping API before adding this feature to the events module.

Finally, there are some areas in the data model ArsDigita plans to re-write because they are not efficient. Foremost of these areas is how the module handles event custom fields. Currently, the data model is styled after the user group module and creates a new event_n_info table for each event. Ideally, the module would store custom information within the user_group_member_fields/user_group_member_field_map tables. But, these tables do not support enough data types for the events module yet. There are plans, though, to update these user group tables in the near future so that the events module may store information within them for registrants.

XII. Authors

System creator: Bryan Che
System owner: Bryan Che
Documentation Author: Bryan Che

bryanche@arsdigita.com