Interface IPromotionProcessor

Responsible for evaluation if a promotions is valid for a specific IOrderGroup

Namespace: EPiServer.Commerce.Marketing
Assembly: EPiServer.Business.Commerce.dll
Version: 10.8.0
Syntax
public interface IPromotionProcessor
Remarks

Any implementation of this that applies to a PromotionData that has an System.Collections.Generic.IList<T> property must consider and plan for values where the amount might be zero for some or all currencies.

Examples
/// <summary>
/// Sample of a promotion processor for <see cref="PercentagePromotionSample"/>.
/// </summary>
[ServiceConfiguration(Lifecycle = ServiceInstanceScope.Singleton)]
public class PercentagePromotionProcessorSample : EntryPromotionProcessorBase<PercentagePromotionSample>
{
private readonly CollectionTargetEvaluator _targetEvaluator;
private readonly FulfillmentEvaluator _fulfillmentEvaluator;
private readonly LocalizationService _localizationService;

/// <summary>
/// Creates a new instance of a <see cref="PercentagePromotionProcessorSample"/>.
/// </summary>
/// <param name="targetEvaluator">The service that is used to evaluate an order against a promotion's target properties.</param>
/// <param name="fulfillmentEvaluator">The service that is used to evaluate the fulfillment status of the promotion.</param>
/// <param name="localizationService">The service that is used to get localized strings.</param>
/// <param name="redemptionDescriptionFactory">Factory for creating <see cref="RedemptionDescription"/>s.</param>
public PercentagePromotionProcessorSample(
CollectionTargetEvaluator targetEvaluator, 
FulfillmentEvaluator fulfillmentEvaluator,
LocalizationService localizationService,
RedemptionDescriptionFactory redemptionDescriptionFactory)
: base(redemptionDescriptionFactory)
{
_targetEvaluator = targetEvaluator;
_fulfillmentEvaluator = fulfillmentEvaluator;
_localizationService = localizationService;
}

/// <summary>
/// Evaluates a promotion against an order form.
/// </summary>
/// <param name="promotionData">The promotion to evaluate.</param>
/// <param name="context">The promotion processor context.</param>
/// <returns>
/// A <see cref="RewardDescription" /> telling whether the promotion was fulfilled,
/// which items the promotion was applied to and to which discount percentage.
/// </returns>
protected override RewardDescription Evaluate(PercentagePromotionSample promotionData, PromotionProcessorContext context)
{
var lineItems = GetLineItems(context.OrderForm);
var condition = promotionData.Condition;

var applicableCodes = _targetEvaluator.GetApplicableCodes(lineItems, condition.Items, condition.MatchRecursive);

var fulfillmentStatus = _fulfillmentEvaluator.GetStatusForBuyQuantityPromotion(
applicableCodes, 
lineItems,
condition.RequiredQuantity,
condition.PartiallyFulfilledThreshold);

var affectedEntries = context.EntryPrices.ExtractEntries(applicableCodes, condition.RequiredQuantity, promotionData);

return RewardDescription.CreatePercentageReward(
fulfillmentStatus,
GetRedemptions(promotionData, context, applicableCodes),
promotionData,
promotionData.PercentageDiscount,
fulfillmentStatus.GetRewardDescriptionText(_localizationService));
}

/// <summary>
/// Gets the items related to a promotion.   
/// </summary>
/// <param name="promotionData">The promotion data to get items for.</param>
/// <returns>
/// The promotion condition and reward items.
/// </returns>
protected override PromotionItems GetPromotionItems(PercentagePromotionSample promotionData)
{
var specificItems = new CatalogItemSelection(
promotionData.Condition.Items, 
CatalogItemSelectionType.Specific,
promotionData.Condition.MatchRecursive);

return new PromotionItems(promotionData, specificItems, specificItems);
}

/// <summary>
/// Verify that the current promotion can potentially be fulfilled.
/// </summary>
/// <remarks>
/// This method is intended to be a very quick pre-check to avoid doing more expensive operations.
/// In this case that a positive discount percentage has been set, and that the cart is not empty.
/// </remarks>
/// <param name="promotionData">The promotion to evaluate.</param>
/// <param name="context">The context for the promotion processor evaluation.</param>
/// <returns>
/// <c>true</c> if the current promotion can potentially be fulfilled; otherwise, <c>false</c>.
/// </returns>
protected override bool CanBeFulfilled(PercentagePromotionSample promotionData, PromotionProcessorContext context)
{
if (promotionData.PercentageDiscount <= 0)
{
return false;
}

var lineItems = GetLineItems(context.OrderForm);
if (!lineItems.Any())
{
return false;
}

return true;
}
}

Properties

Priority

Gets the priority of this processor. In case there are multiple processors which can handle a promotion, the one with highest priority will be used.

Declaration
int Priority { get; }
Property Value
Type Description
System.Int32

PromotionDataType

The type this processor can handle.

Declaration
Type PromotionDataType { get; }
Property Value
Type Description
System.Type

Methods

Evaluate(PromotionData, PromotionProcessorContext)

Evaluates a promotion. Implementations should use context.OrderForm when evaluating promotions

Declaration
RewardDescription Evaluate(PromotionData promotionData, PromotionProcessorContext context)
Parameters
Type Name Description
PromotionData promotionData

The promotion model.

PromotionProcessorContext context

The context for the promotion processor evaluation.

Returns
Type Description
RewardDescription

The reward for a promotion.

Remarks

Any implementation of this that applies to a PromotionData that has an System.Collections.Generic.IList<T> property must consider and plan for values where the amount might be zero for some or all currencies.

GetPromotionItems(PromotionData)

Gets information about the settings for a specific instance of a promotion type. Used when displaying promotion information to a site visitor/shopper.

Declaration
PromotionItems GetPromotionItems(PromotionData promotionData)
Parameters
Type Name Description
PromotionData promotionData

The promotion data to get items for.

Returns
Type Description
PromotionItems

The promotion condition and reward items.

Remarks

This method is intended to be used on a site to display information about a promotion to a visitor/shopper.

It is never used during the evaluation of the promotion, it only exists to provide information about the settings for this instance of a promotion type. So a use case for this could be that you have a "Buy 3 get the cheapest for one for free" promotion. And you want to display information to the visitor/shopper that "If you buy three items from the category cooking books, you will get the cheapest one for free".

This method should not be called explicitly from the site code. It will be called from the IPromotionEngine extension method GetPromotionItemsForCampaign.