Aller directement à la fin des métadonnées
Aller au début des métadonnées


For the first release, CiviVolunteer will live under CiviEvents. A new tab will appear under "Configure Event," serving as a landing page for other volunteer management interfaces. Users whose volunteer needs are not centered around Events will be encouraged to create dummy events to hold their Volunteer Needs.

Volunteers Tab

When the extension is enabled a new tab is inserted in the manage event tab container - "Volunteers." Tab is displayed after the Online Registration tab. A direct link to this configuration tab is also included in the sub-menu presented when "Configure" action link is clicked in the event listing under Manage Events.

The Volunteers tab will present a simple page with explanatory text ("working with event volunteers ...") and a checkbox for toggling volunteer management.

When the form is submitted:

  • If the checkbox is checked, try CRM_Volunteer_BAO_Project::get(array('entity_id' => $foo, 'entity_table' => $bar))
    • on failure (because the Project doesn't exist):
      • Create new Project (setting is_enabled)
      • Create generic/flexible Need for the Project
    • on success:
      • Do $project->enable();
  • If the checkbox is unchecked, try CRM_Volunteer_BAO_Project::get(array('entity_id' => $foo, 'entity_table' => $bar))
    • on failure (because the Project doesn't exist):
      • Do nothing
    • on success:
      • Do $project->disable();
  • The user should be returned to this tab post-submit.

When volunteering is enabled for the event, the Volunteers Tab display three links:

  • Define Volunteer Needs
  • Assign (Schedule?) Volunteers
  • Log Volunteer Hours

Each link opens one of the admin workflows described below as a separate page (not inside of the event tab container). The page URL's will include vid parameters (id from civicrm_volunteer_project). This approach should make it easy to use the same page and form classes to link volunteer to other types of projects beyond events in future phases.

Each of these three task links should also be injected the "Event Links" button menu.

The admin workflows below should redirect back to the Volunteers tab for the selected event when the user is "Done".

Specify Volunteer Needs

Provide an interface for project administrators to specify their volunteer needs.


  • A 'flexible public need' will be automatically generated when volunteering is enabled for an event. This need has no start/end times, is_flexible = TRUE, 'Public' visibility, and a generic role (default label = "Any Role, Any Time").
  • Xavier suggests any entity with an API can leverage inline editing, and that the framework supports field widgets other than text fields. See Core and Extended Reports for examples.

Manage Assignments (Assignment Widget)

Here's the original mockup:

The pool of potential assignees (left side table) is populated by Contacts who have registered availability in the volunteer opportunity. This is represented in the data as contacts with volunteer activity records linked to a 'flexible' need AND with status = Available.

Right side table is a list of Needs grouped by Role (need.role_id) and listing Start Date / Time within each role.

Differences from the mockup:

  • Left side table header should be changed to 'Available Volunteers'.
  • The number of volunteers required for each Need (need.quantity) should be included in the Need sub-headers, e.g. 'October 14, 2012 2:00pm to 4:00pm (2 needed)'.
  • Most Need time slots will not cross multiple dates, so we should condense the slot label for those cases (e.g. do not repeat full date in the end-date-time display).

For phase 2, it will be helpful to allow administrators to add volunteer candidates to "the pool" using the results of some other search. This could be achieved by adding an item to the actions dropdown on search results pages.

Volunteer Sign-Up

This should be relatively easy to implement:

  • For Events which are associated with Needs, add a "Volunteer Now" button alongside the "Register Now" button.
  • The Volunteer signup page is a reserved profile (and hence extensible) with the following fields:
    • First Name
    • Last Name
    • Email Address
    • Volunteer Need ID - This will be presented to the user as a dropdown containing the Needs for this Event (e.g., Lifeguard - 8am to 11am | Ticket Taker - time flexible | Role 3 - time flexible). User-facing label for this field might be "Time Slot" -- open to suggestions here. Only needs with 'Public' visibility will be included in the dropdown.

Additional Notes/Questions:

  • On form submission it would be nice if, in addition to having the Volunteer Activity created, the Contact's participant record was saved with a participant role of "Volunteer" (rather than "Attendee"). As of 4.3, Participant fields cannot be combined with Activity fields in a Profile. Is there another way to approach this?

Log Volunteer Hours

This UI is modeled off of the Batch Entry UI that currently supports membership and contribution entities.

Additionally, it must support:

  • "Add Another" functionality to record hours of volunteers who showed up without registering. This will create a new Need record AND a volunteer activity record.

Log Own Hours

End-users will have an interface to log their own hours. A section will be added to civicrm/user listing Volunteer Projects with public Needs that are current or not more than two months old. Each Project will offer a "Log Hours" link. The link will lead to a form (either in a pop-up or on a separate page) with the following fields:

  • Duration in minutes (custom time_completed_in_minutes field)
  • Start Time (core civicrm_activities.activity_date_time field)
  • Description (core civicrm_activities.details field)
  • "Save" button
  • "Save and New" button (as in adding custom fields to a UFGroup)


For v1 it should be sufficient to provide a report modeled off of the existing activity report. The following changes would have to be made:

Users will be able to report on volunteers hours:

  • by Contact by filtering for a particular contact
  • by Project by filtering for that particular contact
  • organization-wide (across events, etc.)


Volunteer Project

New table for Project entity (civicrm_volunteer_project). Fields:

  • id - autoincrementing
  • entity_id - FK to entity in entity_table
  • entity_table - the table for the entity_id (initially civicrm_event)
  • is_active - indicates that the Event in question has volunteering turned on, and allows user to disable volunteering without destroying data

Volunteer Needs

New table for Need entity (civicrm_volunteer_need). The Need entity is used to generate a scheduling activity. Fields:

  • id - autoincrementing
  • project_id - FK to civicrm_volunteer_project table which contains entity_table + entity_id for each volunteer project (initially civicrm_event + eventID)
  • start time
  • duration (in minutes) - if times are flexible then duration is probably more appropriate than an end_time field
  • is_flexible - boolean indicating whether or not the time and role are flexible, linking activity to flexible need indicates volunteer is generally available
  • quantity - the number of volunteers needed for this need
  • role_id - Role associated with this Need. Initially, this will be just a label (e.g., Lifeguard), but in future releases roles will have additional properties, such as qualifications.
  • visibility_id - indicates whether this Need is offered on public volunteer signup forms. Implicit FK to option_value table for visibility option_group.
  • is_active - indicates whether this Need is displayed on private forms (e.g., manage assignments)

Volunteer Activities

Modeled as a core Activity with Custom Fieldset containing the following fields

  • volunteer_need_id - Links to Need (and everything else linked to the Need, e.g., Role, Entity)
  • time scheduled - In minutes
  • time completed - In minutes

Additional Notes/Questions:

  • Core activities don't allow us to track scheduled hours vs. performed hours, and using the core duration field results in some ambiguity when it comes to reporting. For these reasons, both scheduled and completed time will be stored in custom fields, altogether ignoring the core field, which should be removed from the UI for CiviVolunteer Activities.
  • After some discussion, we decided it makes sense to use the core activity_status property and inject two more status options - Available, No-show. Both of these statuses could potentially apply to other types of activities so it seems like a reasonable approach which will allow volunteer activities to integrate nicely with core activity interfaces.

Volunteer Roles

We will use the option group / value table for the first phase which can hold all the information we need

BAO/API Functions

Need Entity

Basic CRUD functions for Need Entity. The naming convention for these appears to be:

  • get
    • Use case: Given an Entity Type and ID (e.g. Event #143), return all associated Need IDs. This function will be needed to populate the Specify Volunteer Needs display table as well as the Volunteer Assignment Widget. Might have applications in reporting as well.
  • create
  • delete 
    • FJG: I think we need some logic in CRM_Volunteer_BAO_Need::delete which makes the following checks:
      • for the Need being deleted, does is_flexible=TRUE?
      • if so, is this the only is_flexible=TRUE need for the project?

        If both checks are true, we should block deletion and issue a message explaining that at least one is_flexible=TRUE Need is required per Project. The primary reason for this constraint is that the Manage Assignments screen populates the left column with Contacts assigned to is_flexible=TRUE Needs. The second check can be accomplished with something like count(CRM_Volunteer_BAO_Need::get(array('project_id' => $foo, 'is_enabled' => TRUE, 'is_flexible' => TRUE)));
    • Deleting a Need will delete related volunteer activity records. Is a MySQL trigger the best way to do this?
  • getAssignees - needed for Assignment UI

Volunteer Project Entity

A Volunteer Project is an entity that has Volunteer Needs associated with it. In the initial release, all Volunteer Projects will be Events, but this may not be the case for long.

  • get
    • When called with no params, the function returns a list of all Volunteer Projects. The results will be useful for populating a "Volunteer Project" select/check list in reports, to allow users to show results for a limited set of Projects.
  • getNeeds - gets all Needs associated with a Project (required by Needs UI and Assignment UI)
  • getAssignments - get all Assignments (and basic contact info of assignees) associated with a Project (Log hours screen depends on this for displaying default values - fetch contact name from civicrm_activity_contact table, role and start_time from civicrm_volunteer_need table, scheduled and completed times from custom value table, and status from civicrm_activity table.
  • create

Additional Features

This will be specified if time permits

Specifying Recurring Needs

Recurring Needs are not essential to a first release. It's a good candidate for functionality to slip to v2 if need be. Should the "recurring" meta data really be stored in the database? We could just capture it at form submission and then use it to generate multiple Needs records with different dates. The major drawback to this approach is that if a user changes her mind (e.g., "I meant every Tuesday until 2031, not every Thursday") or wants to extend/shorten the recurrence period, she can't.

The UI could look something like Google Calendar's UI for recurring events or something like dhtmlxScheduler's UI. The logic of generating dates from the provided input might be handled by Thomas Planer's When PHP library.

Other Ideas and/or Client-Specific Implementations

See CiviVolunteer - Other Ideas and Client-Specific Implementations.

  • Aucun

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.