Five New Optimizely Certifications are Here! Validate your expertise and advance your career with our latest certification exams. Click here to find out more
Five New Optimizely Certifications are Here! Validate your expertise and advance your career with our latest certification exams. Click here to find out more
The Episerver Commerce promotion engine is built on the Windows Workflow Rules engine. Episerver Commerce comes with several custom promotions which use this engine. In addition, you can create your own promotions by accessing the promotion engine. This topic explains the main steps for developing and testing customized promotions.
Classes in this topic are available in the following namespaces:
See also Promotions and Creating a Volume Discount Promotion for related information.
Two things that need to be built when creating a new promotion:
For example, you might create an expression (template) for a promotion where:
After this expression (template) is created, a configuration control is created to let users configure promotions from this template in Commerce Manager. Think of the template as a formula with variables which constitute the promotion and the configuration control as the place to set the value of the variables. The promotion engine calculates the discounts applicable to a cart based on the promotions created in Commerce Manager.
Before developing a promotion, consider the following:
Start by developing the configuration control. When completed, the configuration control provides the logic and user interface, which lets users set the variable values for the promotion rules template (expression). In this example, the control is displayed under Purchase Conditions and Rewards in the image.
There is a general pattern for elements in the configuration control:
Example: the Settings class
Settings Class Example
[Serializable]
public class Settings
{
public int MinimumQuantity = 1;
public string ShippingMethodId = string.Empty;
public string RewardType = PromotionRewardType.WholeOrder;
public decimal AmountOff = 0;
public string AmountType = PromotionRewardAmountType.Value;
}
From the Settings class examples, you need the following settings for most promotions. While you do not have to use these variable names, they are used in the built-in promotions and are useful for the first promotions you create.
The Settings class should contain all properties set by the user in the control, and any other settings necessary for your promotion.
Information for promotions is saved in the PromotionDto. The base class makes an instance of the particular promotions data available in the PromotionDto variable. You do not have to retrieve the promotion data explicitly in your control. The PromotionDto contains a table called Promotion. One row in the Promotion table represents the settings for a single promotion.
The SaveChanges method is called by ECF when the user selects the OK button at the bottom of a promotion definition. In the SaveChanges method, an instance of the Settings class, should be populated with the customers settings, for instance settings.MinimumQuantity = decimal.Parse(txtMinimumQuantity.Text);.
Example:populating an instance of Settings
Settings settings = new Settings();
settings.MinQuantity = Decimal.Parse(MinQuantity.Text);
settings.AmountOff = Decimal.Parse(OfferAmount.Text);
settings.RewardType = PromotionRewardType.EachAffectedEntry;
int offerType = Int32.Parse(OfferType.SelectedValue);
settings.AmountType = offerType == 1 ? PromotionRewardAmountType.Percentage : PromotionRewardAmountType.Value;
In the SaveChanges method, the Setting class values should be serialized, using the SerializeSettings method in the base class, then saved in a Dto used to store promotion details.
Example: serializing Settings
PromotionDto.PromotionRow promotion = PromotionDto.Promotion[0];
promotion.Params = SerializeSettings(settings);
You do not have to save the promotion settings explicitly, this is done by Commerce Manager. The promotion row has an OfferAmount and an OfferType properties, which may duplicate to some Setting parameters.
Example: OfferAmount and OfferType properties
promotion.OfferAmount = Decimal.Parse(OfferAmount.Text);
promotion.OfferType = Int32.Parse(OfferType.SelectedValue);
When saving a promotion, the expression also needs to be saved. The variable values which are set in the Settings class are used to customize the template/expression. Then, the customized expression is saved in the ExpressionDto as a row in the Expression table of the DTO. This will make more sense after creating your first expression.
Example: creating and saving the expression
// Create custom expression from template
string expr = base.Replace(base.Config.Expression, settings);
// Create or modify expression
ExpressionDto expressionDto = new ExpressionDto();
ExpressionDto.ExpressionRow expressionRow = base.CreateExpressionRow(ref expressionDto);
expressionRow.Category = ExpressionCategory.CategoryKey.Promotion.ToString();
expressionRow.ExpressionXml = expr;
if (expressionRow.RowState == DataRowState.Detached)
expressionDto.Expression.Rows.Add(expressionRow);
// Save expression
ExpressionManager.SaveExpression(expressionDto);
The base.Config property contains a reference to the configuration file or template you create in the next step. Part of the configuration file is the actual expression, which is the template.
When the control renders in Commerce Manager, during the creation or editing of a promotion, the controls need to be initialized and set to the previously saved values, if applicable.
Example: binding the controls
if (Config != null)
{
txtDescription.Text = Config.Description;
}
if (PromotionDto != null && PromotionDto.Promotion.Count != 0)
{
PromotionDto.PromotionRow row = PromotionDto.Promotion[0];
object settingsObj = DeseralizeSettings(typeof(Settings));
if (settingsObj != null)
{
Settings settings = (Settings)settingsObj;
CategoryXFilter.SelectedNodeCode = settings.CategoryCode;
MinQuantity.Text = settings.MinimumQuantity.ToString();
//select the correct shipping method, if it still exists
if (ddlShippingMethods.Items.FindByValue(settings.ShippingMethodId) != null)
ddlShippingMethods.SelectedValue = settings.ShippingMethodId;
}
txtDiscount.Text = PromotionDto.Promotion[0].OfferAmount.ToString("N2");
ManagementHelper.SelectListItem(ddlDiscountType, PromotionDto.Promotion[0].OfferType);
}
Note the following:
The expression, the template for multiple versions of the same promotion, consists of an XML file with 6 subelements.
Example: an expression (template) with subelements
<Promotion sortorder="300">
<Type>[Unique name with no spaces or special characters]</Type>
<Name>[Name used for display purposes]</Name>
<Description>[Short Description]</Description>
<Group>[this must be one of the following values - shipping, entry, or order]</Group>
<Path>[relative path to the config control from one folder above Configs folder. For example : BuySKUFromCategoryXGetDiscountedShipping/ConfigControl.ascx</Path>
<Expression>[This is most of the config file. It consists of XAML which defines the promotion rules] </Expression>
</Promotion>
Five of six subelements require no further explanation.
Note: All properties are available in the ConfigControl.ascx.cs as a base property, called Config. The expression is a lengthy XAML statement that you do not edit directly. Instead, you use a tool included with ECF, the Expression Editor.
When creating a promotion, you generally want to use an existing promotion and modify its contents for your the promotion. These are the steps to accomplish this:
Before editing the rules, there are a few important things to understand:
Remember that the expression is the template for multiple versions of the same promotion. When assigning variables, you are assigning the promotion-admin-specified parameters.
Example: assigning variables
Name: SetupContants
Priority: 2
Condition: True
Then
this.RuntimeContext["RewardType"] = "$RewardType"
this.RuntimeContext["AmountOff"] = decimal.Parse("$AmountOff", System.Globalization.CultureInfo.InvariantCulture)
this.RuntimeContext["AmountType"] = "$AmountType"
this.RuntimeContext["MinOrderAmount"] = "$MinOrderAmount"
Else
Halt
In the If statement, If true always returns true, which means the Then statement always executes, and the Else never executes. Also note that, for this statement to execute first, all other rules must have a numerically lower priority. The name, while not significant to the rules, can help you understand their purpose.
The $.. values (for instance ..= "$CategoryCode") are the exact names of the parameters saved in your Settings class in the configuration control. When the following line is executed (part of the configuration control directions before), the template is made into a specific promotion:
// Create custom expression from template
string expr = Replace(Config.Expression, settings);
Replace is a base class method which has two parameters: the expression and the Settings class instance for that promotion. The Replace class looks for all instance of the variable names from the Settings instance (with a $ in front of it) in the expression and replaces them with the value from the Settings instance.
All values are set as strings in the expression instance. If a new promotion is created with the above variables, you should have a Settings class definition that looks something like the example below.
Example: Setting class definition
[Serializable]
public class Settings
{
public string RewardType = PromotionRewardType.WholeOrder;
public decimal AmountOff = 0;
public string AmountType = PromotionRewardAmountType.Percentage;
public decimal MinOrderAmount = decimal.MaxValue;
}
This means there is a one-to-one match between the variables in the Settings class and the variables you set in this first rule. If you create an instance of this promotion where the AmountOff is 5, the MinOrderAmount is 100, and the RewardType and AmountType are left as is, the Replace function creates an expression instance that looks like the following example.
Example: promotion expression instance
Priority: 2
Condition: True
Then
this.RuntimeContext["RewardType"] = WholeOrder"
this.RuntimeContext["AmountOff"] = decimal.Parse(5", System.Globalization.CultureInfo.InvariantCulture)
this.RuntimeContext["AmountType"] = "percentage"
this.RuntimeContext["MinOrderAmount"] = "100"
Else
Halt
The string instance created by the Replace method represents a specific version of this promotion. This value is saved in the database and used during promotion calculations. If you want to see this in action, retrieve the value of the Expression field in the Promotion database table for a particular promotion and load it into the Expression Editor.
It is possible to test whether the order meets the conditions of the promotion.
Example: testing the promotion conditions
Name: CheckOrderSubTotal
Priority: 1
Condition
this.PromotionContext.PromotionResult.RunningTotal < decimal.Parse((string)this.RuntimeContext["MinOrderAmount"], System.Globalization.CultureInfo.InvariantCulture)
Then
Halt
Else
Note: The Priority is a lower number, meaning it executes after the SetupConstants rule. The condition is a test to see whether the current RunningTotal property of the PromotionResult object is less than the minimum order specified. The RunningTotal property gives the orders Subtotal, after all previous promotions (if applicable) are applied. The order of promotions applied to orders is specified in the Commerce Manager promotion definition screen ( property). This rule in effect says If the order subtotal is less than the specified minimum order amount, halt the promotion evaluation as it does not apply. The end result is that no discount will be returned by the promotion engine in that case. If, however, the condition is false, meaning the subtotal is equal to or greater than the minimum order amount, there is an empty Else statement. As a result, nothing is done and the next rule is executed.
This is the step where, if the rules have executed to this point, a promotion result needs to be returned. This is a PromotionItemRecord object. The parameter for the AddPromotionItemRecord most commonly used is a new PromotionItemRecord.
The constructor values for a new PromotionItemRecord are:
From the AddPromotionItemRecord returned PromotionItemRecord, the PromotionItem is assigned to the PromotionContext.CurrentPromotion, thus passing the promotion information back to the portion of the code that called the rules engine (StoreHelper.cs or CalculateDiscountActivity.cs) to be added to the cart.
Note: The [reduced] syntax PromotionItem = this.PromotionContext.CurrentPromotion is not quite intuitive. This statement is doing two things: adding a PromotionItemRecord to the current context, and setting the PromotionItem associated with that PromotionItemRecord to the current promotion. That PromotionItem contains the properties of the promotion from the database. Finally, the ValidationResult.IsValid = True statement indicates that the result is valid and should be applied.
Example: AssignReward
Name: AssignReward
Priority: 0
Condition
True
Then
this.AddPromotionItemRecord(new Mediachase.Commerce.Marketing.Objects.PromotionItemRecord(this.PromotionContext.TargetEntriesSet,
this.PromotionContext.TargetEntriesSet, new Mediachase.Commerce.Marketing.Objects.PromotionReward((string)this.RuntimeContext["RewardType"],
(decimal)this.RuntimeContext["AmountOff"], (string)this.RuntimeContext["AmountType"]))).PromotionItem = this.PromotionContext.CurrentPromotion
this.ValidationResult.IsValid = True
Else
Halt
In this case, the PromotionContext.SourceEntriesSet.MakeCopy() method is called. The SourceEntriesSet and TargetEntries set properties are both PromotionEntriesSet types, which represent a collection of entries. When working with entry promotions, the SourceEntriesSet consists of all of the entries associated with the lineItems in an OrderForm.
The TargetEntries consists of one lineitem at a time, with the promotions tested against one LineItem entry at a time. With order promotions, the SourceEntriesSet consists of all of the LineItem entries associated with an OrderForm. With shipment promotions, the TargetEntries consist of all of the LineItem entries associated with a single shipment.
When you call the SourceEntriesSet.MakeCopy() method, it returns the subset of entries specified by the $EntryYFilter parameter. The $EntryYFilter variable is simply a delimited list of entry codes. You can use any special character (#,$& and so on) to delimit the list of entries. See the ConfigControl for BuyXGetNofYatReducedPrice for an example of how to build this variable string.
Example: SetupConstants expression for the buy x, get y free promotion
Priority: 1
Condition: True
Then
this.RuntimeContext["EntryXSet"] = this.PromotionContext.SourceEntriesSet.MakeCopy(new string[] {"$EntryXFilter"})
this.RuntimeContext["EntryYSet"] = this.PromotionContext.TargetEntriesSet.MakeCopy(new string[] { "$EntryYFilter"})
Else
Halt
This example uses a method of the RulesContext object, GetCollectionSum. In this case, we are using it to find the total quantity of SKUs from the SourceEntriesSet where the CatalogNodeCode property of the entries is equal to the category code associated with the promotion. If its equal to or greater than the variable minimum quantity, the promotion applies.
The third parameter of the GetCollectionSum allows you to pass in a code expression to use as a filter. The code expression is passed in as a string and turned into a System.CodeDom.CodeExpression. The Windows Workflow Rules engine can then use that expression to filter the IEnumerable Entries collection.
The RulesContext offers a number of methods to allow you to do more efficient evaluations of the cart for promotion condition checks like this using CodeExpressions to filter, validate, or count qualities of the cart.
Example: Promotion condition test
Name: CheckConditionsMet
Priority: 2
Condition
this.GetCollectionSum(this.PromotionContext.SourceEntriesSet.Entries, "Quantity", "this.CatalogNodeCode.ToString().Equals('" + this.RuntimeContext["CategoryCode"].ToString() + "')") < decimal.Parse(this.RuntimeContext["MinQuantity"].ToString()) || this.PromotionCurrentShipment.ShippingMethodId.ToString() != this.RuntimeContext["ShippingMethodId"].ToString()
Then
Halt
Else
There are numerous other promotion examples included in the ECF source code. Review these to better understand other custom promotion options. Another way to get ideas about how to implement your promotion can be found by creating promotions using the Build Your Own Discount option available for entry and order promotions. Create a promotion which includes criteria or rewards similar to your design and then review the expression from the Expression database table in the Expression Editor - it will often provide vital clues for how to complete your promotion.
After you create your promotion and test it with you environment, the following tips can help you expedite your debugging:
Last updated: Oct 12, 2015