![]() | Deprecated page This wiki page is no longer kept up to date with the project progress. Up to date documentation on CiviRules can be found at http://redmine.civicoop.org/projects/civirules/wiki |
This page is work in progress documentation for CiviRules.
- 1 Requirements
- 2 Roadmap
- 3 Mockups
- 3.1 Initial form from Administer Menu
- 3.2 Manage CiviRule Form
- 3.3 Add Event Form
- 3.4 Add Condition Form
- 3.4.1 Data comparison form
- 3.4.2 Data value form
- 3.5 Add Action Form
- 3.5.1 Add contact to group form
- 3.5.2 Set data value form sequence
- 3.5.3 Send PDF letter form
- 4 Framework
- 4.1 Interfaces
- 4.1.1 Event definition
- 4.1.2 Action Definition
- 4.2 Hooks
- 4.2.1 hook_civicrm_rules_event_definition
- 4.2.2 hook_civicrm_rules_action_definition
- 4.2.3 hook_civicrm_rules_alter_dataselectors
- 4.3 API: InvokeEvent
- 4.3.1 Parameters
- 4.4 Models
- 4.5 Data diagram
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
In this section several mockups show the desired workflow of a couple of CiviRules.
Initial form from Administer Menu
Initial form shown to user when he/she selects 'CiviRules' from 'Administration' menu
Manage CiviRule Form
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.
Add Event Form
The following form will be shown when the user clicked 'Add event' in the Manage CiviRule form
Add Condition Form
If the user clicks 'Add condition' in the Manage CiviRule form a couple of forms can be presented, depending on what route is followed. The first form will always appear, the others depend on the selection. A couple of tracks are added here without the presumption of being complete
Data comparison form
If the user selected Data comparison and clicked 'Continue'
Data value form
If the user typed Contact.total_contributed_amount_this_year and then Clcked 'Continue':
That completes this specific condition, the next step would be to add the action.
Add Action Form
So if the user clicked 'Add action' in the form Manage CiviRule, the following sequence will start:
Add contact to group form
In the example 'Add contact to group' has been selected so the next form will show a list of active groups that can be selected, which then completes the action.
Set data value form sequence
If the user selects 'set data value' he or she will be presented with the next form. Actually, most actions could be done with 'set data value' (or a combination of them) but some shortcuts will be provided with the data selectors.
In the next form the user gets to enter the actual value. This could be an input field (with relevant replacement patterns if any) or a select list.
Send PDF letter form
Framework
Below a draft of the API for the framework. The framework consists of the following
- Interfaces
- Hooks
- API
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
- 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.
Action Definition
The action definition interface consists of a system name of the action, a human readable label of the action and optional an entity on which the action is performed. An action could be something like add contact to group, or set data value.
Hooks
The following hooks are available from this extension. So that you can customize this extension to some extent.
- hook_civicrm_rules_event_definition
- hook_civicrm_rules_alter_dataselectors
- hook_civicrm_rules_action_definition
hook_civicrm_rules_event_definition
This hooks returns an array with definitions for events. An event definition could be for example e.g. a post event or a pre event. An event definition is defined in a class which implements the CRM_Rules_Interface_EventDefinition
Below is an example usage of this hook
hook_civicrm_rules_action_definition
This hooks returns an array with definitions for actions. An action could be something like send e-mail or set data value. Every action is an object which implements the CRM_Rules_Interface_ActionDefinition
Below is an example usage of this hook
hook_civicrm_rules_alter_dataselectors
This hook can be used to alter available data selectors within a replacement pattern. This can be useful to add a data selector for total_contribution_amount_this_year at contact level.
Below is an example implementation of this hook.
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
Models
The extension uses the follownig models:
- CRM_Rules_Model_Rule
- CRM_Rules_Model_ReplacementPattern
Model: CRM_Rules_Model_Rule
The CRM_Rules_Model_Rule holds all the data belonging to a rule, which is the event, the conditions and the actions. Also when an action is scheduled to be executed with an offset the replacement patterns should be working in the future. We don't know yet how to achieve this.
4 commentaires
Afficher/Masquer les commentairesOct 01, 2014
Tim Otten dit :
A few thoughts in no particular order:
Oct 01, 2014
Graham Mitchell dit :
Awesome stuff! Can't wait to begin using it. This will revolutionise CiviCRM.
Oct 01, 2014
obowden dit :
This is a bit of a brain dump which I'll think about but wanted to get down in case I forget.
Oct 14, 2014
Jon Goldberg dit :
This looks very cool! I'll note that in your "special conditions" section - two of the conditions are handled by the "Summary Fields" extension, and the last condition ("Has a Birthday") shouldn't be special (date_of_birth IS NOT NULL). So maybe there's no need to build those out right now?