Skip to end of metadata
Go to start of metadata



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.

Case Listeners

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):

caseutil.php (pseudocode)


Case Analyzer




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:

CiviCase XML with Pipeline

Pipeline Test (Pseudocode)

Pipeline Test: Example XML
Pipeline Test: PHPUnit (Pseudocode)



  • None
  1. Jun 10, 2016

    Did anything ever happen with this?

    1. Jun 10, 2016

      The hook was implemented as

      The analyzer was implemented as

      The "pipeline" concept was renamed to "sequence". The main controller for it is (  )

      The SequenceListener was brought into core, so we haven't actually used XML to register any listeners. However, support for that does appear to be in the code:

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.