Introduction
This concept provides an overview of how to configure promotion inclusion/exclusion groups and explains some implementation aspects.
In general, a promotion can be applied to orders, to shipping costs, or to a single product. The inclusion/exclusion feature applies to the product item level.
However, there may exist some products which should not be discounted at all. Therefore, an inclusion/exclusion feature has been implemented to define
groups of products which can be discounted and
groups of products which cannot be discounted.
The granularity varies from selecting categories to picking up single products. Selecting a category means that all products belonging to this category, and those belonging to any child category, will be considered.
Inclusion/Exclusion Lists
Application Level Exclusion
There may exist products which cannot be discounted at all. It is inconvenient to define the set of excluded products for each promotion. Therefore, it is possible to define one product exclusion group which is valid for all promotions of an application.
Another way is to define a set of excluded categories. This is a more convenient way to exclude all products of a category instead of adding them to the exclusion list individually.
Setting up application level exclusion groups can be done at <channel> | Applications | <application> on the Promotions tab under Application Level Exclusions.
Application level exclusion groups are valid for all promotions of an application that belongs to a consumer channel.
Promotion Level Inclusion/Exclusion
Product/category inclusion/exclusion groups of a promotion can be defined for conditions, as well as for actions.
Condition:
In general a condition defines if a promotion rule will be applied or not. Therefore an item inclusion/exclusion condition does not (necessarily) define for which products the discount is applied. This must be setup in the Action section (see below).
An item inclusion/exclusion condition requires at least one included category or product. So it's not possible to define only excluded products or categories (the condition is never satisfied in this case).
An item inclusion/exclusion condition is satisfied when at least one of the included products is in the cart (an included product is either explicitly included or via category and neither explicitly excluded nor via category).
This also applies if there are additional excluded products in the cart. So a product exclusion condition cannot prevent a promotion rule being applied.
Action:
In this section it can be defined on which products the discount is granted. This depends on the selection in the back office (see screenshot).
The following options are available:
(1) "all cart items": The discount is granted to every product in the cart, also to excluded products!
(2) "all cart items matching the condition": The discount is granted on all included products defined in the condition.
(3) "all cart items matching the condition but do not count towards the minimum number of included items": Similar to (2) but only useful with an additional sub condition "Minimum Number of Items Defined in Item Inclusions".
(4) "selected items": The products the discount is granted to can be selected manually. The button will open a page where included/excluded products and categories can be selected.
An action item inclusion/exclusion requires at least one included category or product. So it is not possible to define only excluded products or categories (the condition is never satisfied in this case).
An action item inclusion/exclusion is independent from an Item inclusion/exclusion condition. Products and Categories that are included in an Item inclusion/exclusion condition can be excluded in an action item inclusion/exclusion and vice versa.
The promotion discount may be based on the order, an item, the shipping costs or a free gift. Each of these promotion discount types can be configured to trigger a specific promotion action, e.g., an item percentage off discount.
Order
Order Percentage Off
Order Value Off
Item
Item Percentage Off
Item Target Price
Item Value Off
Shipping
Shipping Percentage Off
Shipping Target Price
Shipping Value Off
Free Gift
Automatic Gift
Hidden Gift
If a product is in an inclusion set at promotion level, but also in the application level exclusion set, it will not be considered! To overrule this regulation, the flag Override Application Level Exclusions must be enabled. In general, exclusions win over inclusions.
Per default, application level exclusions are stronger than promotion level definitions. However, each promotion can be configured to overrule the setting.
Implementation
This subsection does not cover all implementation done in detail, but it explains some interesting aspects.
A promotion can have more than one rule. Internally, this is represented by an instance of Rebate. Each rule consists of one or more conditions and one action. Currently, only one action can be configured, but the framework itself allows more than one action.
As mentioned before, each condition and action can have groups of included or excluded products, or categories respectively. Internally, inclusion/exclusion groups are represented by an instance of RebateFilterGroup. It can be one of two types:
PRODUCT: filter group which refers to products
CATEGORY: filter group which refers to categories
The scope is one of this.
NONE: fall back
ACTION: filter group belonging to promotion actions
CONDITION: filter group for promotion condition
APPLICATION: application level filter group
All business logic to access filter groups, to assign them to/unassign them from conditions/actions are provided by RebateFilterGroupRepository.
The items assigned to a rule filter group are referenced by RebateFilterObjectAssignment. It maps the item's id (product or category UUID) to the rule filter group ID.
The RebateFilterGroupAssignment references a rule filter group to a condition or action.
Application Level Exclusions
The application level exclusion is represented by an instance of RebateFilterGroup with scope APPLICATION. If there are neither product nor category exclusions defined, no RebateFilterGroup will exist. If all products or categories are removed from an existing application exclusion group, the instance of RebateFilterGroup will be removed as well.
The RebateFilterGroupRepository provides methods to handle application-wide inclusion/exclusion groups.
Including the Wizard
Enfinity Suite/Intershop offers wizards to select products and categories. These wizards are used for assigning products or categories to inclusion/exclusion groups.
The pipeline ViewPromotionRebateInclusionsExclusions provides call and callback nodes for the product and category wizards at promotion level, and the pipeline ViewApplicationPromotionPreferenceInclusionsExclusions likewise at store level.
There are some important parameters which must be passed to the wizard for proper working.
ParameterName | Description |
|---|---|
PipelineComponentName | Name of the component, not important. |
PipelineComponentCaller | Who calls the component. You can use it e.g. in component templates to place special text. |
PipelineComponentStartPipeline | The start pipeline of the component. |
PipelineComponentReturnPipeline | The callback pipeline of your application. |
PipelineComponentReturnValueName | The callback pipeline of your application will expect the returnValue with this dictionaryKey. |
PipelineComponentCancelPipeline | The callback-pipeline in case of "cancel" button is used (optional). |
PipelineComponentBackToPipeline | A pipeline within your application in case of "back" button at component. |
In addition, all parameters passed to and through the wizard must be stored in a map named PipelineComponentParameters. This map is kept in the session and passed back when returning to the caller pipeline.
Furthermore, each wizard requires some individual parameters:
Name | Description | Starting Pipeline | Parameters |
|---|---|---|---|
ProductSelectWizard | select one or more products | ViewProductSelectWizard-Search | ProductSelectionFinishButton- text of button, if should differ from "Finish" |
CategorySelectWizard | select one or more categories | ViewCategorySelectWizard-PrepareCatalogAssignment | AlreadySelectedCategoryUUIDMap- map of UUID->UUID, lines are marked selected/grey |
CategorySearchWizard | select one or more categories | ViewCategorySearchWizard-Search | AlreadySelectedCategoryUUIDs UUID iterator of categories, which already have been selected before |
Assigning Objects
The central processing of assigning/unassigning items to and from a rule filter group is done in ProcessPromotionRebateInclusionsExclusions-AssignOrUnassignAllObjects. Depending on the number of returned elements, the assignment/unassignment of products/categories to/from the rule filter group may be performed in a batch job.
The threshold is configured in
bc_marketing/staticfiles/share/system/config/cartridges/bc_marketing.properties
# Threshold to perform the product and category assignment to a promotion's rebate filter group in a batch job. intershop.cartridges.bc_marketing.promotion.assignment.threshold = 1000