This page is work in progress documentation for CiviRules. 

Introduction

CiviRules is based on the Drupal Rules module and does react on an event (post create contribution) and executes a certain action when certain conditions are met. 

This page will contain what we have thought of what needs to be done to develop such an extension. Rather than just starting (what we have done with trigger-action extension) this one is a bit more thought of. So this description is also a basic for a wider debate on how things should work.

Requirements

Roadmap

The following needs to be done. This are the actions we identified so far

Mockups

Initial form shown to user when he/she selects 'CiviRules' from 'Administration' menu

Form shown when a user clicked 'manage' on the initial form or clicked on 'Add CiviRule'. In the latter case there will obviously be no existing Events, Conditions or Actions.

The following form will be shown when the user clicked 'Add event' in the Manage CiviRule form

 

Framework

Below a draft of the API for the framework. This api consist of hooks and functions other extensions could invoke.

Interfaces

Below a more detailed description of the interfaces we are going to use in the framework. The interfaces we have identified are:

Event definition

The event definition contains a system name (name), a human readable name (label) and a description. Any new event should implements this event definition.

Interface CRM_Rules_Interface_EventDefinition {
 
    /**
     * Returns a system name of this event
     * e.g. post_contact
     *
     * @return string
	public function getName();
 
	/**
     * Returns a human and translatable label of the event
     * E.g. 'Before a contact is changed'
     * 
     * @return string
     */
	public function getLabel();
 
    /**
     * Returns the name of the entity e.g. 'Contact', 'Contribution'
     *
     * @return string
     */
	public function getEntity();
 
	/**
     * Returns whether the given event parameters are valid. 
     * If they are not valid the whole rule would probably not be executed
     *
     * @param array $event_parameters
     * @return bool
     */
	public function validateEventParameters($event_parameters);
 
}

 

Hooks

Below a more detailed description of the hooks

API: InvokeEvent

The API of this extension consist of a call to the extension to trigger events of a certain type. E.g. in the post hook we want trigger the post event for a certain object. 

function my_civicrm_post($op, $objectName, $objectId, $objectRef) {
	$api = civicrm_api3('Rules', 'InvokeEvent', array(
		'event' => 'post_'.$objectName,
        'event_parameters' => array(
           'operation' => $op,
           'entity_id' => $objectId,
           'entity' => $objectName,
           'entity_data'  => $objectRef,
        );
	));
}

This call will invoke the rules extension to check whether any post events should be checked. Our aim is to implement by default the pre and the post events which are triggered in the pre and post hook and we will use a flexible mechanism because if any new use cases appear in the feature they can be easily implemented. However we cannot think of any yet.

As soon as invoke event is fired the rules module will check whether any active events are available and executes those events.

Parameters

The invoke event has the following parameters: