Configuration

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.

Prerequisites

Many of the configuration 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
• (optional) write or modify a simple program using the API to automate the creation of activity types or relationships.
  

Configuration Tasks

Follow these steps to configure CiviCase for your organisation.

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

<civicrm_root>/CRM/Case/xml/configuration

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:

http://en.wikipedia.org/wiki/Xml

A set of sample configuration files are included when you download CiviCRM. If you can access the CiviCRM codebase at http://svn.civicrm.org/civicrm/, 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.

<civicrm_root>/CRM/Case/xml/configuration.sample/HousingSupport.xml

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:

 

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: 

 

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:

http://wiki.civicrm.org/confluence/x/UIC9AQ

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

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.

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

• go to Administer -> Configure -> Global Settings -> Enable Components
• select CiviCase in the left-hand box and click Enable (this should move it to the right side)
• click Save.

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

3. Review CiviCase 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 (Administer -> Users -> Permissions). You may want to create case management specific Drupal user roles for staff, based on their responsibilities within your organisation. Permission options are described in the Planning chapter of this section.

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:

Case types

• 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

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 "out of the box". However you will need to manually add any other activity types that you've defined in your case configuration files.

• Administer CiviCRM -> Option Lists -> Activity Types
• Click New Activity Type.
• Complete the form using the exact same text for the Label as you entered for the ActivityType <name> element in your case configuration files.
  
• Select CiviCase in the Component drop-down.
• Click Save.
• 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:

 <?
require_once 'civicrm.config.php';
require_once 'CRM/Core/Config.php';
require_once('api/v2/ActivityType.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);
  $result = civicrm_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.

• 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.
• Click Save.
• Repeat for each unique case role.

For example, to define a Case Coordinator relationship type:

Relationship Label-A to B : "Case Coordinator is"
Relationship Label-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:

<?
require_once 'civicrm.config.php';
require_once 'CRM/Core/Config.php';
require_once('api/v2/RelationshipType.php');

//read the API chapter to get more explanation
$types = json_decode ('[
 {"label_a_b": "Case Coordinator is","label_b_a":"Case
    Coordinator","contact_types_a":"Individual","contact_types_b":"Individual"}
,{"label_a_b": "Benefit Specialist of","label_b_a":"Benefits
    specialist","contact_types_a":"Individual","contact_types_b":"Individual"}
]');

foreach ($types as $type) {
  $result = civicrm_relationship_type_add (get_object_vars($type));
  if (civicrm_error( $result )) {
    echo "\n ERROR creating $type: ". $result['error_message'];
  } else {
    echo "\n Type $type created";
  }
}
?>

Custom fields

It is likely that you will want to collect 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 Counselling 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 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.

• Administer -> Customize -> Custom Data
• Click New Group of Custom Fields.
• Under Used For, select Activities.
• Select one or more specific activity type(s) for which this set of fields will be used.
• Enter any help information you want to be displayed to your users.
• Click Save.
• Enter one or more custom fields for this set.
• 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 Inbound Emails to Cases

Some organizations find it useful to record incoming 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 the reply to become part of the case story.

You can enable this functionality by configuring the provided Email Processor script as described here:

http://tiny.booki.cc/?vfW0

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.