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.

Planning

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.

Assumptions:

• Cases involve a sequence of interactions (activities). The record of these activities form a narrative for the case.
• Case management settings can classify their cases into a known set of case types.
• Cases of a given type often have a predictable sequence of activities (a standard timeline). Creating a schedule with the expected activity sequence is a useful way to measure case progress.
• Cases of a given type have a predictable set of human service providers (case roles). Knowing who is playing what role in a case is helpful for everyone working on the case. Case workers need an easy way to communicate case activities to other people who are working with the client.
• Case management settings may have additional people and / or organizations who are frequently contacted / involved with most or all cases (case resources).

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:

• Inpatient treatment
• Referral to counselor
• Relapse prevention

For a community services organization, examples might include:

• Housing assistance
• Job training
• Prenatal counseling

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:

• Who recorded the activity and who "reported" the activity.
• When and where did the activity occur
• Free-form subject and details

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:

• Case Roles - People directly involved in this case. Examples include Case Coordinator, Addiction Counselor, Intake Physician, etc.
• Other Client Relationships - People related to the client (typically relationships exist beyond the context of a particular case). Examples include Spouse, Sibling, Family Doctor, etc. Generally, use a relationship when you want them to appear on ALL cases for the same client, otherwise use a role.
• Case Resources - People and organizations which have involvement with many / all cases in your case management setting. Examples include: Regulatory agency contact(s), service provider / frequent referral contacts, etc.

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:

• Case Coordinator
• Addiction Specialist
• Job Counselor

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

Overview

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:

• access to a text editor
• access to upload XML files to the server directories where CiviCRM is installed
• (optional) the ability to load a SQL script into your CiviCRM MySQL database using phpMyAdmin or mysql command line

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.

Step-by-step

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 yoursite.org/civicrm/admin/setting/path&reset=1 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. <civicrm_root>/CRM/Case/xml/configuration.sample/HousingSupport.xml 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 (civicrm_option_value.name). 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 (civicrm_option_value.name).

<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.

<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"). (civicrm_option_value.name 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.

Include these Activity Types in All Case Configuration Files 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.

3. Global Settings

Global Settings file (Settings.xml)

• If you haven't already done so, copy the sample CiviCase settings file to the same directory where you've created / edited your case type configuration xml files.:
• The default copy of this file should look like this:

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.

• Create a new Group in CiviCRM: Manage Groups » New Group with a meaningful name ( "Case Resources" for example).
  • Leave the two options for Group Type, access control list and mailing list, unselected.
  • The default visibility of User and User Admin only is fine.
  • There is no need to add a parent group.
• Add a contact record (New Individual, New Organization) for each contact you want to include initially in this listing. Enter a primary phone number and an email address for each contact record if your case management staff will need easy access to emailing or calling these contacts. Assign these contacts to your CaseResources group as you create them. For existing contacts, you can do this from Find Contacts » more actions » Add Contacts to Group.
• Open Settings.xml in your text editor and replace the group name with your group's name. Replace any spaces in your group name with an underline character, and retain upper and lower case. Save your changes.

Other Global Settings

Several other default behaviors are controlled from Settings.xml.

• Force emailed copies of case activities to be redacted (case and client information obfuscated) before sending by setting <RedactActivityEmail> to 1.
• Allow users to assign more than one client to the same case by setting <AllowMultipleCaseClients> to 1.
• Modify the list of case activity types which can not be edited using the <ActivityTypes> section, <editable> parameter.

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:

• Go to Administer CiviCRM » Global Settings » Enable Components
• Select CiviCase in the left-hand box and click Enable. This should move it to the right side.
• If your organization is not planning on using some of the other CiviCRM components - you can Disable them by moving them from the right to the left side. (EXAMPLE: If you are not tracking donors, managing events or membership - move CiviContribute, CiviEvent and CiviMember to the left side.)
• Click Save.
  You should now see a CiviCase menu item in the CiviCRM menu block. You should also see New Case for New Client in the CiviCRM Shortcuts block.

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:

• If using Drupal, you will need to give yourself the "administer CiviCase" permission.
• Administer CiviCRM » CiviCase » Case Types
• Click New Case Type
• Complete the form - using the exact same text for the Label as you entered for the CaseType <name> element in your case configuration files.
• Click Save

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:

• Administer CiviCRM » Option Lists » Activity Types
• Click New Activity Type
• Complete the form - using the exact same text for the NAME as you entered for the ActivityType <name> element in your case configuration files. Select CiviCase in the Component drop-down

• Note that if your xml is MyCase.xml your Name needs to be MyCase. If your xml is mycase.xml your name should be Mycase. The first letter needs to be capitalised for all files. Subsequent ones will follow what you enter.

  .
• Click Save
• Repeat for each unique activity type defined in your case configuration files.

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:

• Administer CiviCRM » Option Lists » Relationship Types
• Click New Relationship Type
• When completing the form fields - define the relationship using the client as Contact A and the service provider as Contact B. The Relationship Label-B to A value should match the text entered for the RelationshipType <name> element in your case configuration files.

Case Coordinator role example 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

• Repeat for each unique case role defined in your case configuration files.

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:

• Administer CiviCRM » Customize » Custom Data
• Click New Group of Custom Fields
• Under Used For, select Activities and then select the specific activity type for which this field or fields will be used.
• Enter any help you want displayed to your users.
• Click Save
• Enter one or more custom fields for this group.
• 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 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. Change site preferences

If you wish to see a tab for a contact's cases when viewing a contact, or if you wish to search for case details in Advanced Search then you'll need to change the site preferences.

Using the admin screens:

• Administer CiviCRM » Configure » Global Settings » Site Preferences
• To see case details when viewing a contact record, check "Cases" under "Viewing Contacts"
• To allow for searching on case details with Advanced Search, check "Cases" under "Contact Search"

8. 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.

• For Drupal - Staff accounts must be granted the "access CiviCRM" and "access CiviCase" permissions. Unless you are implementing group-level access restrictions - you should also grant the following permissions to staff:
  • access all custom data
  • access uploaded files
  • add contacts
  • edit all contacts
  • view all activities
  • view all contacts

• For Joomla - Staff accounts 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. 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.