Drupal 'cron' and CiviCRM tasks

Certain things in CiviCRM need to happen on an automated basis. The most straightforward way of acheiving this is via drupal's fake cron process, which is well documented on the drupal site. Our drupal cron configuration is set to run hourly, and is triggered when the timer exceeds that limit AND a page somewhere on the drupal site is accessed.

To create a Drupal cron task, implement a cron hook function in a Drupal module. This should be called {MODULE_NAME}_cron(). To ensure that CiviCRM is correctly initialised, the method should first run the function

civicrm_initialize();

GENVASC 'mark as available' activity

This has been applied to test, but not production.

The code is located in the genvasc_labels module and uses the CiviCRM API. The process is as follows:

1. Select all the cases with a type of 'Genvasc' that have a status of 'Recruited'.
2. Load the activities for these cases.
3. Disregard any case that does not have an activity of type 'Mark available for cohorting' that is due in the past.
4. For the remain tasks carry out the following processing.
5. Update the case status to 'Available for cohorting'.
6. Add a new activity against the case of type 'Status Changed'. The target contact is the case contact, and the source contact is the 'Cron System' user (see below).
7. Update the 'Mark available for cohorting' activity status to be completed.

This change requires the amended Case API that has been submitted to CiviCRM as a patch. The original version of the civicrm/api/v3/Case.php has been renamed to civicrm/api/v3/Case.php.old.

Note regarding Cron System

By default, the activities and entries created by automated jobs in this way are assigned to whichever user triggered the cron job, in a similar way to the user who accesses an API call in a module being assigned to the results of that API call.

However, for an automated process this isn't what we want, because cron jobs will be assigned to whichever user happens to be logged in at the time the job is triggered. Instead, the LCBRU module creates a CiviCRM contact called 'Cron System' (LCBRU Staff sub-type), and all the functions and activities performed by cron tasks should be explicitly assigned to that specific contact ID. This will require the cron job to look up the Cron System in order to obtain the correct contact ID.

CronHelper

In order to assist with some of the common tasks associated with Drupal cron tasks a new CronHelper class has been created.

Functions

1. Initialise CiviCRM
2. Switch the user used for thr cron job from the anonymous user to the Cron System User for the duration of the processing.
3. Check whether the cron job is enabled.
4. Ascertain if the cron processing is due to run.

Usage

The following code shows how the cron Helper should used.

// Implementation of Drupal cron hook
function module_cron() {

   $helper = new CronHelper('JobName');
   $helper->runCron(function() {
           // Do stuff here
       });
}

Things to note are:

• The jobName parameter cannot be NULL or empty.
• The following additional option constructor parameters can be used to change the default enabled status and frequency:
  • $defaultEnabled - takes values true or false. The default is false.
  • $defaultFrequency - takes one of the CronHelper frequency constant values:
    • CronHelper::FREQUENCY_EVERY_CRON
    • CronHelper::FREQUENCY_DAILY
    • CronHelper::FREQUENCY_WEEKLY (default)
    • CronHelper::FREQUENCY_MONTHLY
• The runCron function takes either an anonymous function or a function name as it's argument.

Config Usage

The values for the enable status and frequency can be changed by the user using a module configuration form. CronHelper provides a utility function to add the setting fields to a configuration form. For example

function _module_config_form($form, &$form_state) {

  $helper = new CronHelper('JobName');

  $helper->addSettingsToForm($form);

  return system_settings_form($form);
}