The CiviCase component is available starting with the 2.2 release of CiviCRM and is included in the general release download files. If you are using Cases in a prior version, refer to Upgrading to CiviCase after reviewing this document.


The CiviCase component provides a high degree of customization to meet the needs of a wide variety of case management settings and workflows. It is important to understand CiviCase's underlying principles and assumptions, as well as the elements which can be customized. Then you can plan and configure the component based on how your organization manages cases.


Case Types, Activity Types and Timelines

The first step in planning your CiviCase configuration is creating a list of the types of cases you handle.

Examples of case types from the Physician Health Program are:

For a community services organization, examples might include:

For each case type, list the types of activities (interactions or other events) you typically record for a case.

Then create a timeline for each case type, listing any of these activities which generally occur in a predictable order and should be accomplished within a certain timeframe (e.g. you might think of this as a case plan). Define the expected number of days between the beginning of the case and each of the subsequent activities in the timeline (reference offset). If needed, you can also define an offset from another activity. EXAMPLE: For a "Referral to Specialist" case, the "facilitate first appointment" activity might be expected to occur within 2 days after the case is opened. "Survey client satisfaction" might be scheduled for 30 days after "facilitate first appointment".

You can also define a set of activities to be included in audit reports that CiviCase can generate. These reports consolidate activity data for the defined activities. EXAMPLE: For a given type of case, what set of activities should be reviewed by a case supervisor periodically? These set could be defined as your "Monthly Review" report.

Activity Data

There is a standard set of data collected whenever a case activity is recorded in CiviCase:

This is sufficient for some types of activities. However it is often useful to collect additional structured data for some types of activities. The "Open Case" (intake) activity is a common example - where you may want to include a set of specific questions about the client and their situation.

Create a list of additional (custom data) requirements for each activity type. The list should include the type of data being recorded (free text, multiple choice, date, etc.).

Case Roles and Relationships

CiviCase provides three mechanisms for relating people to cases and clients:

If no case roles, client relationships, or case resources are defined, then the only person related to the case is the Client.

CiviCRM provides relationship type definitions for most of the standard relationships you might track (e.g. Spouse, Child ...). However you will probably need to define additional relationship types for your case roles. Examples include:

Make a list of the expected case roles for each type of case listed above. Then determine which role is generally considered to be the "case manager" for that case type.

Configuring CiviCase


For the current version (3.2) - most of the configuration steps require that you create and edit files outside of the CiviCRM user interface. You will need:

Configuration tasks are:

  1. Create a custom templates directory to hold your case configuration files.
  2. Create an XML-formatted configuration file for each case type.
  3. Configure Case Resources.
  4. Enable the CiviCase component.
  5. Enter your Case Types, Activity Types, and Case Roles (relationship types).
  6. Create the custom fields you need to collect extra data for your activity types.
  7. Add staff members.


1.  Configuration Files Directory

If you haven't already created a custom template directory for your Civi install, please create a directory outside of the CiviCRM module directory (placing it in the same path as your "Custom Files" directory would be a good choice). Then visit and register the path you have just created. (learn more...)

Inside your custom templates directory, create the path /CRM/Case/xml/configuration

Copy the contents of /civicrm/CRM/Case/xml/configuration.sample into your newly created folder to provide a good starting point.

Note that if you choose to forgo the sample files, a file named Settings.xml and one file per case type are necessary for CiviCase to run.

2. Case Configuration Files

Create an XML-formatted text file for each case type you plan on using.

The file names should match the case type name with spaces removed and the first letter of each word upper-cased.
EXAMPLE: Case type = "Housing Support" Filename = "HousingSupport.xml"
Use a copy of one of the sample configuration files that are included in the distribution as a starting point.


Copy this file to the /CRM/Case/xml/configuration directory below your custom template path, and then edit it to meet your requirements.

These files contain the following sections:

<CaseType> - Top level element

<name> - Name of this case type. Must match a value stored in the CiviCRM database ( The name cannot contain hyphens - or parentheses ().

<ActivityTypes> - Listing of all the activity types which might be used in this type of case

<ActivityType> - A specific activity type

<name> - Name of this activity type. Must match a value stored in the CiviCRM database (

<max_instances> - Optional limit on how many instances of this activity type are allowed in a single case

<ActivitySets> - Groups of activity types which define either the standard timeline (plan) for this case type, OR an audit report definition for this case type.

Note: At least one Activity Set must exist, and each Activity Set must contain the Open Case activity type.

<timeline> - Set this element to 'true' to define a group of activities which will be automatically scheduled whenever a new case of this type is opened.

<status> - Status that this activity should be set to when it is created (default is "Scheduled"). ( where type is "activity_status").

<reference_activity> and <reference_offset> - Used in the timeline activity set. <reference_activity> is most often 'Open Case' - but can be any activity which occurs earlier in the timeline. <reference_offset> is the number of days after the reference activity to schedule this activity.

<reference_select> - Valid values are newest or oldest. Used in the timeline to specify which instance of the reference activity should be used for scheduling this activity (either the oldest or the newest one).

<order> - (v4.1+) Optionally order how activities in your timeline are referenced. The sort order will first use the optional date-based settings (reference_activity, reference_offset, reference_select) and then the order elements. 

When using the timeline feature, Activities should be entered in chronological order based on the <reference_offset>. For example, an Activity that will be scheduled 2 days in the future should be listed prior to one scheduled 10 days in the future. Otherwise, you will get an error when trying to open a case.

<Case Roles> - The set of service provider relationships generally needed for this case type

<RelationshipType> - The name of the relationship type. Must match a value stored in the CiviCRM database (civicrm_relationship_type.name_b_a).

<creator> - If true, assign this case role to the person who opens the case. EXAMPLE: This might be the 'Case Coordinator' or 'Intake Counselor' role.
<manager> - If true, mark the person with this role as the "case manager" for this type of case.

Refer to a local copy of <civicrm_root>/CRM/Case/xml/configuration.sample/HousingSupport.xml - OR browse to this file in our SVN repository - to see how these sections and their elements are entered.

The following activity types will be needed for any type of case. Be sure to include them in each case type configuration file: Open Case, Change Case Status, Change Case Type, Follow up. You will use Change Case Status to close a case. Follow up is a useful "general" activity type for most cases settings.

      <name>Open Case</name>
      <name>Change Case Type</name>
      <name>Change Case Status</name>
      <name>Follow up</name>

3. Global Settings

Global Settings file (Settings.xml)

Case Resources Group

CiviCase allows you to include a listing of people and organization contacts whom your staff might need to communicate with (Case Resources) whenever a case is being viewed. You can do this initially, or add this feature at any time.

Other Global Settings

Several other default behaviors are controlled from Settings.xml.

4. Enable the CiviCase component

The CiviCase component is included in CiviCRM downloads starting with version 2.2 However it is NOT enabled by default. To enable the component:

5. Populate Case Types, Activity Types, and Case Roles

You will need to add database records for each case type, activity_type, and case role that you've included in your case configuration files (in step 1 above). You can use the CiviCRM Admin screens to do this. However... if you have a lot of entries to make and some SQL knowledge you can create and load a SQL script. Sample SQL snippets are included below - and you can also refer to the SQL script provided in the configuration.sample directory (<civicrm_root>/CRM/Case/xml/configuration.sample/SampleConfig.mysql).

Case Types

Using the admin screens:

SELECT @option_group_id_case_type := max(id) from civicrm_option_group where name = 'case_type';
-- Note that the value column MUST be an integer
   `civicrm_option_value` (`option_group_id`, `label`, `value`, `name`, `grouping`, `filter`, `is_default`,
   `weight`, `description`, `is_optgroup`, `is_reserved`, `is_active`)
    (@option_group_id_case_type, 'Inpatient treatment',  1, 'inpatient_treatment', NULL, 0,  0, 4,
    'Inpatient treatment case', 0, 0, 1),
    (@option_group_id_case_type, 'Intervention',  2, 'intervention', NULL, 0,  0, 5, 'Intervention case', 0, 0, 1),
    (@option_group_id_case_type, 'Referral to counselor',  3, 'referral_to_counselor', NULL, 0,  0, 1,
    'Referral to counselor case', 0, 0, 1);

Activity Types

The "general" activity types listed in step 1 above (Open Case, Change Case Status, etc.) are included in all CiviCRM installs. The Meeting and Phone Call "generic activity types are all included "out of the box". However you will need to add any other activity types which you defined in your case configuration files (in step 1 - above).

Using the admin screens:

SELECT @caseCompId := id FROM `civicrm_component` where `name` like 'CiviCase';
SELECT @option_group_id_activity_type        := max(id) from civicrm_option_group where name = 'activity_type';
SELECT @max_val := MAX(ROUND(op.value)) FROM civicrm_option_value op WHERE op.option_group_id  =

   `civicrm_option_value` (`option_group_id`, `label`, `value`, `name`, `grouping`, `filter`, `is_default`,
   `weight`, `description`, `is_optgroup`, `is_reserved`, `is_active`, `component_id` )
    (@option_group_id_activity_type, 'Plan intervention', (SELECT @max_val := @max_val+1), 'Plan intervention',
    NULL, 0,  0, (SELECT @max_val := @max_val+1), 'Include in the details a list of expected attendees and their roles.',
      0, 0, 1, @caseCompId ),
    (@option_group_id_activity_type, 'Rehearse intervention', (SELECT @max_val := @max_val+1), 'Rehearse intervention',
      NULL, 0,  0, (SELECT @max_val := @max_val+1), '', 0, 0, 1, @caseCompId ),
    (@option_group_id_activity_type, 'Conduct intervention', (SELECT @max_val := @max_val+1), 'Conduct intervention',
      NULL, 0,  0, (SELECT @max_val := @max_val+1), 'Did Physician Health representatives attend?', 0, 0, 1, @caseCompId ),
    (@option_group_id_activity_type, 'Debrief intervention', (SELECT @max_val := @max_val+1), 'Debrief intervention',
      NULL, 0,  0, (SELECT @max_val := @max_val+1), 'Record what the result was. Did the problem person obtain help?',
      0, 0, 1, @caseCompId );

Case Roles (relationship types)

You will need to define relationship types for any case roles you've defined in your case configuration files (step 1 - above). If you do not do this, when you try to create a new case, you will receive a fatal error upon trying to save your case. Examples might include Intake Coordinator, Employment Counselor, Housing Advocate, etc.

Using the admin screens:

Relationship Label-A to B : "Case Coordinator is"
Relationship Label-B to A : "Case Coordinator"
Contact Type A: "Individual"
Contact Type B: "Individual"

* Click Save

INSERT INTO `civicrm_relationship_type` (`name_a_b`, `name_b_a`, `description`, `contact_type_a`,
  `contact_type_b`, `is_reserved`, `is_active`)
 VALUES ('Psychiatrist is','Psychiatrist','Psychiatrist','Individual','Individual',0,1),
		('Addiction Specialist is','Addiction Specialist','Addiction Specialist','Individual','Individual',0,1),
		('Other Specialist is','Other Specialist','Other Specialist','Individual','Individual',0,1);

6. Custom fields

It is likely that you will want to collect some structured data for some of the activity types you've defined.

Custom fields are most often connected to a specific activity type. For example, in Employment Counseling cases, you may want to define an activity type used to record client job skills. This activity type will require one or more custom fields - perhaps a set of checkboxes. If you are transitioning from a paper-based system - it is helpful to refer to existing forms and then determine what information from the forms is relevant. CiviCase is designed to store pretty much all case information within activity records - and does not support custom fields at the case level.

Please review the section on configuring custom data fields prior to beginning these steps.

Using the admin screens:

If you need to define a large number of fields for a given activity type, consider breaking them up into a few sets of related fields. You can assign more than one custom data field group to a single activity type - however you can not currently share groups of custom fields between different activity types.

7. Add Staff Members

You will need to create a contact record for each staff member or service provider who will be using CiviCase to enter or view case information. These individuals will also need to have a user account (Drupal and Joomla installs). If you are new to CiviCRM, please review the Access Control section before continuing.

You should also add contact records for service providers who will be assigned case roles but will not be accessing the CiviCase system. CiviCase will allow your staff to easily send emails to these providers with pertinent case and client information, as well as record case-related interactions reported by them. Click New Individual from the CiviCRM Shortcuts block to begin adding contact records.

Optional Enhancements

1. Filing emails under cases

In 3.2 and later, you can file any type of non-case activity on a case by using the action File on Case that appears in activity lists. You may wish to set up the Email Processor as described in Autofiling email activities via EmailProcessor to facilitate filing emails that come into your inbox onto cases.

Note that the File on Case feature is available in earlier versions too, but you will only see it on Inbound Emails and not for other activity types, and it only appears at the bottom of the activity when they are viewed.