Migrate Legacy Promotion Module to Promotion Engine
17 min read
SAP Commerce Cloud version 6.0 introduced a new promotion engine, which utilizes a Drools rule engine. This article covers the recommended practices for either maintaining the legacy promotions in 6.x and strategies to migrate orders with legacy promotions over to the new promotion engine.
Table of Contents
- Maintaining Legacy Promotion Engine in 6.x
- Functional Gaps in New Promotions Engine
- Migrating to the new promotion engine
- Sample IMPEX
- Recommendations for Removal of Legacy Promotions Extension
- Recommendations for Archiving Legacy Promotion Orders
The Promotions Engine was released with SAP Commerce 6.0. With additional features being added in 6.1 and 6.3 both the legacy promotion and voucher modules have been marked for deprecation and will be removed from the platform in Q2 and Q4 2018. For existing solutions that are looking to upgrade to version 6.x this leaves a couple of options:
- Upgrade your platform to a 6.x version that has the legacy promotions and vouchers extensions, and continue to use it. This will make your upgrade go quicker. However, at some point down the line, before removing it form the platform you will have to migrate to the new promotion engine.
- Upgrade your platform to any 6.x version and at the same time migrate your existing legacy promotions over to the new promotion engine.
Because of the high level of customization associated with promotions, there is no migration tool for promotions, like the one created for the Hybris Management Console (hmc) to backoffice migration. This article will cover both options listed above as well as:
- Identify functional gaps in the new promotion engine
- Strategy for migrating from old promotion extension to the promotion engine
- Cart migration
- Order migration
- Recommendations on removal of legacy promotion extension
- Recommendations on archiving orders with legacy promotions
- Running sample code/test data/unit tests
Maintaining Legacy Promotion Engine in 6.x
It is possible to run SAP Commerce v6.x with the legacy promotion and voucher modules, but we recommend spending time migrating existing promotions to the new promotion engine because eventually the legacy promotions/voucher extensions will be deprecated and will no longer be supported. Understandably, migrating orders and promotions can be a large task, so you might decide to use the legacy promotion modules.
If you wish to continue to use legacy promotions/vouchers in 6.x ensure you have completed the following:
Your localextensions.xml should be referencing the legacy extensions:
In your localextensions.xml make sure you've removed any references to the new rule engine (for example, rulebuilderbackoffice, promotionenginebackoffice, droolsruleengineservices, promotionenginesamplesaddon, promotionengineservices, couponservices, and others).
In your accelerator storefront extension, ensure the following dependency (if it exists) is commented out:
Complete the remainder of your upgrade as per the Upgrade Project Framework
Functional Gaps in New Promotions Engine
This table outlines all of the promotions that were available from the legacy promotion extension and if its functionality can be replicated through the new promotion engine as of SAP Commerce version 6.3:
|Promotion Type||Functionally Reproduced in 6.3|
|Order threshold change delivery mode||Available|
|Order threshold fixed discount||Available|
|Order threshold free gift||Available|
|Order threshold perfect partner x||Available|
|Buy X get Y free||Available|
|One to one perfect partner bundle||Available|
|Perfect partner bundle||Available|
|Stepped Multi-buy||Not Available|
As you can see, currently the stepped multi-buy can not be ported over to the new 6.3 promotions-engine. You might be able to reproduce the behaviour through the use of multiple promotions (for instance, one for each step of the stepped multi-buy promotion) but you can't encapsulate all of the steps within a single promotion currently – for the purpose of this article I will consider that it's functional counterpart in the promotions engine is not available. The rest of the legacy promotions are available using the new promotions engine, so the feature gap is relatively low.
Migrating to the new promotion engine
We recommend you complete the. steps below while the application nodes are unavailable to the public, because some of the steps interfere with the customers browsing experience. Once all migration steps are completed, then you can open up your application again for public browsing. Be sure to schedule downtime for your site to execute these steps.
Additionally, we recommend being on the latest version of SAP Commerce Cloud, to take advantage of all the performance and bug fixes related to the promotion engine.
The general strategy to migrate the old promotion extension to the new promotion extension is relatively straight forward. The steps are the following:
- Disable new users from using the site while migrating.
Modify the localextensions.xml to include the following:
In your accelerator storefront extension ensure the following dependency (if it exists) is included:
Build and run the platform from the command line:
Update running system with all options checked after you have started up the application. At the very least make sure the following project data is set:
This will create essential data to run. If you do not want essential data to run, you can verify the steps below in your test environment without the box checked.
- Create equivalent promotions using the new promotion engine for any promotion created using legacy promotion (see below).
- Publish the new promotions.
- Confirm the promotions are working on the site (no need to complete the order, but at least maker sure the carts are now picking up the promotions).
Create the cron job (seebelow) in the system with the following script:
- Run the cron job.
- Check the result, if SUCCESS, then all orders have been migrated, if ERROR, check the logs to determine the orders that had a problem and identify the root cause
Note: To revert to the legacy promotions extension seesection above
Here is an example IMPEX that creates equivalent promotion engine promotions for the legacy promotions that come with SAP Commerce.
There is no default way of determining the equivalency of a legacy promotion with a promotion engine rule. We recommend you name the promotion engine rule using the same code as the legacy promotion, as it makes the lookup much easier later.
Make sure to model any legacy promotions that was active before switching to the promotion engine, using new data structure. There are a couple of options to create these promotions:
- Data load (the promotions were created on some other system and then imported into production) through impex (see )
- Hand create them in thebackofficeapplication
More information about promotion engine can be found on this page of the product documentation.
There may be carts that have legacy promotions on them that need to be migrated over to the new promotion-engine (so they don't reference promotions in the legacy promotion extension). The key here is as mentioned above is that the promotions that were active before the system was switched to the new promotion engine need to be modeled in the new data model that the promotion engine uses in order for there to be a seamless transition from the view of the customer. After you migrate promotions and make your site publicly available when the customer returns to their cart there should be an automatic re-calculation fired, because their cart will be loaded from the database (no cache). Additionally during the checkout their cart will be recalculated, causing all promotions to be removed and re-evaluated. This will result in replacing the legacy promotion results with the promotion results now being created by the promotions engine.
In summary, there should be no further intervention required to migrate carts since the system will be restarted; the SAP Commerce platform should be able to handle the update to promotion engine promotions automatically.
Make sure to model any legacy promotions that have been used in older orders before switching to the promotion engine using the new data structure, published and activated. There are a couple of options to create these promotions:
- Data load (the promotions were created on some other system and then imported into production) through impex(see above)
- Hand create them in thebackofficeapplication
More information about promotionengine can be found on this page of the product documentation.
There will be orders in the system that have legacy promotions attached to them. When migrating to the the new promotion engine you have two options:
- Do nothing and leave those orders the same: This means the old orders with legacy promotions can not be modified anymore, and once the legacy promotions are removed they won't be able to be opened without errors. Any modification to an order with a legacy promotion will cause a recalculate, which would remove the legacy promotion and alter the price of the order. Think about archiving old orders (otherwise will always have to keep the legacy promotion extension in order to view orders in the future). This is most likely not an option for situations because because potential orders could require changes (refunds, returns, cancellations).
- Migrate those orders to use the new promotion engine promotions: This will allow you to continue to modify orders as needed, as a recalculate would use the equivalent promotion engine promo during recalculate. With this option you will be able to remove the legacy promotions from the system. The two issues with this option. Firstly, you need to create equivalent promotion engine promotions for every legacy promotion created. Secondly, you need to recalculate every order that could potentially be modified. During recalculation you may run into other issues. For example, if taxes change between when the order was originally created and when it is recalculated, even if the promotion engine promotion is applied correctly, the total would change due to the tax change.
Our recommendations for orders are:
- Evaluate how many orders and legacy promotions you have and find an appropriate time in the past where an order most likely needed to be open. This will typically be 6 months to 1 year, but could be longer. The shorter the time period, the fewer promotions you'll have to recreate and the fewer orders you will need to recalculate.
- Create a strategy for what to do if an opened order hasn't been recalculated with a promotion engine promo. This should be shared with all customer-facing employees, so they understand what to do when this happens. Unfortunately, there isn't a common strategy because every solution will be different depending on company policy.
The process outlined here involves recalculating orders with a promotion engine rule(s) applied. There is a known bug in some versions of SAP Commerce that prevents recalculation on an order/cart with the new promotions. If you wish to proceed with the steps outlined below, make sure you are running at least one of the following versions
The easiest way to migrate orders is to create a CronJob that can be run once (after all of the data is set up and ready and promotion engine is enabled) that will force recalculation of the orders and allow for the equivalent promotion engine promo to be applied to each order. The cron job should log an error if the promotion migration fails an integrity check (if the order total before does not equal the order total after the calculation) – these orders would have to be looked at manually to determine the issue.
A general outline of the cron job activities are as follows:
Queries for orders that have promotion results (assumption is there are no orders with new promotion engine promotions because we haven't allowed any customers to use site yet)
- (optional) If you're not querying all orders and you are utilizing a smaller timeline, ensure your cronjob takes a date/number of days as a parameter and utilize the parameter in the query above to reduce the number of results.
- (optional) Perform a sanity check that determines if all legacy promotions have equivalent promotion engine rules. If not you need to determine what to do (abort, log and continue, and so on) this can prevent an error in step #5 from occurring
- Disable all of the published promotion engine promotions, once orders are found
For each order found in step #1, find the equivalent promotion engine promo(s) and enable them
Capture the existing order total before recalculation.
Re-calculate the order, then re-apply promotions and taxes.
- Compare the new order total with the value in step #4. If they are not the same, log the order as an error for manual follow-up later.
- Disable all the promotions enabled in step #3.
- Continue steps 3-7 until all orders are migrated.
Return the cron job SUCCESS if all orders were migrated without error, otherwise ERROR status.
In order to prevent orders from receiving promotions that weren't intended for them, we disable all active rules between each order. This means at the end of a run ALL your rules except for any from the last order processed will be disabled. Before re-enabling your site for users ensure you have published and activated all the rules that should be active for your site currently (inbackofficesee Rule Engine->Drools Rules)
Recommendations for Removal of Legacy Promotions Extension
The legacy promotion extension is still depended upon heavily by SAP Commerce code; it can be seen as dependant on the commerceservices, promotionengineservices, and promotionsbackoffice extensions (all of which are platform code). The best that you can do is remove any dependencies in your data to the types contained within the promotions extension, so when it's completely removed from the product, it makes the task easier without breaking the viewing of orders.
Currently this is not possible by the way that the code is organized in the code, but in preparation of this for the future the following is required:
- No multi-step promotions on orders in the system (because they can't be modeled in the new promotion engine and therefore the order can't be migrated).
- All orders with legacy promotions are migrated over to use the new promotions using the promotion engine.
Recommendations for Archiving Legacy Promotion Orders
Archiving old orders should be considered if the likelihood of opening them to view them is remote. We recommend this approach, because if you want to migrate orders with legacy promotions to use the new promotion-engine, then you would have to re-create all promotions that are present on the old orders. This is a time consuming task, as there could be thousands or millions of orders and just as much promotions. So, having to re-create promotions for each order that you might not have to open again is a waste of time. Therefore, it is more efficient to have a threshold or orders that you are trying to migrate while archiving the rest of the orders in some manner.
Archiving orders would require effort to create and customize for your needs, but with every order you archive you will have fewer orders to migrate promotions
You should now understand the effort to either maintain your legacy promotion module in 6.x versions of SAP Commerce Cloud or how to take the recommended steps of migrating to the promotion engine.