Skip to main content

Dynamic Promotion

Overview​

In Out-of-the-Box Enactor POS, the promotion calculation on the POS application is done by the promotion engine component, which runs alongside the POS application. The POS creates a request containing all the relevant items present in the transaction and the promotion engine determines the best deal to apply.

It is important to notice that the POS application is responsible for providing the details of the transaction (customer number, customer group, currency, location, region) and items (e.g. the product id, product price, product group) and the Promotion engine is responsible for loading the promotion configuration itself.

Dynamic Promotion is a mechanism that allows the POS application to supply additional promotions that are only relevant to the current transactions. This would usually be when complex logic is required or when the additional promotions are retrieved from third party system.

Supplying a dynamic promotion does not guarantee that the promotion will actually trigger. The promotion configuration itself must be applicable for the basket. This is similar to Manually activated Promotion; they do not trigger by default and even when manually activated by the operator, the basket must contain the relevant conditions for the promotion to trigger.

Terminology​

  • Static Promotion - A promotion configured in the Estate Manager and broadcast to the POS application. It triggers when the configured condition are met (e.g. the correct product is added to the basket)
  • Manually Triggered Promotion - This is a static promotion that will require the operator to enable the promotion. It also requires the configured condition to be present.
  • Dynamic Promotion - A promotion that is injected to the promotion engine at runtime for a specific basket. As with the promotions above, it also requires the basket to match the configuration.

Example​

Here is an example of a promotion that would not be directly supported by a configured promotion: Given a customer has been added to the transaction, if their birthday is within 10 days of the transaction date, they get a 10% discount.

This could be achieved in the following ways:

  • When the customer is added to the transaction, a custom extension checks for the birthday condition and add a "NEAR_BIRTHDAY" customer group to the transaction. A static promotion with this customer group can be configured as a trigger for the 10% promotion. This solution does not require Dynamic Promotion
  • When the customer is added to the transaction, a custom extension check for the birthday condition and inject a Dynamic Promotion to the promotion request. No promotions need to be configured in the Estate Manager. This example is what this document covers.

Injecting Dynamic Promotions​

The two steps for injecting a dynamic promotion are:

  • create the dynamic promotion configuration. This requires the creation of an instance of the Promotion entity and setting the relevant properties on the object
  • inject the dynamic promotion using the built-in AddDynamicPromotion process

Create Dynamic Promotion Configuration​

The configuration of a dynamic promotion is identical to the configuration of a normal Enactor promotion that would be done on the Estate Manager. Here it is done in code instead of from the UI.

This is a code snippet on how to create a 10% discount on all items in the basket

IPromotionKey promotionKey = new PromotionKey("10_OFF", location.getRegionGroupKey());
IPromotion promotion = new Promotion();

promotion.setDescription("10% off");
promotion.setOperationWithDiscounts(OperationWithDiscountsOptions.APPLIES_AFTER_ON_GROSS);

multibuyReward = new MultibuyReward();
multibuyReward.setRewardType(RewardType.PERCENTAGE_DISCOUNT);
multibuyReward.setRewardValue(0.1);
multibuyReward.setThresholdType(ThresholdType.COUNT);
multibuyReward.setThresholdValue(1.0);
multibuyReward.setRoundingRule(RewardRoundingRule.DOWN);
promotion.getMultibuyRewardsList().add(multibuyReward);

Alternatively the promotion can be created in the Estate Manager and loaded on the POS:

  • create the promotion in the Estate Manager with a known promotion key. Ensure the promotion is disabled so that it does not trigger by default. This can be achieved by setting the "Manual Activation" flag
  • on the POS application, load the promotion (using LoadEntityLenientAction action)
  • re-enable the promotion (promotion.setManualActivationRequired(false))

A combination of the two techniques above can also be used.

Injecting Dynamic Promotion​

With the dynamic promotion created above, the next step is to attach the promotion onto the transaction so that the promotion engine can use it during its calculation.

This is done by calling the Pos/Promotion/AddDynamicPromotion process with the Promotion, Promotion Key, and Transaction Handler. The inputs of the process are:

  • enactor.mfc.Promotion of type com.enactor.mfc.promotion.IPromotion
  • enactor.mfc.PromotionKey of type com.enactor.mfc.promotion.IPromotionKey
  • enactor.mfc.TransactionHandler of type com.enactor.mfc.retail.transaction.IRetailTransactionHandler

There are additional application processes that can be used to manage dynamic promotions:

  • Pos/Promotion/AddDynamicPromotion to add (or replace) a dynamic promotion
  • Pos/Promotion/RemoveDynamicPromotion to remove a dynamic promotion in a transaction
  • Pos/Promotion/ClearDynamicPromotions to remove all dynamic promotions of a transaction

Please note that dynamic promotions are not persisted between transaction.

Duplicate Promotion Key​

Please note that the promotion key must be unique for a given transaction. If the same promotion key is used, then the last dynamic promotion passed in the call to AddDynamicPromotion will be used.

Additionally, if the promotion key of a dynamic promotion is the same of static promotion present in the configuration, then the dynamic promotion will take precedence in the promotion engine. This mechanism can be used to Override a static promotion.