The promotion rule engine is built on JBoss Rules (formerly Drools Rules). JBoss Rules is a third-party rules engine that uses a fast algorithm to evaluate rule conditions and execute their actions. The input to the JBoss Rules engine is a set of objects used in the condition evaluation and action execution as well as the set of rules, which we express as text in the proprietary Drools language.

The representation of a rule in Elastic Path is an object model of the components of a rule such as conditions, actions, and parameters used by various rule elements. The object model is persisted in the database directly with one table corresponding to one class in the rule object model. This allows the graph of rule objects to be easily stored, retrieved and modified, and stored again. The objects in the rule object model are responsible for generating Drools language code that is passed to JBoss Rules. The generated code is not persisted and it is not possible to re-create the object model representation of a rule given the Drools code.

JBoss rules supports basic evaluation of objects' properties within the engine itself. However, more complex operations are not supported. In Elastic Path, nearly all conditions are evaluated in Java and the actions are also executed in Java. This allows the condition and action code to be easily debugged and unit tested. The PromotionRuleDelegate is the class that is responsible for computing conditions and executing actions as required by JBoss Rules.

A promotion is a rule. A rule consists of rule elements. There are two types of rule elements:

• Condition: Describes the set of conditions that must be true for the action to be executed. Conditions are optional. If no condition is specified, then the action will execute whenever the customer is eligible. When multiple conditions are specified, the user can again choose whether all or any of them must be satisfied.
• Action: Describes the action that will be taken if the the customer is eligible and all conditions are met. If multiple actions are present, all actions will be executed when the conditions are met.
  Note:

  Before Elastic Path 6.2.1, there was a third type of rule element: eligibility. This was replaced by the shopper segment, which is determined by evaluating information stored in the shopper's tag set. The PROMOTIONS_SHOPPER tag dictionary represents tags that relate to shoppers. For more information on customer segmentation and the tagging framework, see the tagging framework section.

The Commerce Manager promotion editor allows the user to compose rules from rule elements and then save those rules in the database. The system then retrieves the rules from the database as object graphs, requests the corresponding Drools code from the rule objects, and passes the rule code to the JBoss Rules engine. JBoss Rules will then determine which rules' actions should be executed on the Java objects that are passed to it.

Using the promotion rule editor in the Commerce Manager, users mix and match promotion rule elements to create rules. Therefore, all rule elements are independent of each other. It is not possible for an action to use information determined by a condition.

There are two types of promotions:

• Catalog promotions: These promotions are applied when looking up product prices, for example, while the shopper is browsing the product catalog or viewing product details. This promotion type supports relatively simple rules, such as x% off a product or category.
  Warning:

  All catalog promotions are applied simultaneously. The conditions are checked at the same time and then discounts are applied. In cases where multiple discounts apply to the same item, the lowest discounted price always wins.

• Shopping cart promotions: These promotions are only applied when the shopper is viewing items in their shopping cart. This promotion type supports more complex rules, usually requiring awareness of the combinations of items in the cart.
  Warning:

  Cart promotions are applied in two steps. Promotions with shipping and cart item discounts are applied first. Then, promotions with cart subtotal discounts are applied. This ensures that shipping and cart item discounts are applied before any cart subtotal discounts are calculated.

The key classes that represent rules in the domain model are:

• RuleSet - A set of rules valid for each promotion type.
• Rule - A promotion. Each rule contains a collection of rule elements (conditions and actions).
• Condition - A condition that must be true for a promotion to be available.
• Action - The action to perform if a rule's conditions are met.
• RuleParameter - Actions and conditions typically require parameters held by a RuleParameter object

These domain objects generate the Drools code that is executed by the rule engine. The rule domain objects are also responsible for self validation. The validation and code generation is invoked by clients at the top level (Rule Set) and propagated down to the child objects.

Other key classes include:

• EpRuleEngine - Retrieves rules from persistent storage, compiles them into Drools language, and evaluates them against domain objects when requested by clients.
• PromotionRuleDelegateImpl - Evaluates rule conditions and executes rule actions.

The rules objects generate Drools code such as the example below:

//Objects used in the evaluation or action must be imported
import com.elasticpath.domain.rules.PromotionRuleExceptions;
import com.elasticpath.domain.shoppingcart.CartItem;
import com.elasticpath.domain.catalog.ProductSku;
import com.elasticpath.domain.shoppingcart.ShoppingCart;
import com.elasticpath.domain.rules.PromotionRuleDelegate;
import com.elasticpath.domain.catalog.Product;

//Each rule must have a name, defined here
rule "First Time Buyer"

  //Salience determines the order of evaluation,
  // higher salience means higher priority
 salience -1

  //Agenda groups are evaluated and executed together
 agenda-group "SubtotalDependent"

    //Start of the "Conditions" Block
    when

         //Declare objects used in the rule
         delegate: PromotionRuleDelegate ( )
         cart: ShoppingCart ( )
         eval ( delegate.checkDateRange("0","0") )

         //Ask the delegate to evaluate whether conditions are true
         eval ( delegate.isFirstTimeBuyer(cart) )


    //The "then" block defines what will happen when the conditions in
    //the "when" block are all true
    then

         //Ask the delegate to execute an action
         delegate.applyOrderDiscountAmount(cart, 4489216, "75");
end

Rules are composed of rule elements, which can be conditions or actions. To add a new rule element:

1. Add the implementation to the com.elasticpath.domain.rules.impl package and extend from an appropriate base class. If you are creating an action, extend AbstractRuleActionImpl, otherwise extend AbstractRuleElementImpl.
2. Add a JUnit test case for the element, which should extend AbstractTestRuleElementImpl.
3. Add a method in PromotionRuleDelegateImpl (and its interface) that will execute the action or condition of your rule element.
4. Unit test this delegate method in PromotionRuleDelegateImplTest.
5. Add the rule element bean name to ContextIdNames and also to the bean definitions in PrototypeBeanFactory.
6. Add the rule element to the appropriate category in the rule service bean definition in service.xml.
7. Integration test a rule containing the new rule element by firing it through the harness set up in EpRuleEngineImplTest.
8. Add an entry in the RuleElementType enum for the new rule element.
9. If adding a new rule parameter type, you will need to modify the Java code for the Commerce Manager client rule editor. The files you may need to change include:
   1. NewPromotionWizardRulesPage - UI for adding a new rule
   2. PromotionRulesDefinitionPart - UI for editing a rule
   3. PromotionRulesWidgetUtil - utility methods for creating UI elements and performing rule element parameter data binding
   4. PromotionsMessages - defines localized text for the rule element
   5. PromotionsResources.properties - localized text for the rule element

Rules are extensively tested by JUnit at several levels. The following kinds of JUnit tests are most frequently added or extended when extending the rules system:

• Rule Element Tests. Each RuleElement should have a unit test. Tests for conditions should extend AbstractTestRuleElementImpl. Tests for actions should extend AbstractRuleElementImplTest.
• PromotionRuleDelegateImplTest. Add test cases to this class to test the execution of rule actions by the PromotionRuleDelegateImpl. Tests should also be added for each condition and eligibility decision that is delegated to the PromotionRuleDelegate.
• EpRuleEngineImplTest. This test suite is used to test the highest level of integration in the core rules system and actually runs the JBoss Rules engine to test that it executes generated rule code. When testing a new rule, add the rule element to the rule set in createShoppingCartRuleSet or createCatalogRuleSet depending on the scenario in which the rule element is valid. The rule delegate method that should be invoked by the rule engine must then be mocked in testFireShoppingCartRules() or testFireCatalogRules().

Once the rule system has successfully executed the unit tests, rules can be tested in the Commerce Manager client and Cortex Studio. For information on setting up the system for easier rule testing, see the Configuration section.

To assist with troubleshooting rules engine failures, the Drools code generated by the rules domain objects can be logged in the log or console.

The set of rules to be passed to JBoss Rules is loaded at start time and cached by the EpRuleEngineImpl. EpRuleEngine.compileRuleBase() is invoked periodically by a Quartz scheduled job to reload rules from the database.

• The promotion rulebase can be configured to rebuild periodically. Scheduling and configuration can be found under the search server's Scheduled Jobs (Search Server). This means that rules will be reloaded from the database and compiled into the input format for JBoss Rules. This rule compilation operation is expensive and should not be performed more frequently than every 5-10 seconds.
• For rules to take effect immediately after rulebase compilation, it is necessary to disable caching (Both the second-level cache and the product retrieval strategy defined in service.xml). This is useful for testing but disabling caching is not recommended for production environments.