The proposals described here aim for use with CiviCRM 4.4 and CiviHR 1.2. To avoid any major changes in core, the changes should be developed as a new extension, "org.civicrm.caseutil", which builds on top of existing hooks. As it matures, we can look at moving the extension into core for CiviCRM 4.5.
In CiviCase XML, add support for a new tag, <Listeners>. A case-listener receives notifications about changes to the case and takes some follow-up action, such as adding a new scheduled activity.
When implementing a listener, one should have access to the case, the case XML, and any activities. And one would implement a listener as a class:
Registering listeners through the XML will produce more cogent XML documents and make it easier for readers to trace the code, However, hooks are also useful and common way to handle listeners, so we can do that as well:
Looking at this critically, why should we add any of these tags, classes, or hooks? The same functionality could be achieved by listening to existing actvity-hooks (ie hook_civicrm_post with the "Activity" entity). The proposal here solves a few issues with activity-hooks:
- When listening to an activity-hook, you need to determine whether the activity is relevant to your case-type, and this requires loading the case record. Similarly, you may need to analyze the other activities which have occurred in the case before deciding what to do, and this requires more loading. If the system has multiple modules loading the cases and activities, then it will add-up to a lot of redundant loading. By passing in CRM_Case_Analyzer, one avoids this.
- With activity-hooks, a developer who tries to read and understand the code for a case-type must take the initiative to cross-reference the XML (for a list of allowable activity types) and the hooks (for a list of workflow rules). By referencing the workflow rules in the case XML, we make it easier for the developer to start reading from a high-level perspective (the XML) and drill-down to details.
The proposal here provides something more advanced than activity-hooks, but it can build on top of the activity-hooks – we can implement the listener system as an extension (without patching core):
When coordinating a series of activities, one common pattern is to perform them in sequence: schedule activity A; when it's complete, schedule activity B; when that's complete, schedule activity C; when the final activity completes, close the case. This pattern isn't exceedingly flexible, but it's simple and close enough for some situations. To support it, one would add this to their XML:
Pipeline Test (Pseudocode)