Promotion Background
Promotions are applied to individual SKUS as well as Carts. The PublicLayer/WebUtility/Helpers/StoreHelper.cs class (Mediachase.Commerce.Website.Helpers namespace) provides a convenient means to determine the discounted price for a SKU using the GetDiscountPrice() method. This will calculate promotions that are specific to an individual SKU (e.g. buy SKU x, get $y off), if any exist. This method simply returns the discounted price for that SKU. It doesn’t include quantity-based promotions for the SKU (e.g. buy 3 SKU x’s and get %20 off the SKU price) and doesn’t include order-wide promotion discounts (e.g. if your cart subtotal (before taxes and shipping) is over $100, shipping is free). The StoreHelper calls the promotion engine to calculate the price for a SKU by calling PromotionHelper.Eval().
Promotions are also applied to a whole cart during checkout. This occurs in the CalculateDiscountActivity.cs in the BusinessLayer/OrderSystem/ActivityLibrary project (Mediachase.Commerce.Workflow.Activities.Cart namespace). This activity is included in two workflows: CartValidateWorkflow and CartPrepareWorkflow. The CartValidateWorkflow is designed to calculate the subtotal for a cart, including promotions; the subtotal doesn’t include calculating taxes and shipping charges. The CartPrepareWorkflow is designed to calculate the final state of a cart before the customer confirms the order purchase, including taxes and shipping charges. Discounts are set in the cart by setting discount properties and calculating the cart total with deductions for the discounts. The discount properties include :
- LineItem.LineItemDiscountAmount (total decimal amount of all promotions applicable to that LineItem)
- LineItem.LineItemDiscounts (which store a collection of promotions, including names of each promotiona and the amount)
- LineItem.OrderLevelDiscountAmount (amount of discount applicable from the order. This is applies when the Promotion RewardType is for the whole order and the promotion group is not shipping)
- LineItem.OrderLevelDiscounts (same as LineItemDiscountAmount except for promotion discounts applicable on the order level to an individual LineItem)
- Shipment.ShippingDiscountAmount (same as LineItemDiscountAmount except for promotion discounts applicable to a Shipment)
- Shipment.Discounts (same as LineItemDiscounts except for shipments)
- OrderForm.DiscountAmount (same as LineItemDiscountAmount except for promotion discounts applicable to the order as a whole (e.g. $50 off an order when certain conditions are met))
- OrderForm.Discounts (same as LineItemDiscounts except for the entire order)
The CalculateDiscountActivity performs the discount calculations in the CalculateDiscounts() method.
After the CalculateDiscountActivity activity is run, the CalculateTotalsActivity calculates the totals for each lineitem, orderform, and shipment. It performs these calculations to apply discounts:
- The LineItem.ExtendedPrice is calculated by multiplying the ListPrice for a SKU by the quantity being purchased and then subtracting the LineItemDiscountAmount and OrderLevelDiscountAmount.
- The OrderForm.SubTotal is the sum of the SKUs price (in this case PlacedPrice times the Quantity minus the LineItemDiscountAmount).
- The OrderForm.Total is the sum of the subtotal, shipping charges, taxes, minus the shipping discounts and LineItem order level discounts.
Promotion Rules Engine
ECF includes a Promotion Rules Engine designed to provide a flexible and fast framework to create different types of promotions that will be displayed on the front-end.
The Promotion Engine has two distinct use cases:
- Design mode: To configure promotions
- Runtime mode: To display and apply promotions
Design Mode
Promotions are created either using the graphical user interface in the administration console or by a developer. Most of the promotions can be created by using "Custom Promotion" type, which you can select when creating new promotion. In some cases when promotions are somewhat unique, developer will need to create custom expressions and user interfaces (please refer to the tutorial section for that).
There are 3 groups of promotions which determine in which scenario they are executed. Those are:
- CatalogEntry - executed against individual entry and can be applied to the items in the catalog and shown during search, catalog browsing
- Order - executed against the whole order and will only display on the shopping cart / order pages
- Shipping - executed against individual shipments and will be shown only on the order/checkout pages
Expressions
Expressions is a core technology behind Marketing system. It allows for a very flexible and standards based way to extend different aspects of the system. Promotions, Customer Segments and Policies all rely on expressions.
When designing new Marketing we needed a way to provide a more flexible rules based extension mechanism. These rules had to be external and not built into the framework itself, since they will be changed often. It also had to have high performance and ability to process hundreds of rules for each customer accessing the site.
Architecture
The Architecture of Expression Manager is similar to the Provider model used in .NET Framework. The engine relies on external class to process the expression which can be specified in the configuration file. That class simply needs to implement IExpressionValidator interface and the actual implementation is up to that class.
With ECF we provide one of the implementation that relies on Windows for Workflow Foundation Rules Engine, so if you pick that you can use our Expression Editor to create expressions. The Expression Editor is located in the following path of your solution:
BusinessLayer\MarketingSystem\ExpressionEditor
You can find more details on how rules engine works here Introduction to the Windows Workflow Foundation Rules Engine.
Runtime Mode
Execution Sequence
There are two distinct ways the promotions are applied to the product: during browsing or searching of catalog and when viewing shopping cart or checking out.
They both rely on "MarketingContext.EvaluatePromotions" method which cycles through each promotion prioritising and filtering them. The sequence for EvaluatePromotion goes like this:
- Checks global exclusivity (if global promotion has been applied, it stops executing)
- Checks target group
- Checks group exclusivity
- Checks limits (apply only 1 time)
- Checks dates and status
- Verifies coupon
- Performs basic catalog/node/entry filtering (not currently used in demo)
- Checks conditions (expressions)
- Checks policies
- Commits all new records (promotions added)
Browsing Catalog
During catalog browsing you would typically use relatively simple promotions that just apply to the individual products.
Execution Sequence
- StoreHelper.GetDiscountPrice(Entry entry, string catalogName)
- PromotionHelper.Eval(PromotionFilter filter)
- MarketingContext.Current.EvaluatePromotions(true, this.PromotionContext, filter)
Step 1
During step 1 we get the sale price (which will be used to calculate the base price for which discounts if any will be added) using the following call:
Note: we pass Minimum Quantity when browsing the item in the catalog, which will typically default to 1
Next we need to setup the PromotionContext, which will provide context for our rules to execute against. Since it is just one product in this case all we need to do is Create new PromotionEntry object (which represent one product for our marketing system) and populate it with all the attributes (meta fields from the catalog entry) that might be used during promotion evaluation. Some other key concept during this stage are:
- MarketingContext - this is where we add extra objects that can be used by the expression engine
- TargetGroup - we set it to the entry, since this is the only promotion group we should be executing when browsing catalogs
- IPromotionEntryPopulate - this is an interface that allows developer to override how the properties are copied from Entry object to the PromotionEntry object, this is configured in ecf.marketing.config file using PromotionEntryPopulateFunctionType config section (set to "Mediachase.Commerce.Marketing.Validators.PromotionEntryPopulate,Mediachase.Commerce.Marketing.Validators" by default)
And at last we call the eval method and return the discounted price back.
Step 2
During step 2 we simply execute the promotion engine with all the information collected during step 1:
Step 3
Goes through each promotion, checks the policies, customer segments, dates and validates the expressions.
When promotion is successfully applied, it is typically added to the PromotionResult object as a PromotionItemRecord object which contains information about the items affected and the discount applied.
Cart/Checkout
During checkout more complex promotions can be used. In this case you are working in the context of the order system. You will no longer calculate discount directly, but through the use of workflow activities.
Execution Sequence
- CartHelper.RunWorkflow("CartValidate")
- CalculateDiscountsActivity.CalculateDiscounts
Step 1
This is a step where you initiate the workflow. The workflow (typically) will check if entries exist and available, remove all the existing discounts and then execute the CalculateDiscountsActivity. This will be done during each step in the checkout process or when accessing the shopping cart.
Step 2
The logic of discounts activity is very similar to the one used during browsing with exception of two additional discount groups: Order and Shipment. The engine first calculates line item discounts, then order and then shipments.
The code below calculates discount for each individual order form:
Note: Just like in previous step the CalculateDiscountsActivity relies on IPromotionEntryPopulate interface to populate properties for each item. This means that there is only one place for you to customize the logic related to populating custom properties and it can be completely replaced without any changes to the core logic.
Coupon Codes (Reservations and Expiration)
Coming soon.