E-mail
CiviCase Phase 1 - Scope of Work
This document summarizes the modifications and enhancements targeted for Phase 1 CiviCase implementation - subject to approval by PHP-BC. Scheduled delivery of a working alpha to PHP-BC is early December 2008. Scheduled availability of production code for this phase is January/February 2009 (included in the 2.2 release).
Relationships
- Extend Relationship data model to link Service Providers or other stake holders (contacts) to a Case (case management 'roles') by adding a Case ID to the Relationships table.
- "Expected roles" (relationships) are created when the case is created - and will not initially be assigned to a service provider. We can handle this by allowing a NULL value for the "service provider" side of the relationship (contact_id_b by convention). EXAMPLE: Relationship type defines contact_a as "Client" and contact_b as "Addiction Counselor". When the case is created, a relationship of this type is inserted, setting the client's contact ID as contact A, and setting contact B to NULL (until the case coordinator assigns that role for the case).
Cases
Case Configuration (by Case Type)
- Define Case Roles - There will be a defined set of expected case roles ("CiviCRM relationships") for each case type. When a case is created, a record for each "expected" is created and linked to the case. Each "role" will be listed with "Add" buttons on the View Case screen. The case manager can then populate the relationships as the case progresses - which replaces the "Add" button with a link to that person's contact record.
People Involved in this Case
- Addiction Counselor: » Add
- Primary Physician: Jane Grant
- Define Case Standard Plan - Set of activity types for which Activity records are pre-populated when a case of this type is created.
- Define Case Reviews or "Named Activity Sets" - These are named sets of Activity Types (e.g. 15 Day Review, Cigna Disability Application, etc.). The case mgr will select one of these when they choose to run a "Case Review" - and CiviCase will determine which activities in the set have been done and which haven't and present that data on a screen.
NOTE: Both the "Standard Plans" (auto-populated activity types) and the Case Summary / Requirements are "sets of activity types". They can both be defined in the same XML file with the same structure - and use a flag to mark one set as the "Standard Plan" for each case type. Some items in these sets also require a date offset FROM another Activity Type (which by default would be the "Case Opened" activity).
Case configuration settings will be stored in an XML format which can be modified via text (or XML) editor. For phase 1, no user interface will be provided for maintaining these settings.
Case Dashboard
The CiviCase component dashboard (home page) is intended to provide at-a-glance status of Cases and Activities for the logged in user. The summary table will include case load by case type and status. Users with "access CiviCase" permission will see "their cases" by default (cases for which they have an active "Case Role"). A button to "Show ALL Cases" will be included to switch the view. The dashboard will list "Cases with Upcoming OR Overdue Activities" and "Cases with Recently Performed Activities" - giving the logged in user quick access to "active cases".
Viewing and Editing Cases
The existing screens for viewing and editing a case will need to be modified extensively to reflect the conceptual shift to storing almost all data in Activities. The View Case screen will include:
- Case Type, Status and Open Date with links to change type and status
- Case Roles (list of related service providers and stakeholders) with links to send case-related email to each or all people involved in the case
- "Add a Timeline" features allows user to insert a selected "set" of scheduled activities into the case (see Named Activity Sets below).
- Filtered list of Activities (with compact form for selecting and modifying Activity filters)
Cases should also be extensible via Custom Fields.
Named Activity Sets for Reporting and Adding Timelines
Case configuration files will include any number "named sets of activity types".
Users will be able to select a set to run a "Report". For phase 1, output will be in the form of a two paned HTML page providing visual "map" to the state of the case. The output screen should display available data for all the referenced activity types - with visual flagging of activities / activity data that is "missing" (based on the requirements of the selected case review).
Users will also be able to select a set for the purpose of inserting additional scheduled activities into the case.
For phase 1, the only differentiator between the configured activity sets is that ONE set will be the designed standard timeline for that case type. This set determines what activities are auto-populated when a case of that type is created.
Activities
- Activity Type Categorization - Given the large number of activity types, add a mechanism for assigning categories to activity types. This will allow us to provide a hierarchical select interface to users when they are filtering lists of activities, AND when they are selecting an activity type to add to a case. EXAMPLE: Category -> Personal History, Activity Type -> Last Contact with MD
- This will probably require pulling Activity Type out of the option_value table and creating a dedicated table for these items.
- Custom Fields by Activity Type - Many activity types will require custom fields. We can use our existing model for extending the Activity input form and display based on activity type. Given the large number of fields to be configured, we will implement a method to define all custom fields using an XML file and load the configuration via a command line script.
- Screen Layout -Define separate form layout templates to be used for Add / Edit Activity and View Activity when the Activity is linked to a Case. This will allow us to include fields that are not useful for existing standalone activity functionality, as well as modifying some field labels if needed without conflicting with current usage of these screens.
- Due Date - Expose the existing Due Date field so that each activity can have BOTH a Due Date and a Completed Date.
- Record Created By and Created Date - These values will be stored for all activities automatically in the civicrm_log table. This value is independent of the source_contact_id value ("reported by") - which may or may not be the person entering the record. Created by / date data will be displayed (read-only) when viewing an activity. Users will be able to search for activities on "Created By" and "Created Date" (range).
- Reported By - The existing "source contact" field which is currently labeled "Added By" will be used to record the "Reported By" contact (and relabeled for activities in a case). The "reporter" may be the case coordinator / user who is logged, in OR may be the client or some other "role" (parole officer, co-worker, doctor, counselor, spouse, etc.). The current behavior defaults source as logged in user and allows them to change it. This is ok - but we may need a second method of picking source from a filtered list of "roles in the case" (e.g. people related to the case).
- Case Role - Include an optional field to record the relationship of the "reporter" to the case. This is needed because service providers may fulfill multiple 'roles' in a case. If the selected "reporter" only has a single relationship to the case, this can be automatically populated. Otherwise a drop-down is proved.
- NOTE: Target contact (With ...) will always be the client - and we'll relabel this for activities in a case (same usage as Front Line and other general activity input)
- Activity Audit Trail - In case management settings, activities should not be modified directly once they are created. We will provide an Edit link for permissioned users. However, editing an existing activity will actually create a new copy of the record when edits are saved. Copies will be linked to the original via foreign key. The latest copy will be displayed by default. If older revisions exist, a link to a listing of prior revisions will be displayed when viewing an Activity. Users can click a prior revision to view it (read-only access).
- Medium - Add new field to core Activity schema to record the "Medium" for the activity - e.g. In Person, By Phone, .... (The existing Activity Types of Meeting, Phone Call, Email can not be used here - since we will be using much more specific types which do NOT specify the type of encounter. We will probably need to suppress this field for those existing "generic" types since it will be redundant.) Implement a new group of Option Value for this field so administrator can modify the list of options. Default values: Face-to-face, In-bound Phone, Out-bound phone, Email, Letter.
- Auto Generated Flag - Activities which are auto-populated (based on Case Type configuration) need to be marked (is_auto_generate). This allows us to remove them if the user changes the Case Type (and they haven't been completed).
- Email a Copy of the Activity Record - Add the ability to email a copy of any Activity record to selected contacts. Recipients are limited to contacts with a "relationship" to the case ("Case Role") (verified by David D on 9/23). Interface should make it easy to send to ALL or some of these contacts.
- Schedule Follow-up Activity - While adding or editing an Activity, users will be able to specify a follow-up to be scheduled N days in the future.
- Move to Trash feature - In order to ensure that all recorded data is available for audit trails, the "delete" function for Cases and Activities will be modified to simply set a "Deleted" flag on the record (rather than physically deleting it from the database).
- Activities with Anonymous Clients
- PHP-BC provides a large number of "services" (mostly by phone) to anonymous clients. These can be tracked as Activities which are not linked to a Case. However, we need to figure out the right way to specify the activity "target" (recipient of service). Preferred approach (since it simplest) is to create an "Anonymous Contact" record and (by convention) users will select that contact as the client ("target") when recording an Activity (service provided) to an anonymous client.
- Link Standalone Activity to a Case - We may need an interface to link Activities to a Case AFTER they are created (phase 2?).
Search Requirements
The current thinking is that full-text searching would be the ideal solution for case / activity searches. We'll look at this for phase 2. For phase 1, basic search by client name/email, case type and status will be implemented.
Find Cases
Search criteria for cases:
- Client Name or Email
- Case Type
- Case Status
Find Activities
NOTE: Standalone activity search is ON HOLD for phase 1. Based on our October meetup with PHP-BC, this functionality is not required.
Currently available activity search criteria are:
- Activity Type
- Activity Dates - From / To
- Contact Role (Added by, Target, Assigned)
- Activity Status
- Subject
With CiviCase enabled, we need to add:
- Activity Category >> Activity Type (with multi-select?)
- Case Role
- Due Date
- Created By / Created Date
- Auto-generated
If custom case and activity fields which are searchable should be included in the search component forms. For phase 1, this will be limited to a small number of the total set of custom activity fields. However, custom fields for different activity types may have the same or similar names, so the Activity Type label should be prefixed to the custom field when displayed in search forms.
Permissions
For phase 1, a single permission will be used to determine if the user can view, create or edit case data - "access CiviCase".
Based on user feedback on phase 1, we will consider implementing more granular permissioning. This may include the following roles:
- Supervisor
- add case and assign relationships (including case coordinator)
- view and edit any case and it's activities
- add or edit any activity
- Service Provider (case coordinator, social worker, etc.)
- add case and assign relationships
- view and edit any case which they have a relationship to ("their cases")
- add activities in those cases
- edit activities which they've created ("their activities")
- view all activities in "their cases"
Data Redaction
Data redaction involves either hiding or replacing data which identifies a specific individual with some generic value. For this phase of CiviCase, redaction requirements are as follows:
- Only "Case Report" output files will be redacted. No redaction is required for edit and view screens within the CiviCRM interface.
- Redaction is limited to expressing all contact-specific values using a unique hash of that contact's ID.
EXAMPLE: Jane Smith, whose case role is "Addiction Counselor" records an Activity about her "Assessment Interview" with the case "client" - Paula Jones. When the activity is output in the Case Review XML file - it might look like this:
Record Activities for a Case via Email
Some service providers need an easy way to add activities to a case when they are "in the field". We will provide a mechanism to do this via email:
- User sends email to case+case_id@civicase.physicianhealth.com
- CiviCRM supplied script will retrieve and process emails from that (wild-carded) mailbox;
- Parse email for Case ID and verify that FROM (sender) has a current "relationship" to that case
- Insert activity record for that case. Email subject => Activity subject
- A generic activity type ("Inbound Email") will be assigned unless the email message includes a valid activity type in the first line
8 Comments
Hide/Show CommentsSep 25, 2008
D D
Some comments based on my experience with Workplace Disability case management.
1) Case roles:
A very common use case is "Jane has left, or is on mat leave, so now all her cases need to be reassigned to Mary". Attempts to deal with this in the past by using indirection (e.g. similar to the way you might use email groups like sales@company.com) failed because people can't quite get their heads around it. So there's a need for a feature to batch reassign selected roles for a selected group of cases. Maybe not a phase 1 item. Not sure what the caseload size is for the PHP-BC.
2) Dates:
Some suggestions:
a) Don't use the words start/end/open/close anywhere. These words have different meanings to different people, sometimes even within the same organization. And don't store it in the case record.
Here's an example of what will happen if it's in the case record: A case is managed for short-term disability and they put in a "start" date. The case goes to long-term disability. The new case manager will go and change the start date. What you really want are two activities:
- The date that short-term disability case management started.
- The date that short-term disability case management ended == The date that long-term disability case management started.
And in fact to the subject/employee, the "start" date is neither of those. You'll also have activities like "date the symptoms first started" and "date that employee first went off work".
So in short, instead of start/end, use "DATE THAT such and such happened". The one date that can go in the case record is the date that the case was created in the database, since it's a system date. In practice nobody involved in the case ever uses that date though, and it's used more as an audit control or aid in troubleshooting.
b) I'd also recommend storing all dates in GMT. It solves ALL problems. This doesn't mean you have to display it as GMT, just store it that way in the database and convert for display as necessary.
c) It's very common to have a situation where there is a "break" in cases, meaning that for the purpose of counting days, you need a way to exclude some days. So this is another reason not to use "start" and "end", because it's very common that the "duration" number you want to compute is NOT [end date - start date].
Example:
Employee goes back to work, but then a week later experiences a recurrence and goes off work again. Many insurance policies will consider this the same claim and when adding up the days they will want to exclude the days they were back at work.
3) Emailing a copy of the record:
As discussed by phone, if roles are configurable there wouldn't be a need to email a copy to someone not involved in the case.
4) Prepopulated sequences:
This maybe needs a little more thinking about, because there are some situations where the sequence has some if-then branches, so you don't know until later which branch. I'll be posting some sample sequences to give some idea.
Also a note that there's situations where the branch depends on multiple previous activities, not just a single activity. It might be workaroundable by defining separate activities for every possible variation of a situation, but that becomes unwieldy for users.
5) XSLT:
My experience with XSLT is "don't use XSLT". I've always ended up using DOM/SAX api's.
Regarding XML in general, I've found that it's wonderful for config files, but not for storing/transferring/manipulating data, but others may have different experience.
Generally there are two types of users who need to see some type of data from the system. The workers involved, who need to see things to help them do the work, and their managers, who need to make reports. In the latter case, the end format will almost always be a spreadsheet, and with html output to the browser screen the user can't edit it before printing unless you provide functions to do so.
For the specific case review feature, I'm thinking spreadsheet wouldn't be a bad format either, but browser screen may also be convenient. It may be helpful to enumerate all the use cases for the case review feature.
a) User wants to know what still needs to be done
User clicks link/button
User selects only show "missing" activities
b) User wants to prove they've done everything for audit/QA purposes.
User clicks link/button
User selects to show all activities
User emails or prints the report for delivery to the audit/QA person
c) Case managers' manager wants to generate a report
User clicks link/button
User selects "all" cases, or some filtered set of cases, and selects to show all activities.
User manipulates report and emails/prints it.
Optionally the report is filed for reference.
d) Other?
6) Redaction:
Is it necessary to output the <clientid> and private fields at all? Can they not just be removed?
Scrubbing the <description> section will be difficult as it is freeform text. Andrew pointed out an article at http://dl.getdropbox.com/u/198969/Software%20Tool%20for%20Removing%20Patient%20Identifying%20Information%20from%20Clinical%20Documents.pdf that describes some techniques, but again I'm wondering if this section can just be excluded, given the statement that this is all only for case review.
Sep 27, 2008
Andrew Clarke
Excellent insights, Dave. I would just caution that in the physician health field (and probably others) there is a somewhat more "in depth" need for QA audits. We might not succeed in finding a reliable way to automate the redaction/scrubbing of freeform text. It's a nice grail, though, as long as it doesn't consume too many resources that would be better spent on other projects (like a full set of user documentation). I agree that the client ID is probably not a field that will be let pass unredacted.
Regarding the need for certain pre-populated activities to depend on multiple previous ones. I don't know if it would be feasible to store a code fragment (PHP or ?) with the definition of the activity that gives it some internal logic about how to configure itself based on the existence or properties of multiple other activities in the same case.
Sep 26, 2008
D D
Clarification on start/end/open/close
The words can be used, but not "standalone". So not "case start date", but there can be "STD claim start".
Singleton Activities and Audit trail
There are some activities where there's only ever one of them, like "Reduce STD benefits to 70%" or of course "STD claim end". The assumption could be that the latest one is the "real one" but it's awkward for users if you have multiple ones showing up on a case. Then there's a related situation of users without edit access being unable to fix mistakes.
So one solution is that since you've already got the audit trail when you edit, you would have permissions of either read-only or editor, and not use the "create but not edit" permission. But a nice enhancement would be to add a configuration property to activities to identify them as singletons, so that if a user tried to create a second one, it would just redirect them to edit the existing one.
Sep 27, 2008
Andrew Clarke
I think that the idea of marking an activity as a singleton and providing redirection on request to edit as you've suggested is brilliant.
Sep 29, 2008
Andrew Clarke
It seems like what you're suggesting here is replacing the word "case" with the type of case when we develop user-facing text labels. This isn't exactly critical for proper system function, but really helps the users develop a better understanding of what it is they're asking for when they ask for reports on case activity.
EXAMPLES:
If the type of case is "STD claim" then we would refer to the date of the "start" activity as "STD claim" + "start date".
Likewise, if the case type was "child advocacy" we would use "child advocacy" + "start date"
Is that a fair distillation of the essence of your suggestion?
Sep 29, 2008
D D
I'm saying people use the word "start" differently depending on what role they're in, even within the same organization, and so if not qualified with a second word it ambiguously refers to multiple activities recorded on the same case. There would be a "first" activity when sorted by what date an activity was entered into the database, but then might as well use the date the case record was first entered into the database, and it should be labelled that way. But that date isn't meaningful for most tasks.
So it depends what you need it for, and that depends what role you're in, and even more specifically, what task you're currently trying to perform.
Oct 07, 2008
D D
Making a note about the situation where you have "breaks" in cases. We discussed as a phase 1 possibility that the feature to repopulate an activity set could allow the user to shift the dates manually by entering a number of days. I've posted improved support for it as a phase 2 possibility.
Oct 07, 2008
D D
Also we discussed that some activities require one or more previous activities to be "overwritten", for lack of a better word, but not sure if it would be a phase 1 or 2 item. One example is the break situation just mentioned. If an "XXX claim end" activity has been entered, then when the break is over, you need some way to clean that up, otherwise you'll have two "XXX claim end"s on the case when that activity happens again later, and if data is stored at the case record level it might be out of sync. It can be done manually, editing the activity, but is then error prone if the user forgets or if it's a more complicated situation involving multiple activities.