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

• The action should be basically API actions
• Should be flexible to extend by developers. E.g. it should be easy to add new event types, new condition types, new action types
• Rules (event, condition and condition) should be stored in the database as well as in code, like Drupal Views and Drupal Rules but does not need to be as sophisticated as Drupal does.
• It should be possible to extend the storage layer
• It should use the queue mechanism of CiviCRM Core (take a look at scheduled reminders on how to use this queue mechanism)
• It should be possible to send e-mail, sms, print pdf letter as an action

Roadmap

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

• Create mockups

• Investigate the core queue mechanism and document it

• Create the basic framework for the rules extension

• Create a UI around the framework

• (API) action for sending e-mail

• (API) action for sending SMS

• (API) action for printing PDF Letter

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

The following form will be shown when the user clicked 'Add condition' 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.

• hook_civicrm_rules_event_types: returns event types to the framework
• Invoke Event: api to invoke an event in the civicrm rules module
• hook_civicrm_rules_condition_types: returns condition types to the framework
• hook_civicrm_rules_action_types: return action types to the frameworks

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
• condition definition
• action definition

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.

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. 

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:

• event: the name of the event
• event_parameters: an array with additional parameters for this specific event