How to upgrade SAP commerce

Here are some recommendations to make your upgrades as smooth as possible.


Please take your time to update and test the new Hybris version. In average the update takes an effort of 2 days of development and many days of testing. Try not to be interrupted by other work items.

What Hybris version to use a target version?

Never update to the last Hybris release as it may be buggy and not stable for production. If there isn't any critical fix or feature that you need, update to the third last version with the highest patch level. For example: If the last version is, update to version

If there are more than 4 releases between your current version and your target one, update the hybris version slowly with steps of 3-4 releases. For example: if your target version is 6.7 and your current one is 6.2, update first to 6.5 and then to 6.7.

Avoid SAP commerce 6.4. This version seems to have threading bugs and the update running system may block for hours.

Preparation to have less surprises

  • Go to the release notes page of every release version between your current and target version. Analyze what parts of the standard extensions have been changed.
  • Don't forget to read the titles of all the fixed tickets on the page Important Information about the SAP Commerce 6.x Release and guess if the changes done on the ticket may impact your code.
  • Make a list of all the changed areas in all the releases from your current version to your target version. These areas have to be carefully tested

Deprecation of standard extensions

Please read the section End-of-Life (EOL) Announcements to see if any of the extensions which your system depends on was deprecated by Hybris. You have 18 months to migrate to an alternative extension. Please inform the dev team about the deprecation, so less features are implemented on deprecated extensions or technologies but wait until Hybris offers an alternative with the same features as the old one. This may happen a few months before the deadline.

Make your custom code compatible with the target version

  • To isolate the changes from other work items, create a feature branch
  • Download the zip file with the target version
  • Extract the subdirectory hybris on your local repository
  • Compare the files on hybris/config/customize and hybris/config/<server name>/customize with the files in the directory platform
  • For every customized file you have three options:
    1. Remove the customized file and write a solution with overrides the bean or create an ant hook on one of your custom extensions. This will reduce the update effort and bugs of future releases and it is the recommended approach
    2. Read the Hybris documentation to find out if the customized features ships with the new Hybris release. If the customization is obsolete, your can remove the customized file
    3. Merge Hybris's changes into the customized file. You usually override the customized file with Hybris's file and reapply the customization
  • Run ant clean customize all
  • Correct the compilation errors
    • If error is originated from new methods in the superclasses from Hybris, please check if you can reduce number of classes which you are overriding or make your custom classes extend a Hybris class
    • Hybris removes deprecated methods once in a while, so you may need to find the new methods and refactor your code
  • When the Spring libraries are updated you have to check your xml configuration specially your web security configuration
    • Start the server many times until the application contexts correctly load
    • Usually changes in third libraries like Spring Security break the application contexts

Removal of unused code and deprecated extensions

  • Before spending lots of time in migrating code, ask yourself if it is required. For example: Remove the web context of an Hybris extension which is used to import data during the deployments. There is no need to migrate the application context to the newest version of Spring Security if the code isn't required
  • Remove any deprecated Hybris extension which you may be using. Less code means less bugs and maintenance


  • Test the changes in a database with similar data as in production
  • After the tests were successful, leave the staging server with the new Hybris version in observation for 2-3 weeks

Deployment in production

  • Reduce the number of fixes and features of any release including a Hybris upgrade
  • Inform anyone that unforseen bugs are expected

– Based on SAP commerce 6.4


Enter your comment. Wiki syntax is allowed: