Now that you've gone through the planning process and determined the types of cases, activities and case roles that you need, you're ready to configure your CiviCase installation.

The configuration process requires some technical skills. Review these prerequisites before getting started, and recruit assistance if needed.


As of CiviCRM 4.1, the sample configuration will work immediately after enabling CiviCase. However, to customize the configuration, many of the steps require that you create and edit files outside of the CiviCRM user interface. You will need to:

  • use a text editor
  • edit XML files and upload them to the server directory where CiviCRM is installed
  • (optionally) write or modify a simple program using the API to automate the creation of activity types or relationships.

Configuration Tasks

Follow these steps to set up CiviCase for your organisation:

1. Enable the CiviCase component

Once you have created your configuration files and uploaded them to the configuration directory in your CiviCRM installation, you must enable the CiviCase component. The CiviCase component is included in CiviCRM downloads, but it is NOT enabled by default. To enable the component:

  1. Go to Administer > Configure > Global Settings > Enable Components.
  2. Select CiviCase in the left-hand box and click Enable (this should move it to the right side).
  3. Click Save.

CaseMenuYou will now see an Other option in the navigation menu. Click that option to see the Cases menu. People in your organisation who work with cases will probably want to modify their navigation menu to move Cases to the top-level.

Navigate to Administer > Customise > Navigation Menu to make this change.   

2. Case Type Configuration Files

You will create a separate XML-formatted text file for each of the case types you identified during the planning process. These files specify the characteristics of the case type using XML elements.

Case configuration files should be saved to the following directory in your CiviCRM installation:


You will need to create this directory when you save your first configuration. Ensure that the directory is readable by your web server process.

If you are not familiar with XML markup, refer to the Wikipedia page on XML at:

A set of sample configuration files are included when you download CiviCRM. If you can access the CiviCRM codebase at, load the sample case type configuration file for Housing Support in your text editor before continuing, and refer to it as you review each of the sections below.

  • Activity Types: this is a list of all activity types that are valid for this type of case. Several activity types will be needed for any type of case. Be sure to include them in this listing: 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 case settings.

You can optionally specify the maximum occurrences of this activity type in a case using the max_instances element. Generally you'll want to set max_instances to 1 for the Open Case activity type, but you can also use this to limit recurrence of other types of interactions or processes. 

  • Activity Sets: groups of activity types which define a sequence of interactions. You must include at least one activity set in the configuration file which defines the standard timeline (plan). The activities in the standard timeline set are automatically created when you open a case of this type. You can control the scheduling of each activity relative to the date the case is opened OR relative to another activity using the reference activity and reference offset elements. Offsets are expressed in days.

Here's a simple timeline example for a Housing Support case:

<ActivitySet>       <name>standard_timeline</name>       <label>Standard Timeline</label>       <timeline>true</timeline>       <ActivityTypes>         <ActivityType>           <name>Open Case</name>           <status>Completed</status>         </ActivityType>         <ActivityType>           <name>Medical evaluation</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>1</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>         <ActivityType>           <name>Mental health evaluation</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>1</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>         <ActivityType>           <name>Secure temporary housing</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>2</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>         <ActivityType>           <name>Follow up</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>3</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>         <ActivityType>           <name>Income and benefits stabilization</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>7</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>         <ActivityType>           <name>Long-term housing plan</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>14</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>         <ActivityType>           <name>Follow up</name>           <reference_activity>Open Case</reference_activity>           <reference_offset>21</reference_offset>           <reference_select>newest</reference_select>         </ActivityType>       </ActivityTypes> 

In this example, the Open Case activity is marked as Completed when the case is opened. Three additional activities are automatically scheduled when the case is opened. A medical evaluation is scheduled for the following day (reference offset is 1); then secure temporary housing (reference offset 2); and finally a follow-up three days later.

  • Case Roles: this section lists the types of people who are involved in the case in some way. Roles listed here will be automatically created when the case is opened. One role is marked as creator. This role is automatically assigned to the person who created the case. After the case is opened, users with access to the case can assign the remaining roles to contacts as appropriate. You may also mark one of the roles as the case manager. The case manager's name will be displayed prominently in case listings and reports.

Here's a simple example of case roles for a Housing Support case: 

<CaseRoles>     <RelationshipType>         <name>Homeless Services Coordinator</name>         <creator>1</creator>         <manager>1</manager>     </RelationshipType>     <RelationshipType>         <name>Health Services Coordinator</name>     </RelationshipType>     <RelationshipType>         <name>Benefits Specialist</name>     </RelationshipType>    </CaseRoles>

In this example there are three case roles. The Homeless Service Coordinator is both the creator and manager of these cases. In addition, a Health Services Coordinator and a Benefits Specialist role are created when the case is opened.

Refer to the detailed configuration documentation on the wiki for more detailed explanations of each element in the XML file:

Create a separate XML file for each of your case types. Your file names should match the case type name with spaces removed and the first letter of each word in upper case.

For example, if the case type is Housing Support, the filename would be "HousingSupport.xml". A good approach is to use a copy of one of the sample configuration files that are included in the distribution as a starting point, and edit it to meet your requirements. 

3. CiviCase Drupal permissions

This section applies to Drupal installations only.

In order for users to add and manage cases, you will need to configure CiviCase-related permissions in Drupal (Administer > Users > Permissions). You may want to create case management-specific Drupal user roles for staff, based on their responsibilities within your organisation. You can assign permissions to users in order to control whether or not they have access to the CiviCase component, as well as what case data they can see (Administer > Users > Permissions).

The following is a list of the CiviCase-related permissions:

  • Access my cases and activities: allows a user to create new cases, add activities to the cases they've created and edit those activities. Users with this permission can NOT see cases or activities created by others.

If you need to restrict certain users to ONLY seeing case data (i.e. hide all other contact information from them), assign "access my cases and activities" permission WITHOUT "edit and view contacts" permission. This permissioning model is useful for users who are external to your organisation and who should not be allowed to see contact details.  

  • FindDeletedCasesAccess all cases and activities: allows a user to create new cases, as well as view and add activities to any case (regardless of who initially created the case). 
  • Delete in CiviCase: allows a user to mark cases or case activities as deleted. Cases and activities are never physically deleted from your database, but only hidden when you mark them as deleted.

Users with this permission can also find and undelete these cases and activities by checking the Deleted Cases option in Find Cases and the Deleted Activities option in the Case Activities Search Filter.

  • Administer CiviCase: gives access to Administer > CiviCase options including:
  • create and edit case types and case statuses
  • set rules for redacting case data. These rules are used to disguise data which could be used to identify the case client in case reports which are shared with external reviewers.   

4. 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 type configuration files. You can use the CiviCRM Administrative screens to do this.

To add case types:
  1. Go to Administer CiviCRM > CiviCase > Case Types.
  2. Click New Case Type.
  3. Complete the form using the exact same text for the Label as you entered for the CaseType <name> element in your case configuration files.
  4. Click Save.
Activity types

Generic activity types (Open Case, Change Case Status, etc.) are included in all CiviCRM installations. Meeting, Phone Call, Email (inbound and sent) activity types are also included by default. However you will need to manually add any other activity types that you've defined in your case configuration files.

  1. Administer CiviCRM > Option Lists > Activity Types.
  2. Click New Activity Type.
  3. Complete the form using the exact same text for the Label as you entered for the ActivityType <name> element in your case configuration files.
  4. Select CiviCase in the Component drop-down.
  5. Click Save.
  6. Repeat for each unique activity type defined in your case configuration files.

Alternatively, if you have a lot of entries, you may prefer to use the API to write a simple programme to automatically create all the activity types:

 <?php require_once 'civicrm.config.php'; require_once 'CRM/Core/Config.php'; require_once('api/api.php');  //read the API chapter to get more explanation $componentCase = 7; $types = array ("Medical evaluation","Secure temporary housing"); foreach ($types as $type) {   $param = array("label"=>$type,"description"=> "Example of Type","component_id" =>      $componentCase, "is_reserved"=>false,"is_active"=>1,"weight"=>1,      "version"=>3);   $result = civicrm_api('activity_type', 'create', $param);   if (civicrm_error( $result )) {     echo "\n ERROR creating $type: ". $result['error_message'];   } else {     echo "\n Type $type created";   } } ?> 
Case roles

You will need to define relationship types for any case roles you've defined in your case configuration files. Examples might include Intake Coordinator, Employment Counsellor, Housing Advocate, etc.

  1. Go to Administer CiviCRM > Option Lists > Relationship Types.
  2. Click New Relationship Type.
  3. When completing the form fields, define the relationship using the "client as Contact A" and the service provider as "Contact B". The Relationship Name-B to A value should match the text entered for the RelationshipType <name> element in your case configuration files.
  4. Click Save.
  5. Repeat for each unique case role.

For example, to define a Case Coordinator relationship type:

Relationship Name-A to B : "Case Coordinator is"

Relationship Name-B to A : "Case Coordinator"

Contact Type A: "Individual"

Contact Type B: "Individual"

Again, if you have a lot of entries, the process of defining relationship types can be automated using the API:

<?php require_once 'civicrm.config.php'; require_once 'CRM/Core/Config.php'; require_once('api/api.php');  //read the API chapter to get more explanation // if you are getting errors, make sure there are no line breaks in the middle of a field below $types = json_decode ('[ {"name_a_b": "Case Coordinator is","name_b_a":"Case Coordinator","contact_type_a":"Individual","contact_type_b":"Individual"},{"name_a_b": "Benefit Specialist of","name_b_a":"Benefits Specialist","contact_type_a":"Individual","contact_type_b":"Individual"} ]');  foreach ($types as $type) {   $params = get_object_vars($type);   $params['version'] = 3;   $result = civicrm_api('relationship_type', 'create', $params);   if (civicrm_error( $result )) {     echo "\n ERROR creating {$type->name_a_b}: ". $result['error_message'];   } else {     echo "\n Type {$type->name_a_b} created";   } } ?> 

Custom fields

It is likely that you will want to collect structured data for some of the activity types you've defined. You can collect data in custom fields connected to a specific activity type. For example, in Employment Counselling cases, you may want an activity type Skills Assessment, in which an employment counsellor records 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 to include. Remember that CiviCase is designed to store 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.

  1. Go to Administer > Customize > Custom Data.
  2. Click New Group of Custom Fields.
  3. Under Used For, select Activities.
  4. Select one or more specific activity type(s) for which this set of fields will be used.
  5. Enter any help information you want to be displayed to your users.
  6. Click Save.
  7. Enter one or more custom fields for this set.
  8. Repeat these steps for each activity type which requires custom data to be recorded. 

If you need to define a large number of fields for a given activity type, consider breaking them up into sets of related fields. Group the fields into logically related sets that will make sense to the users, and avoid the form looking like an endless tunnel of fields.

You can assign more than one custom data field group to a single activity type. For example, if you are collecting a lot of data during client intake, you may want to create several sets of custom fields for the Open Case activity type.

If you have sets that are only relevant to some contacts, for example a different set of fields for male or female contacts, you can modify the form's template and add client-side logic using jQuery to hide/show the relevant sets based on the values selected on previous fields.

Filing Emails on Cases

Some organizations find it useful to record case-related emails in CiviCase. For example, the case coordinator for a work disability case might send an inquiry to a state agency representative and would like both the sent email and the reply to become part of the case story.

You can choose to send outbound emails directly from the Manage Case screen, but you can also set up CiviCRM to integrate with your usual email client so you can send and receive emails as usual and also have them filed in CiviCRM.

In the CiviMail chapter the Email Processor was described as a way to get inbound and outbound emails into CiviCRM as non-case activities. When you enable CiviCase, a new action will be available that allows you to file any non-case activity onto a case.

Additionally, when email activities are sent from the Manage Case screen, if the Email Processor has been set up then replies will automatically be filed directly onto the case.

5. 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 Drupal or Joomla! user account.

For Joomla! installations, staff members must have back-end (administrator) access. All CiviCase functions are done within the Joomla! Administrator interface.

You should also add contact records for service providers who will be assigned case roles but will not be accessing the CiviCase system. This will allow your staff to easily send emails with pertinent case and client information to these providers via CiviCase, as well as record case-related interactions reported by providers.