Draft Specification This is a draft specification. We are actively soliciting community feedback prior to finalizing the specifications on or around December 7. Please review this document carefully and post feedback and questions as comments on this page. This document reflects feedback and suggestions from many folks in the CiviCRM and Drupal communities. We'd like to especially acknowledge Jeff Porter of The Foundation for Prader-Willi Research, and Dan Robinson of CivicActions for their extensive contributions.

Phase 1 Scope / Assumptions

CiviEvent Phase 1 will support the following functionality:

• Implement core Event and Participant classes (see schema below).
• Event "wizard" to create events and online event information and registration pages.
• Events can be "public" or "private".
• Upcoming "public" events can be published as an iCal formatted feed.
• Online event registration forms for both free and paid events.
• Events can be copied (however, automatically recurring events will not be supported in phase 1).
• Define one or multiple fee levels with "labels" for paid events (e.g. "Student Admission", "Tier One Seating", etc.).
• Event location mapping.
• Define and track participant statuses (e.g. Registered, Attended, No-show, Cancelled).
• Define and assign participant roles (e.g. Attendee, Volunteer, Host, Speaker, etc.).
• Define custom fields to extend the core Event and Participant classes. Custom fields are available for import, export, online and offline Event Registration.
• Event registration pages can be extended with "Profiles" to collect participant roles, custom event and participant info or other contact info.
• Customizable email confirmation for online registrations (with optional cc: or bcc: to host).
• Option to enforce maximum number of participants - with a customized message to be presented when event is full.
• Dashboard to display current event registration status to end-users.
• Basic Event participant Search/Listings (search and list contacts by event, registration status, participation status and role).
• Batch update grid to update participant statuses (e.g. record attendance or no-show, add notes, etc.).
• Import and Export Participant records.
• Record an Activity History record for event registration, cancellation (and participation, if tracked). This data is then available in the consolidated contact "view". (Activity History display includes drill-down to Event details.)
• APIs to create, update or delete Events and Participants.
• Event creation and modification is limited to users with "administer CiviCRM" and "access CiviEvent" permissions.
• Access control for private event registration pages. (tentatively included)

The following features are NOT part of phase 1:

• Event creation moderation/approval and delegation of event management for specific event(s) to specific individuals.
• Moderation/approval of public event participants.
• Multi-session / nested events (e.g. conferences where user signs up for specific sessions).
• Built-in bulk communications, including broadcast emails to invitee lists, invite to response tracking, sending event updates to participants, etc. However, sites that have CiviMail installed and running will be able to use CiviMail broadcast email, open-tracking and forwarding tools to send invites and communicate with registered participants.
• Automatically recurring events. However a "Copy Event" action will be provided.
• Public Event Finder (search) form. However, APIs will be available to construct search forms and event locations can inlcude postal codes and geocode data (lat and long).
• Specific screens for Volunteer Management. However, a "Volunteer" role will be defined and custom fields can be defined to collect / store additional volunteer-related info.
• Event revenue / expense tracking or reporting. We are thinking this functionality belongs at a "Campaign" or "Project" level - implementation TBD.

You can post your organizations Phase 2 requirements here.

Menu / User Interface Elements

Phase 1 UI will include an Event Information page, Online Event Registration form and processing sequence, a CiviEvent Menu with component dashboard, participant Search, and wizard to Import event participants, and administration interfaces to create events and configure online event information and registration pages.

Event Administration

These functions are accessed via a new set of icons in a CiviEvent section of the CiviCRM Admin control panel.

Manage Events

This page lists all current and upcoming events (where End Date is greater than or equal to current date + 1 month) sorted by Start Date DESCENDING. Page includes a link to ">> Show Past Events" - which requeries and displays all Events. (Selector-style paging is provided when number of events exceeds "rows per page").

• Place link to create new events above the listings table: >> New Event
• Listing columns:
  • Event (title), Location (city, state), Public?, Dates (start/end), Enabled, Actions
• Actions = Edit, View, Copy, Disable, Delete.

New Event Wizard / Edit Event

New events are created using a wizard with the steps (screens) shown below. Existing Events are edited by accessing each of the screens from an "Edit Event" menu (this page is a listing of links to each screen - using the same format as the existing "Configure Contribution Page". The steps / screens for creating and editing an event are listed below.

Event Information and Settings

Contains the following fields (refer to schema below for properties and required vs. optional rules)

• Title
• Event Summary
• Full Description
• Public?
• Start Date / Time (with date-picker)
• End Date / Time (with date-picker)
• Max Number of Participants
  • (if set) Event Full Text
    Enabled?

Event Location

• Location Name
• Address Block
• Contact Email
• Contact Phone # 1
• Contact Phone # 2

Event Fees

Contains the following fields (refer to schema above for properties and required vs. optional rules)

• Paid Event (yes / no)
• If yes, select Contribution Type
• If yes, provide matrix to set fee labels, amounts, and default (same as for Contribution Page >> Amounts)

Online Registration

• Allow Online Registration?
  If enabled:
• Registration Link Text (text for link to Event Registration form / processing sequence - default is "Register Now")

• Registration Screen:
  • Registration Intro
  • Registration Footer
  • Custom Fields (group 1) - select a profile to collect contact and participant info.
  • Custom Fields (group 2) - select a second profile to collect contact and participant info.
    NOTE: If this is a fee-based event AND the configured payment service requires collection of billing information - then the second profile is rendered BELOW the billing information block.
• Confirmation Screen:
  • Title
  • Intro Text (large textarea - 6 rows)
  • Footer Text
• Send Confirmation Email? (radio yes/no). If yes:
  • Text (small textarea - 2 rows)
  • CC Confirmation To
  • BCC Confirmation To

Copy Event Action

If the user selects Copy (row-level action) from Manage Events, they are taken to a "task" screen which prompts for "Title for Copied Event". Default is existing Event Title. If the click "Continue" - insert a complete copy of the civicrm_event record and the following related records: civicrm_event_page (if one exists for source object), civicrm_custom_option records, uf_join records.

Event Type, Participant Status, and Participant Role

CiviEvent will include a set of default event types (Conference, Dinner, Concert, Tournament), participant statuses (Registered, Cancelled, Attended, No-show), as well as a set of default participant roles (Attendee, Host, Volunteer, Speaker). These control panel items will provide listings and add / edit screens to for the status and role values. Note that the 'Registered' and 'Cancelled' values for participant status will be reserved (can not be modified) - as they are used by the online registration processing logic.

Online Event Registration

Registration Screens

Online event registration will follow a similar flow to online contributions. The primary difference is that users can optionally be directed to a "built-in" Event Information screen prior to the Registration form.

1. Event Information

This is a read-only screen which includes the event title, location (with conditional map block), description, start and end dates and any custom fields (label + value) defined for the event. Depending on the event settings (civicrm_event.is_online_register = TRUE) - a prominent link to the actual Event Registration page is included. If maximum number of participants is set and has been met - then the Event Full message will be displayed below the title. NOTE: This page is available to display event information regardless of whether Online Registration is enabled or not for an event.

2. Event Registration (input form)

Includes title, registration intro message, radio button group to select fee level (if applicable), profile 1 (if applicable), billing block (if applicable), profile 2, and footer message.

3. Confirm Registration

User reviews their registration info (and billing information if applicable).

4. Registration Completed / Thank-you

Displays confirmation title and text as well as registration info (and payment info if applicable).

Registration Processing

Execute the following steps for each SUCCESSFULLY completed online registration:

• If we have a contact handle (e.g. registration by logged in user), update contact fields as applicable
• If we don't have a contact handle, check for matching contact record (based on configured duplicate match rules)
  • Insert new contact if no match
  • Else update existing contact
• Insert Participant record. Set role_id = the participant_role option_value where is_default is true. Set status_id = 1 (s/b reserved id for "Registered")
• Insert Contribution record if this is a paid event
• Insert Activity History record
  • entity_table = civicrm_contact
  • entity_id = contact_id
  • activity_type = 'Event Registration'
  • module = CiviEvent
  • callback = (function to display Participant details)
  • activity_id = PK of new Participant record
  • activity_date = current date/time
  • activity_summary = "$event.title - $event.start_date ($participant.role if assigned)"
    EXAMPLES: "Holiday Concert - Dec 12, 2006 (Volunteer)"
• Generate and send confirmation email (if enabled for this Event). For paid events, this email includes contribution receipt data as generated for "regular" contributions (e.g. Amount, Trxn ID, etc.)

CiviEvent Menu Items

• CiviEvent Dashboard (default page for the CiviEvent menu)
• Find Participants
• Import Participants
• CiviEvent Administration (CiviEvent section of CiviCRM Administration control panel)
  • Manage Events
  • Participant Status
  • Participant Roles

Find Participants

The CiviEvent search component is available as a separate search form from this menu AND integrated into Advanced Search. Users can search on the following criteria:

• Contact Name (partial or full)
• Event Name (using inline auto-complete via dojo ComboBox widget)
• Event Date : From / To
• Participant Status: (multi-select checkbox group)

Results (listings) are sortable by each column and include:

• Name (link to Contact Summary)
• Event (link to display of "Event Information" page - see below)
• Fee Level
• Event Date(s) (Start date/time + line break + End date/time)
• Participant Status (Status + line break + (Participant Record Last Modified Date))

The following tasks (bulk operations) are supported for search results:

• Create Smart Group
• Export
• Batch Update via Profile
• Cancel Registration
• Print

Individual row-level actions are: View, Edit, Cancel, Delete (depending on permissions)

Export Participants

For phase 1 we will have a 'standard' export which will output the following data:

• Event data: Event ID, Event Name, Event Start, Event End
• Contact data: Contact ID, Contact name fields (first, middle, last), Primary Location fields (address, email phone)
• Participant data: all core and custom Participant fields

Batch Update via Profile

Profiles which contain only Participant fields (core and custom) will be available for batch update via a grid form. The functionality is analogous to the Batch Update for Contributions implemented in v1.6 - with the following modifications:

• Contact Name AND Event Name are presented as read-only data in columns 1 and 2 of the grid.

Import Participants

• Phase 1 import supports import of Participant data for existing contact records only. Core and custom participant fields are mapped (same flow as current Contact Import Wizard).
• Import REQUIRES that incoming rows include either the CiviCRM contact_id (primary key) of the participant or email address / name values to match on.

Add / Edit / View Event Registration

New event registrations (civicrm_participant records) can be created manually (offline) for a selected contact from a Contact Summary >> Events tab. Existing event registrations can also be viewed and/or edited (cancelled or modified) depending on permissions.

• The add/edit screen presents a form for each core Participant field plus any defined custom fields for Participants. Event selection drop-down should display Event Title and Start Date as recurring events may have the same title. By default, only current/future active events are displayed - but there should be a link to "Select Past Events". Since custom fields are linked dynamically by participant role, the Participant Role field should be placed second in the form (immediately after selecting the "Event") with an onchange event to load the applicable custom fields.
• When an event registration is added or a participant status is modified (e.g. Cancelled, Attended, etc.), a corresponding Activity History record should be inserted (see online registration example below).

CiviEvent Access Control

For Phase 1, we will add the following access control permissions which can be assigned to Roles as needed:

• access CiviEvent (global access to CiviEvent menus)
• edit event participants (CRUD access to Participant records)
• view event participants (read-only access to participant records, includes search and export)

Contact access permissions will intersect with these permissions. So, if user A only has permission to'view contacts in New York Members' group - and they are granted 'view event participants' - they would only see event registrations for contacts in the NY Members group.

Users with access CiviEvent AND administer CiviCRM permissions will be able to Manage Events (CRUD access to Event and related records)

Classes and Schema

Event (civicrm_event)

We will store the following properties for each Event. Note that Location info for an Event is stored in a joined civicrm_location record (and associated address, phone, email records).

• id : int(10) unsigned NOT NULL auto_increment COMMENT 'Event ID',
• domain_id : int(10) unsigned NOT NULL default '0' COMMENT 'Event belongs to which Domain?',
• title : varchar(255) default NULL COMMENT 'Event Title (e.g. Fall Fundraiser Dinner)',
• summary : text COMMENT 'Brief summary of event. Text and html allowed. Displayed on Event Registration form and can be used on other CMS pages which need an event summary.',
• description : text COMMENT 'Full description of event. Text and html allowed. Displayed on built-in Event Information screens.',
• event_type_id : int(10) unsigned NOT NULL default 0 COMMENT 'Event Type ID. Implicit FK to civicrm_option_value where option_group = event_type.',
• is_public : tinyint(4) NOT NULL default '1' COMMENT 'Public events will be included in the iCal feeds. Access to private event information may be limited using ACLs.',
• start_date : datetime NOT NULL COMMENT 'Date and time that event starts.',
• end_date : datetime COMMENT 'Date and time that event ends. May be NULL if no defined end date/time',
• is_online_registration : tinyint(4) default '1' COMMENT 'If true, include registration link on Event Info page.',
• registration_link_text : varchar(255) default 'Register Now' COMMENT 'Text for link to Event Registration form whiich is displayed on Event Information screen when is_online_registration is true.',
• max_participants : int(10) unsigned default NULL COMMENT 'Maximum number of registered participants to allow. After max is reached, a custom Event Full message is displayed. If NULL, allow unlimited number of participants.',
• event_full_text : text COMMENT 'Message to display on Event Information page and INSTEAD OF Event Registration form if maximum participants are signed up. Can include email address / info about getting on a waiting list, etc. Text and html allowed.',
• is_monetary : tinyint(4) default '0' COMMENT 'Is this a PAID event? If true, one or more fee amounts must be set and a Payment Processor must be configured for Online Event Registration.',
• contribution_type_id : int(10) unsigned NOT NULL default '0' COMMENT 'Contribution type assigned to paid event registrations for this event. Required if is_monetary is true.',
• is_map : tinyint(4) default '0' COMMENT 'Include a map block on the Event Information page when geocode info is available and a mapping provider has been specified?',
• is_active : tinyint(4) default '0' COMMENT 'Is this Event enabled or disabled / cancelled?',

Online Event Registration (civicrm_event_page)

This class stores properties related to the Online Registration process. For now, there will be a 1 : 1 relationship between Event and Event Page. The Event Page record is only created if online registration is enabled for an event. NOTE: During implementation we may determine that the existing ContributionPage object should be used to store this data as much of it is analogous.

• id : int(10) unsigned NOT NULL auto_increment COMMENT 'Event Page ID',
• event_id : int(10) unsigned NOT NULL COMMENT 'Event which this page belongs to.',
• intro_text : text COMMENT 'Introductory message for Event Registration page. Text and html allowed. Displayed at the top of Event Registration form.',
• footer_text : text COMMENT 'Footer message for Event Registration page. Text and html allowed. Displayed at the bottom of Event Registration form.',
• confirm_title varchar(255) default NULL COMMENT 'Title for Confirmation page.',
• confirm_text : text COMMENT 'Introductory message for Event Registration page. Text and html allowed. Displayed at the top of Event Registration form.',
• confirm_footer_text : text COMMENT 'Footer message for Event Registration page. Text and html allowed. Displayed at the bottom of Event Registration form.',
• is_email_confirm : tinyint(4) default '1' COMMENT 'If true, confirmation is automatically emailed to contact on successful registration.',
• confirm_email_text : text COMMENT 'text to include above standard event info on confirmation email. emails are text-only, so do not allow html for now',
• confirm_from_name : varchar(255) COMMENT 'FROM email name used for confirmation emails.',
• confirm_from_email : varchar(255) COMMENT 'FROM email address used for confirmation emails.',
• cc_confirm : varchar(255) COMMENT 'comma-separated list of email addresses to cc each time a confirmation is sent',
• bcc_confirm : varchar(255) COMMENT 'comma-separated list of email addresses to bcc each time a confirmation is sent',

Event Locations (civicrm_location...)

Location info for an Event is stored in a joined civicrm_location record (and associated address, phone, email records). Constraints and usage:

• The UI will support ONE location per event (is_primary is TRUE)
• The UI will support ONE address, ONE email address and TWO phone numbers for the event location.
• A reserved location_type_id ('Event') will be automatically assigned to Event locations.
• Users may optionally populate a Location Name (location_name) while entering the Event location info (e.g. 'Civic Auditorium', 'Grouse Hall', etc.).

Participants (civicrm_participant)

Each contact registered for an event is represented by a Participant record.

• id : int(10) unsigned NOT NULL auto_increment COMMENT 'Participant Id',
• contact_id : int(10) unsigned NOT NULL default '0' COMMENT 'FK to Contact ID',
• event_id : int(10) unsigned NOT NULL default '0' COMMENT 'FK to Event ID',
• status_id : int(10) unsigned NOT NULL default '1' COMMENT 'Participant status ID. Implicit FK to civicrm_option_value where option_group = participant_status. Default of 1 should map to status = Registered.',
• role_id : int(10) unsigned NULL default NULL COMMENT 'Participant role ID. Implicit FK to civicrm_option_value where option_group = participant_role.',
• register_date : datetime default NULL COMMENT 'When did contact register for event?',
• source : varchar(128) default NULL COMMENT 'Source of this event registration.',
• event_level : varchar(255) default NULL COMMENT 'Populate with the label (text) associated with a fee level for paid events with multiple levels. Note that we store the label value rather than an FK as the label stored in custom_option may change, but we don't want that to change the label in place at time of this registration.',

Fee Levels (civicrm_custom_option)

Fee levels for paid events are stored as civicrm_custom_option records with entity_table = civicrm_event_page (this is the same storage mechanism as we use for contribution pages).

Participant Statuses (civicrm_option_group / civicrm_option_value)

Statuses will be stored in the existing option_group / option_value tables. Option group = participant_status. Default statuses are loaded by civicrm_data. Registered and Cancelled statuses are "reserved".

Participant Roles (civicrm_option_group / civicrm_option_value)

Roles will be stored in the existing option_group / option_value tables. Option group = participant_role. Default roles are loaded by civicrm_data.

Participant Payments (civicrm_participant_payment)

A participant payment record is generated for each online paid registration. This record links the participant record to a contribution record.

• id : int(10) unsigned NOT NULL auto_increment COMMENT 'Participant Payment Id',
• participant_id : int(10) unsigned NOT NULL COMMENT 'Participant Id (FK)',
• payment_entity_table : varchar(128) NOT NULL COMMENT 'Table being referenced for payment entity (expected usage is civicrm_contribution).',
• payment_entity_id : int(10) unsigned NOT NULL COMMENT 'FK to table with payment record (e.g. civicrm_contribution.id).',

Participant Notes (civicrm_note)

Participant records may be linked to one or more notes - stored in the existing civicrm_note table (entity_table = 'civicrm_participant').

Logging for Event and Participant Creation and Modification (civicrm_log) (tentative)

Extend current logging logic to insert a log entry when an Event is created or modified AND when a Participant is created or modified. This will give us the ability to keep track of who made changes to Event info, and track changes in Participant status (e.g. Jane Doe registered on 12/15 and cancelled on 12/22). NOTE: If this is implemented, AND we use the 'data' column to encode data modification(s), then it might make sense to eliminate the register_date column in civicrm_participant.

Profiles for Event Registration Pages

Profiles are linked to Event Registration pages using the existing civicrm_uf_join table (this is the same mechanism currently used to link profiles to Online Contribution pages).

Custom Data Enhancements

Custom Data Groups will now be able to 'extend' Event or Participant (in addition to existing options to extend Contact, Individual....Location...). For Participant, a custom data group can be linked dynamically based on Participant Role (e.g. you can extend " — Any --" participant role, or user can select a Participant role to extend, e.g. "Volunteer" or "Speaker" role. For Event, a custom data group can be linked dynamically based on Event Type (e.g. you can extend "- Any --" event, or you can extend a specific type of event, e.g. "Concert").

Issues

• Online events are "attended" by people in different time-zones. What additional support is needed for time-zones?