Document Properties
Kbid
2806H2
Last Modified
07-Aug-2023
Added to KB
11-Nov-2016
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
  • ICM 7.10
  • ICM 11
Concept - Promotion Inclusions and Exclusions

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).
default=PipelineComponentReturnPipeline

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"
ProductSelectAllButton- text of button to select all products of the list, default=noButton
AlreadySelectedProductUUIDs- these lines are marked selected and grey
NotSelectableProductUUIDs- these lines are unmarked and grey
SelectionType - "Single" .. only 1 product can be selected (default="Multiple")

CategorySelectWizard

select one or more categories

ViewCategorySelectWizard-PrepareCatalogAssignment

AlreadySelectedCategoryUUIDMap- map of UUID->UUID, lines are marked selected/grey
NotSelectableCategoryUUIDMap- map of UUID->UUID, lines are grey
SelectCatalogStepNo- step number for selecting catalog
SelectCategoryStepNo- step number for selecting category

CategorySearchWizard

select one or more categories

ViewCategorySearchWizard-Search

AlreadySelectedCategoryUUIDs UUID iterator of categories, which already have been selected before
CategorySelectionFinishButton- variable name of first finish button, e.g. "Add Selected", returns only the selected element to the caller
CategorySelectAllButton- variable name of second finish button, e.g. "Add All", returns all elements to the caller
SelectedMenuItem- name of the menu item to be highlighted


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


Disclaimer
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.