[module] Rules

Compatibility:

0
Project page quote (external)
Project page quoted on: 
2014-03-17

Posted by fago on November 7, 2007 at 1:34pm

The Rules module allows site administrators to define conditionally executed actions based on occurring events (known as reactive or ECA rules). It's a replacement with more features for the trigger module in core and the successor of the Drupal 5 workflow-ng module.

Example use cases

- Build flexible content publishing workflows changes

- Send customized mails to notify your users about important

- Create custom redirections, system messages, breadcrumbs, ...

- Build an eCommerce store using Drupal Commerce

And many more...

Features

- Obviously, you may use reaction rules to react upon any event with custom conditions and actions.

- Allows functionality to be re-used via components (Drupal 6: Rule sets only).

- Flexible scheduling system that allows scheduling any component / action.

- Users can share their customizations by using the built-in import/export feature. For that the module also integrates with Features.

- Modular input evaluation system - for example you can install the Token module and use it in every action.

- The module has been developed with site performance in mind, so it makes use of caching routines to speed up rule evaluation.

- Rules 2.x (Drupal 7 only) features improved APIs, a new admin UI, support for all entity types, parameter configuration via simple data selection (i.e. just pass node:author as argument) and much more. See this blog post for more details.

Integrations

Modules may use the Rules module's API to provide new events, conditions, actions or default rules, which can be customized by users. Some notable ones are:

- Rules Link - Provides clickable links on entities and views that trigger Rules execution

- Rules list conditions - Allows checking condition(s) on list items, evaluating to TRUE if either "any" or "all" items match the condition(s)

- Views Rules - Provides Views directly as Rules actions and loops to seamlessly use view result data

- Rules Forms - Provides a Rules based method for controlling forms and their elements

- Conditional Rules - Provides inline conditional branching in Rules configuration with statements: If/Else, Switch/Case, While

To make your own integration, check out the developer docs. See also issues tagged rules-integration and a manually updated list of modules supporting Rules.

Depends on modules [Drupal7]
Required by modules [Drupal7[

Qs and As

Q: I am developing a simple Drupal7 community web site for sharing my favourite recipes; do I need Rules ?
A: Probably not.


Q: I am professional Drupal7 developer/consultant; do I need to understand Rules and how to create new Event-Condition-Action (ECA) instances via the Rules interface and Rules elements using the Rules API in code ?
A: Definitely.


Q: I am developing a Drupal7 site using Drupal Commerce; do I need to understand Rules and how to create new Event-Condition-Action (ECA) instances via the Rules interface ?
A: Definitely.


Q: I am developing a Drupal7 site using Drupal Commerce; do I need to understand how to create new Rules elements using the Rules API in code ?
A: Maybe. Depends how complex your purchasing and checkout workflow flow, and whether you need to create a new payment integration using the Commerce Payment API.


Q: Does Ubercart also use Rules ?
A: Yes, Ubercart 3.0 does have Rules integration (but it is not so deeply reliant on Rules as Commerce). You no longer need the additional UC Rules module, which is only for Drupal6.


Q: Will Rules eventually replace the core Trigger module and core actions for system events ? Will Rules (over)rule ?
A: Not as far as I can tell. There are some external links below discussing the difference between Trigger and Rules. But clearly Rules is far more comprehensive, covers more cases, and is the integration target of (increasingly) more modules.

An increasing number of modules either depend on Rules explicitly (for better or worse) or offer optional integrations with it.

Why 'for better or worse' ? Because although Rules has a lot of power - and is definitely easier than PHP code for those who are not coders - having lots of Rules can sometimes make it hard to tell what is happening where (compared with code), especially if some of a site's logic is handle by Rules and some of a site's logic is handled by non-rules custom PHP code, and because Rules can sometimes be hard to diagnose and debug. Sometimes one has to trawl through Action after Action to see exactly what is done where (although good Action descriptions can help reduce that problem).

If you are absolutely new to Rules, it's hard to go past The Tiny Book or Rules (PDF) primer by Johan Falk and Wolfgang Ziegler.

If you are new to Rules, and you are going to begin playing with it, I highly recommend you enable these diagnostic settings under Configuration > Workflow > Rules > Settings (/admin/config/workflow/rules/settings):

Debugging
[x] Log debug information to the system log

Show debug information

[ ] Never
[ ] In case of errors
[x] Always
Debug information is only shown when rules are evaluated and is visible for users having the permission Access the Rules debug log

Then enable the Access the Rules debug log permissions for desired roles.

Another tip from The Tiny Book or Rules is:

If variables are not behaving as you expect, you will find the Rules action Debug value useful (provided by the Devel module). It prints out a krumo dump of a variable that you choose, making it available for inspection.

The available Rules elements (actions, events, conditions, components) are not enough. Can I code my own in PHP ?

Sure. If you want to get your hands dirty with PHP rule extensions you'll need to carefully examine the hooks (lots of them) in the Rules API, and examine the Rules example module. For example, to define a new rule-compatible action you'll need hook_rules_action_info(). The Tiny Book or Rules has a nice mini example of a coded Condition, Action, and an Event, how to invoke rules Components programmatically (by using rules_invoke_component()), how to extend and alter data types, and how to provide new entities and datatypes.

Modules can also create Default rules using hook_default_rules_configuration():

roviding default rules may serve as a simple way for modules to provide some default functionality, which users may override. Also it's useful for versioning rule configurations in code using the usual version control system or to build feature-like modules.

Exporting/importing Rules

You can export rules in entity_export/import JSON format as explained here under Managing your exported rules in code:

You can also export every rule individually into its own file and check these in to git. (This makes changes to individual rules easier to see and manage). The files can be placed into a /rules/ folder inside your custom module, and each one can end in a .rule extension.

Then, you can place a single function inside the file mymodule.rules_defaults.inc in mymodule. In that function you can loop through all the files, and import each rule.

You can also export rules configurations with Features (and Strongarm). There's a screencast by Johan Falk Importing and exporting rules demonstrating it. It basically works by writing as part of the feature a .rules_default.inc file with a __feature_default_rules_configuration() function that uses entity_import('rules_config', JSON_rules_stuff).

Finally, if you have an exported rules JSON snippet, you can enter it directly using the Import rule button (for reaction rules) or the Import component button, which is also demonstrated at the end of the above screencast:

/admin/config/workflow/rules/reaction/import
/admin/config/workflow/rules/components/import

Where the JSON rules snippet can be obtained from the export link at the right of each reaction rule or rule component in the lists of reaction rules or rule components:

/admin/config/workflow/rules/reaction/manage/[rule_id]/export
/admin/config/workflow/rules/components/manage/[component_id]/export

This also gives you a simple way to move rules between stages.

However, the compelling advantage of using one of the file-based approaches (such as Features-based rules export), is that it can be combined with Git code repository management. It also means you have a robust record of the rule's JSON snippet (not just a copy in a clipboard).
Visit also