Guide - 7.10.12.2 Storing of Promotion Information at Orders

Info

This Migration Guide applies for 7.10.12.2+ and 7.9.4.11+.

Introduction

A basket may contain several promotions that are triggered by a condition or by a promotion code. In the past the created order of a basket that contained promotions only stored the IDs of the used promotions without any further information. The ID was then used to retrieve the information from the existing promotion objects in order to display them in several order detail views in the back office as well as in the My Account | Order History | Order Details section. This approach is very efficient because no redundant information is stored. However, the disadvantage was that promotions had to remain in the system for a long time or even for the system lifetime because the impacts of a removal of a promotion were not entirely clear. As a result, the number of promotions in the system increased more and more, making it very difficult to manage the promotions. The total number of promotions in the system, including the ones that are not active,  also influenced the whole system's performance significantly.

In order to overcome these problems mentioned before, the order creation process has been adapted to store the relevant information of all used promotions directly at the order.

1 Technical Details

1.1 Stored Fields

Since an order can contain multiple promotions which include a lot of textual information for multiple languages, the data might need a lot of space when storing all information is necessary. For that reason, the promotion information stored in the order has been restricted. The following table provides an overview about the information that is stored:

Promotion FieldDescriptionDisplayedLanguages
UUIDInternal UUIDBackoffice-
Promotion IDPromotion ID that is entered when creating a promotionBackoffice-
Disable Messages FlagFlag that indicates if the maintained title/long title is displayed for this promotion or notStorefont-
Promotion CodeUsed promotion code if promotion was code-basedBackoffice-
Amount NetNet amount of the promotional discountBackoffice/Storefront-
Amount GrossGross amount of the promotional discountBackoffice/Storefront-
Display NameName of the PromotionBackofficemax. 3 languages*
TitlePromotion Title (shown in the order details)Storefrontmax. 3 languages*
Long TitlePromotion Long Title (promotion details dialog in order details)Storefrontmax. 3 languages*

Legend:

  • - means language-independent
  • max. 3 languages* means:
    1. Store text in the selected basket/order language
    2. If different to 1.: Store text in default language of the application
    3. If different to 1. and 2.: Store text in lead locale language.

Orders that include the promotional information are marked with a boolean attribute value "PromotionMessagesFlag".

Note

The complete promotional information that is maintained in the back office and displayed in the storefront consists of

  • Disable Messages Flag
  • Icon
  • Title
  • Long title
  • Rule Description
  • Legal Content
  • External URL Flag + External URL

Only the values printed in bold type are stored in the order. For this reason it is recommended not to remove the promotion from the system until a certain time, especially after legal claims are expired.

1.2 Extensions to Retrieve Data

The OrderBO extension "OrderBOAppliedRebateExtension" to retrieve the promotional data from the data has been partly deprecated since all methods that return a collection of "AppliedRebateBO" rely on existing promotions in the system. As a replacement there is a new OrderBO extension called "OrderBOPromotionInformationExtension" which contains all methods that have been deprecated with the same name, but returning a collection of "PromotionInformationBO". All other methods from OrderBOAppliedRebateExtension that are not deprecated can also be found in the new OrderBOPromotionInformationExtension and can be used likewise.

The same applies for "OrderProductLineItemBOAppliedRebateExtension" and "OrderShippingBucketBOAppliedRebateExtension". All methods returning a collection of "AppliedRebateBO" are deprecated and should not be used anymore. There are new extensions "OrderProductLineItemBOPromotionInformationExtension" and "OrderShippingBucketBOPromotionInformationExtension" to retrieve the new "PromotionInformationBO".

From ICM version 7.10.16.1 on these new extensions are only available for migrated (see next chapter 'Migration') or newly created orders. Otherwise the extensions are null. This can be used to distinguish between old orders that are not migrated yet and new respective migrated orders.


OrderBOAppliedRebateExtensionOrderBOPromotionInformationExtension
Collection<? extends AppliedRebateBO> getAppliedItemValueRebates()Collection<PromotionInformationBO> getAppliedItemValueRebates()
Collection<? extends AppliedRebateBO> getAppliedItemValueRebates(boolean hasPromoCode)Collection<PromotionInformationBO> getAppliedItemValueRebates(boolean hasPromoCode)
Collection<? extends AppliedRebateBO> getAppliedOrderValueRebates()Collection<PromotionInformationBO> getAppliedOrderValueRebates()
Collection<? extends AppliedRebateBO> getAppliedOrderValueRebates(boolean hasPromoCode)Collection<PromotionInformationBO> getAppliedOrderValueRebates(boolean hasPromoCode)
Collection<? extends AppliedRebateBO> getAppliedOrderShippingRebates()Collection<PromotionInformationBO> getAppliedOrderShippingRebates()
Collection<? extends AppliedRebateBO> getAppliedShippingRebates()Collection<PromotionInformationBO> getAppliedShippingRebates()
Collection<? extends AppliedRebateBO> getAppliedShippingRebates(boolean hasPromoCode)Collection<PromotionInformationBO> getAppliedShippingRebates(boolean hasPromoCode)
Collection<? extends AppliedRebateBO> getAppliedRebates()Collection<PromotionInformationBO> getAppliedRebates()
Collection<? extends AppliedRebateBO> getAppliedRebates(String promoCode)Collection<PromotionInformationBO> getAppliedRebates(String promoCode)
Collection<? extends AppliedRebateBO> getAppliedRebates(boolean hasPromoCode)Collection<PromotionInformationBO> getAppliedRebates(boolean hasPromoCode)
OrderProductLineItemBOAppliedRebateExtensionOrderProductLineItemBOPromotionInformationExtension
Collection<? extends AppliedRebateBO> getAppliedRebates()Collection<PromotionInformationBO> getAppliedRebates();
Collection<? extends AppliedRebateBO> getAppliedRebates(String promoCode)Collection<PromotionInformationBO> getAppliedRebates(String promoCode);
Collection<? extends AppliedRebateBO> getAppliedItemValueRebates()Collection<PromotionInformationBO> getAppliedItemValueRebates();
Collection<? extends AppliedRebateBO> getAppliedItemShippingRebates()Collection<PromotionInformationBO> getAppliedItemShippingRebates()
Collection<? extends AppliedRebateBO> getAppliedItemGiftRebates()Collection<PromotionInformationBO> getAppliedItemGiftRebates()
Collection<? extends AppliedRebateBO> getAppliedItemHiddenGiftRebates()Collection<PromotionInformationBO> getAppliedItemHiddenGiftRebates()
OrderShippingBucketBOAppliedRebateExtensionOrderShippingBucketBOPromotionInformationExtension
Collection<? extends AppliedRebateBO> getAppliedShippingRebates()Collection<PromotionInformationBO> getAppliedShippingRebates()

1.3 Templates

All standard ISML templates (back office and storefront) can handle promotional information from the orders as well as information from existing promotion objects. Since an order is marked if the promotional information is included or not, the templates include conditions to support both cases. The back office templates usually provide a link to the used promotion if the promotion exists in the system. If it does not exist in the system, the title is displayed without link.

2 Migration

2.1 General

The promotional information is stored automatically at the order for all new orders. As long as existing promotions should not be removed from the system, there is no need to migrate old orders since all templates involved are prepared to handle old and new orders as well. Nevertheless, a clean up of expired and inactive promotions should be done from time to time. If this is done, a migration of old orders is recommended to obtain the information displayed for the customers in the storefront as well as for the Shop Manager in the back office.

A migration pipeline has already been prepared, but a migration job the executes the pipeline has to be created manually as described in the next section.

2.2 Creating a Migration Job

  1. Open SMC.
  2. Select Schedules | Scheduling.
  3. Select the Domain SLDSystem an click Apply.
  4. Click the New button at the bottom of the table.
  5. Create a New Schedule as the following picture shows.
    The pipeline name is MigrateOrderPromotionInformationJob and the start node is named MigrateOrders. It is important to enable the schedule and to select the Application SLDSystem.
  6. Commit your changes by clicking the Apply button.
  7. Open the Attributes tab.
  8. Create a new attribute as shown in the picture (name: MaxNumberOfOrdersPerRun, Data Type: Integer, Value: 1.000).
  9. Click the Add button to confirm.

    This attribute defines how many orders are migrated at one time per channel. This number can be increased if necessary. However, it is not recommended to migrate all orders in one run. This might influence the performance of the shop.
  10. Run the migration job manually or as recurring job depending on the system parameters and the number of order to migrate.
  11. The log file of the job contains information about migrated orders:

    Information About Migrated Orders in the Log File
    [2019-07-16 15:30:39.344 +0200] [JobExecutor288850583] [Job:MigrateOrdersWithPromoInfo] [Req:R4sKAEsBIU0AAAFr7VdhcPr6] INFO  ProcessOrderPromotionInformation  - No orders to migrate for channel: Shopping Live 
    [2019-07-16 15:30:39.358 +0200] [JobExecutor288850583] [Job:MigrateOrdersWithPromoInfo] [Req:R4sKAEsBIU0AAAFr7VdhcPr6] INFO  ProcessOrderPromotionInformation  - No orders to migrate for channel: Reseller Channel 
    [2019-07-16 15:30:39.367 +0200] [JobExecutor288850583] [Job:MigrateOrdersWithPromoInfo] [Req:R4sKAEsBIU0AAAFr7VdhcPr6] INFO  ProcessOrderPromotionInformation  - No orders to migrate for channel: inTRONICS Business 
    [2019-07-16 15:30:42.242 +0200] [JobExecutor288850583] [Job:MigrateOrdersWithPromoInfo] [Req:R4sKAEsBIU0AAAFr7VdhcPr6] INFO  ProcessOrderPromotionInformation  - Migrated 1000 of 58662 orders for channel: inTRONICS 

    Now it can be decided if the job must be executed several times or not.

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.

Customer Support
Knowledge Base
Product Resources
Support Tickets