Managing Rules

Rules govern responsive site behaviors based upon site visitor types or visitation patterns. After creating a new Rule, Conditions, and Actions can be added to a Rule. Conditions are basically trigger criteria that for a responsive site behavior or “action(s)” that will be taken if visitor type or pattern is detected. If the Rule Condition(s) are met, the Rule Actions fire, allowing the Site/Page behavior to change and customize content delivery to each visitor type/pattern.

This document details how Rules can be created, edited, and managed.

The following screenshot shows the variety of the configurable options available when defining Rules:

Add a Rule

To add a new Rule, click on the +Add Rule button on the top right side of the Rules view. When a new Rule is added, it will appear at the top of the list of Rules by default. After adding a new Rule, the Rule Name, Fire On, and On/Off, Delete, and Add Condition controls are displayed in the grey Rule bar - as shown in the image below.

Viewing Rules

By default, the Rules page displays all Rules in a contracted view. To expand the Rule and see Rule Conditions or Rule Actions, click the arrow to the left of the Rule name.

Clicking on the arrow to the left of the Rule expands the view and displays all the details of a specific Rule, including all Conditions and Actions that determine Rule behavior. After clicking on the arrow to the left of a specific Rule name, Conditions and Actions can be seen and edited.

Searching and Filtering

Rules can be searched by Name using the search box above the Rules list. When you type anything into the Search box, the display is filtered so that Rules are only displayed if some part of the Rule title matches the text typed into the Search box.

Rules can also be filtered to show only Active Rules, only Inactive Rules, or All Rules (default) by clicking the appropriate filter in the Show filters under the Search box at the top of the Rules list.

• Active: Displays only Rules that are currently activated or “On“.
• Inactive: Display only Rules that are currently de-activated or “Off“.
• All (default): Displays all Rules.

Edit a Rule

Listed below are the ways a Rule and/or Rule properties can be edited:

*When adding/editing Conditions or Actions automatically de-activates the Rule and sets the Rule to “Off” in the UI. After adding/editing Rule Conditions/Actions, remember to re-activate the Rule by toggling the activation button back to “On“.

Activate or De-activate a Rule

If a Rule is activate (On), dotCMS will evaluate each Condition and apply Actions if the Condition(s) evaluation results are TRUE. Rules can be de-activated (OFF), to suspend Rule-set Actions. Rules can be activated/de-activated using the On/Off button.

Delete a Rule

Rules can be deleted by clicking on the trash can icon to the right of the rule.

Note: If the Rule has no dependent Actions or Conditions, it will be deleted without a warning.

If a warning dialogue box is displayed, you must confirm the Delete to remove the Rule.

Adding Conditions and Actions to a Rule

To add a new Condition to a Rule, click on the + at the right of the grey Rule bar. To add complementing Conditions or a “Condition Group”, click the + to the right of a Condition, and then set the AND/OR property to the left of the new Condition. To add a Rule Action, choose an appropriate action from the select box to the left of the Green Actions section at the bottom of a Rule. Additional Actions can be added by clicking on the green + to the right of the last Action listed.

For more information, see the Actions and Conditions documentation.

Troubleshooting and Error Handling

If your rules are not performing as expected, you may find the following methods helpful to help identify and resolve the problem.

Debug Logging

If your rules are not performing as expected, you can activate debug logging for Rules to help identify and resolve any problems or unexpected behavior. To activate debug logging for Rules, add the following to the Loggers section of the log4j2.xml file:

<Logger name="com.dotmarketing.portlets.rules" level="debug" additivity="false">
    <AppenderRef ref="generic"/>
</Logger>

Performance Logging

You may also configure your system to automatically log any Rules which execute slowly. For more information, please see the Slow Rule Logging section of the Special Logging Configurations documentation.

Error Handling for Custom Conditions or Actions

You may create Custom Rule Conditions and Rule Actions via OSGI plugins. However, customizations to Rule Actions or Conditions that are not implemented properly may cause the Rules that utilize them to break. If this occurs, the Rules will stop displaying the broken Rule(s), but will continue to display Rules that are functional and do not implement the broken custom action(s)/condition(s).

If an expected Rule does not appear in the Rules list, examine the dotcms.log under System→Maintenance→Log Files. The dotcms.log should display error messaging which helps locate the broken customization. In the example error messages below, a custom OSGI actionlet (being used by a rule), was removed:

~ERROR rules.RuleTransform: Actionlet not found: SendRedirectActionlet
~WARN exception.InternalServerException: {"error":"dotcms.api.error.internal_server_error: Could not create ReST Rule from Server, Rule id '7ba80564-0a33-4c44-9314-3d17b85800cb'"}
com.dotcms.rest.exception.InternalServerException: HTTP 400 Bad Request