Sunday, October 24, 2010 - 21:02
Written by
A few months ago as our organization was just starting to use CiviCRM, Dave Greenberg recommended that we look at CiviCase as a solution for our admissions team to keep track of prospective students. As a collection of activities associated with a client, CiviCase looked like a great way to record our interactions with potential students as we made initial contact, followed up, received communication from them, sent more info, and then accepted their applications. From a DB point of view, yes, it is a nearly perfect way to store that information. But from a UI point of view, we had a long way to go before our admissions team would be able to painlessly get the data in, work with and update it once it was there, and then be able to get it back out in the form of reports. Here's what we did to make that happen (and more!):

Getting the Data In

Creating a case for a new prospective student is simple: just log in to CiviCRM and create a new individual contact record for the person. Then add them to our mailing list group. Then create a record for their school. Then create a “student” relationship between them and their school. Then create a record for their teacher or guidance counselor. Then open a “prospective student” case. Then add the teacher/counselor as a case resource. Then send them an email and record that follow-up activity to the case. Okay, maybe it's not so simple; if an admissions person came back from tabling with a sign-up list of 40 interested students, repeating those 8 steps for every student would mean 320 page-loads/form-submissions just to enter the initial data. As one admissions person said when faced with that idea, “Are you kidding??” Woolman Admissions Assistant ScreenshotIn response to the need for simplified data-entry, I sat down and wrote my first custom module: The Admissions Outreach Assistant, using Drupal's FAPI and jQuery for the interface, then passing the input into CiviCRM APIs. The result was cutting those 320 pages down to a single 3-step form:
  1. Enter the school, teacher/counselor, time & date of your visit
  2. Enter names & addresses of all the students you met
  3. Compose a follow-up email to those students (personalized with name tokens)

An API for CiviCase

The biggest hurdle in writing this module was the little problem that it wouldn't be able to open cases via the case api, because there wasn't one. The friendly advice on the Civi IRC was “contributions welcome,” so with help from our GNU media intern Brylie Oxley, I wrote up an API that could create, read, update, and delete cases, and also create and read case activities. As my “reward” for contributing this code to the community, I got recruited to the Civi API team -- yep, not even a lousy T-shirt :).

Introducing: Case Bulk Operations

Now that they were getting spoiled with such an easy way to add students and create cases, I started to get a lot of questions from our admissions staff about how to manage them all. In CiviCRM, there's only one way to manage cases: one at a time. “But what if I call 15 people's voicemails and want to record all those activities at once?” Or, “I want to schedule a follow-up activity with these 20 students for next week.” Or, “what about when a staff person leaves and we want to reassign all 200 of his cases to someone else?” Or even something as simple as: “what if I want to view details of all my cases at once?” Woolman Prospective Student Manager ScreenshotIt was time to get back to coding. This time I set out to create a single interface that would allow staff to search, sort, filter, manage cases, and work with case activities without having to navigate between pages. Since, from the user's point-of-view, there isn't any difference between cases and case-activities, I wanted to erase that distinction in the interface; so instead of requiring the user to click “manage case” before they could see and work with the activities, this interface would do it all. And the same would be true of the bulk operations: if you can change 20 case statuses in one click, why not be able to add or update 20 case-activities the same way? The result looks a lot like Drupal's bulk operations interface, with some extra jQuery goodness to speed things up. The table presents a lot of information, so I made use of hover-links, popups, and tooltips to keep things out of the way until they are needed. CiviCase's “View Activiy” popup is so great that I shamelessly stole it (with the minor improvement of adding an animated spinner to give people something to look at while it's loading). At the top of the screen are filters, which allow you to display cases by status, case manager, start date, by the time since the last completed activity or time until the next scheduled activity, by the student's state, High School, or the outreach trip we met them on.Woolman Prospective Student Stats Screenshot Below that are bulk operations, which seamlessly allow you to update case data (case status and case manager), contact data (HS graduation date and semester of interest) and case-activities (schedule follow-up, send email, and create or update various activities). The form fields appear as needed (for example, choose “send email” from the bulk actions menu, and the subject and body fields appear for you to type your message, along with a little box of instructions about how to use tokens). And below that, of course, is the table of students, which presents the most important contact, relationship, case, and case-activity information about each student in a click-sortable table, with some links to take you back to civicrm in case you want to do something really complex. As a finishing touch, I made use of a graphing library to construct some colorful charts and graphs to present an overview of it all: how many active cases we have and who they're assigned to, a timeline of incoming and outgoing communication, and how well we're doing at following-up.

Using CiviCase for Online Applications

Woolman Semester Application ScreenshotSince it worked so well for tracking prospective students, we decided to use CiviCase in a similar way as the DB back-end for our new online application system. The application process involves a predictable timeline of activities (application form, short-answer questions, essay question, teacher recommendation, interview, etc.) so once again CiviCase would work perfectly for storing the data, but a lot of custom code would be needed to meet our specific UI needs, and take care of all the miscellaneous CRM tasks of opening cases, updating activities, creating relationships, etc. Enter the “Apply Online” module. On the front-end, the Online Application module presents students with a friendly, step-by-step process that shows their progress, lets them save forms as a draft, and auto-populates forms with any existing data so that, for example, they don't have to fill-in their address if we already know it. When they fill out the names and email addresses of their parents and teachers, the module will email those people a link that takes them directly to a personalized version of the appropriate recommendation forms. And of course, when a recommendation form is submitted, the case activity is updated and the student will see that step as completed in their application summary. Woolman Semester Applications ScreenshotFor staff, I created a simple interface that shows the progress of each applicant and allows staff to view each activity (again in CiviCase's nifty popup activity viewer), or update/schedule things like interviews and financial-aid information. An admin screen allows admissions staff to change things like the questions on each form, form-instructions, and the text of automatic email messages. Behind the scenes, the module takes care of creating contacts, addresses, and relationships for the students' family members, teachers, and schools. It creates and updates cases and activities, and sends email updates to admissions staff when activities are completed.

Great! Can I use it too?

The modules I have written are tailored to The Woolman Semester's needs, and a lot of settings specific to our database are hard-coded into them. If your organization has similar needs for managing outreach efforts, tracking online applications, or just needs an efficient way to work with large numbers of cases, please contact me about it, I'd be happy to discuss creating something similar to meet your specific needs. It's also possible that some of this code could be abstracted and made into stand-alone modules, like a flexible “apply online” system or a generalized “case bulk operations” module that could be made freely available to meet the needs of many organizations. If your organization would like to sponsor such a project, please let me know.


Nice writeup. And thanks for the api.

And +1 for

"...from the user's point-of-view, there isn't any difference between cases and case-activities..."

This is similar to something I've been pushing since day one, just there are implementation trade-offs so I see both sides.


One question: Any particular reason for choosing Drupal FAPI over Civi/Quickform?


"As my “reward” for contributing this code to the community, I got recruited to the Civi API team".


I'm afraid you misunderstood: what happen is that you spontaneously offered to share your valuable expertise and volunteered  to join the API team... didn't you ?



Might be that it happened before Eileen briefed you on the slowest to step backward recruitment policy  ;)



Really nice usage of case. Well done.

Thanks X, and it's great to be on the A Team (although a T-shirt would have been nice too)


The API team is awesome :), so the least we can do is get u'll a t-shirt and a copy of the book. We'll try to get that to you before the end of the year!


Seems like we might want to think about an API sprint and see if we can get funding to do so for later this year. Another thing to add to a growing proposal :)



Hmm can we have the API sprint somewhere really nice & get funding for the A(PI) team to attend?


We could have it in Brisbane after the Drupal meet (with Dries as Keynote) ... if the Maldives is booked out I mean

I think I can come to the sprint in SF next month, so hopefully we can talk APIs there.

I see those tradeoffs too -- I think I was able to get away with it because of how tailored my module is to our use-case (for example, I can be pretty sure that a single case will not have 200 activities in it!). Civi core developers can't make assumptions like that, and need to provide an interface that's bulletproof in all situations. That said, I really think that case bulk operations could be made to work in a generalized context that could serve the needs of everyone. It would be especailly good if it included some admin options that allow different fields and operations to be shown or hidden depending on the needs of the org. For that matter, it would be great if all of CiviCRM would include options like that -- it has so many features that most people never use, and we all know how overwhelmed and confused "non-computer-people" can get when presented with too many options.

As to the question about FAPI vs. Civi's quickform, I have no experience with the latter, so I just went the easy route. I found Drupal's documentation much easier to understand and was able to get up and running with FAPI very quickly. I have also heard some talk of depreciating Civi's framework entirely in favor of Drupal's APIs, so maybe I'm just ahead of the curve :)

I'd rather stab myself in the eye with a fork than use Quickform.  It's an undocumented mess.

This is a really great write up that highlights the usability weaknesses of cases for large volume of cases with very similar tasks. I noticed that bulk operations on cases are not even on the CiviCase roadmap.

We implemented cases for our admissions process but our admins hate them so we may have to stop using them and go to something like activities or custom fields.

I'd love to see your work as a generalised module. Our organisation would be happy to pitch in some money to make this happen (but probably not enough to see through the whole project). Do you have any estimates on how much this would cost?

Hi Dominik, I think I can help your admins to not hate CiviCase so much :). Please contact me and we can discuss your needs and our best approach.