Prepare from the Start: A Possible Cure for the Painful SAP Commerce Upgrades

You cannot say that you are truly a SAP Commerce (Hybris) developer until you do your first migration. Every developer who worked on such a task has scars to show and a war story to tell.

As each Client has its own needs, customization of the standard accelerators becomes necessary and this is the primary source of headaches. There are multiple guides out there on how to perform an upgrade, but no one can guide you on how to migrate your custom features.
This is not just another article on how to handle upgrades, but we’ll focus instead on how you can properly prepare for them by tackling upgradability right from the start.

A bit of theory

Let’s start with the basics. Architectural Characteristics, also known as Non Functional Requirements, are a crucial part in the overall success of the architecture and therefore, of the project. Unfortunately most of the time the focus is on the functionality and these are either overlooked or taken into account too late which can lead to significant additional effort.

So what are the architectural characteristics one should consider in a SAP Commerce (hybris) project?

If somebody would have asked me this question a couple of years ago, the very first thing that would have popped into my head would have been Performance. Then you learn that also Scalability and Configurability are important. Then somebody tells you that Availability is more important than Performance. In the end you figure out that there are many answers to this question, but there is no right or wrong, it all depends on the context, as there will always be trade-offs because of the domain, timeline, team availability and technology stack knowledge, budget, etc.

There is one Architecture Characteristic though that should be considered for every SAP Commerce Cloud (Hybris) project, and that one is the Upgradeability.
In order to fulfill the business needs, a project must evolve and it may do so by upgrading. This remark applies for any project, especially for a SAP Commerce (Hybris) platform based one.

Upgradeability refers to the ability to easily/quickly upgrade from a previous version of this application/solution to a newer version on servers and clients.
Fundamentals of Software Architecture by Mark Richards and Neal Ford

So why should you upgrade? This depends on many factors but the main drivers for performing an upgrade of the Platform & Accelerator versions used are:

  • enabling new features
  • supportability

The decision to upgrade to a new Platform or specific Accelerator version must indeed be carefully thought of. There are many business drivers for doing an upgrade but I’ll skip them for the sake of the article. My takeaway, also learned the hard way, is don’t be a beta-tester. Avoid being the first one to try to upgrade to the new, shiny release, as you usually run into a lot of unforeseen problems. On the other hand, Hybris’ recommendation is to avoid fighting windmills, meaning make sure you run on versions that were released no later than 2 years prior.

Theory into practice

SAP Commerce Cloud (Hybris) comes with various Accelerators which are basically different flavors usually specific to a certain area like B2C, B2B or industry such as Telco, Travel, Retail etc. The purpose of these Accelerators is to offer a set of predefined functionalities in order to reduce the time needed to Go Live. The issue with this approach is that as soon as you generate the Accelerator extensions (via ant modulegen) and make a single change to the generated code, you have created custom code. Every additional change you make to the generated Accelerator extensions increases the level of customization and implicitly the upgrade effort.

So how can you and your Clients take advantage of the new features included in the latest releases without spending too much time in porting over custom code? How can you ensure immediate adoption of future releases, in one word – Upgradability?

The traditional steps for performing a Functional migration would be:

  1. upgrade platform code to the new version
  2. re-generate custom extensions based on the latest accelerator template (ant modulegen)
  3. identify and port custom code
  4. perform technical migration of configuration and database, in order to be compatible with target binaries version

What I’ve learned after doing this a couple of times is that the most time spent during the migration is on identifying the custom code. One idea widely spread amongst the SAP Commerce projects is to adopt a certain naming convention in order to isolate the custom code e.g. use the project name as prefix. The issue with this approach is that naming conventions are error-prone, identifying the customization takes time and usually a certain level of knowledge and experience on the project.

My primary experience when it comes to SAP Commerce projects is on Telecommunications, also called Telcos. If you followed the release notes from SAP Commerce, for sure you have seen that the Telco Accelerator had a remarkable evolution in the past years. Much awaited features like Eligibility, Compatibility, Composite Prices, TM Forum APIs were released every quarter. We wanted to leverage our implementation on these features, our Client also wanted to have that competitive edge so the only thing left to do was to continuously upgrade. This is unfortunately easier said than done.

The first problem we stumbled upon each time was to identify the right person for the job, that person that has the seniority and a deep understanding of the project in order to perform that tedious and crucial activity of identifying the customizations and port them over.

Just like in cooking, after you follow a recipe multiple times, you become confident enough and you want to add a personal touch to that classic recipe. This is what happened in our case as well, more exactly, we understood that by applying some basic software development principles from the beginning we can make our life way more easier later.

During the setup of a SAP Commerce project, the template extensions are cloned and the derived extensions are treated as custom code, but the key to create maintainable code and to ensure support for upgrade is to adhere from the beginning to low coupling and high cohesion.

The diagram below describes an approach to reduce the coupling to the minimum. Basically, the blueprint of your project should be the outcome of the following steps:

  1. generate the accelerator extensions (in blue) based on a SAP Commerce accelerator (in gray) using ant modulegen
  2. for core, facades and storefront generate a separate extension/addon using ant yempty/ant yaddon where to isolate the logic (in green)
  3. generate a new extension for integration layer – in some cases it would make sense to have a specific extension for each integration (in green)
  4. consider functional cohesion (place all functionality related to a single feature in a separate extension) (in green)

From now on all changes should be done in the green section. The generated accelerator extensions (in blue) could be either versioned in a different repository or uploaded to a Binary Repository Manager (e.g. Artifactory) to avoid the temptation of modifying directly the generated code instead of the ‘empty’ extensions. Of course this approach adds a layer of complexity, but in our case it proved to be worth it.

If the above mentioned recipe is followed, then the steps for performing a Functional migration would be:

  • upgrade platform code to the new version
  • re-generate custom extensions based on the latest accelerator template (ant modulegen) and upload them to a Binary Repository Manager
  • perform technical migration of configuration and database, in order to be compatible with target binaries version

There is one thing though that cannot be avoided and that is the refactoring of the custom code when it becomes redundant as it is already delivered by the out of the box. A gap analysis has to be performed before taking a decision, but even this can be softened if your custom code follows some basic principles.

Even if your project is in an advanced stage, maybe already deployed to Production, I would highly recommend to invest some time to figure out the right extensions architecture for you. It will definitely pay off even if you don’t upgrade to the latest accelerator version more than once or twice per year.


First Law of Software Architecture says that everything in software architecture is a trade-off. Try to understand from the beginning if the upgradability is a hard requirement coming from your Client because it can influence some structural aspects of the design. Even if this is not coming from the Client, your duty is to highlight the importance of spending some extra time at the beginning of the project for defining a proper and scalable extensions architecture, that on the long run will prove to be also cost efficient.

As a rule of thumb, avoid touching the generated accelerator extensions, ensuring low coupling and high cohesion will improve your maintainability, upgradability and code quality in the end.