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.
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.
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. 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.
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.
<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.
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.
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).
Using the admin screens:
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:
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:
* Click Save
6. Custom fields
It is likely that you will want to collect some structured data for some of the activity types you've defined.
Please review the section on configuring custom data fields prior to beginning these steps.
Using the admin screens:
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.
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.