CX Works

CX Works brings the most relevant leading practices to you.
It is a single portal of curated, field-tested and SAP-verified expertise for SAP Customer Experience solutions

Step-By-Step Analysis of SAP Commerce Upgrade Effort

10 min read

Step-By-Step Analysis of SAP Commerce Upgrade Effort

With versions of SAP Commerce reaching end-of-life typically after 24-months, many project teams are interested in upgrading to a supported version of SAP Commerce, in order to stay on a supported version of the platform. As part of the Discovery phase, of the Upgrade Project Framework for SAP Commerce Cloud, there is an activity to generate a Rough Order of Magnitude (ROM) for an upgrade. This article provides a how-to in 3 steps (processes).

Table of Contents


The upgrade analysis or upgrade assessment is only applicable if this work is performed by the team that is doing the upgrade. However, if the upgrade is a foregone conclusion, then omit this process and let the team performing the upgrade execute the Upgrade Engineering activity (Execution phase).

The upgrade analysis or upgrade assessment consists of three steps:

  1. Prepare local environment
  2. Analyze code
  3. Report findings

The purpose of the upgrade assessment analysis is to get an analysis report that covers the ten items listed for the report. The three steps above help produce an upgrade assessment analysis report.

During the analysis, the engineer goes through the different phases of the upgrade. This upgrade analysis is geared towards capturing the issues and spending the least amount of time upgrading code. The list of issues gathered during the upgrade analysis is used to create the project scope.

Prepare local environment

The key part of this step is to isolate your customizations and any platform changes. This will give you estimate of how much effort is needed to upgrade and test.

If you're not using a template (for example, an accelerator) skip steps.

  1. Create a new git repository.
  2. Generate the template with the same parameters you used originally, using your source version of SAP Commerce. Commit this code (without any modifications) to your master branch.
  3. Add all your customizations and commit.

    You should now have a local development environment that looks like the example below.

      `-- hybris/     
        `-- .git/        # TO KEEP: your local .git clone metadata folder
        `-- bin/         # platform + our code - /!\ TO KEEP (partially)
          `-- custom/    # TO KEEP: your custom code
          `-- ext-*/     # TO REMOVE: SAP Commerce platform
          `-- platform/  # TO REMOVE: SAP Commerce platform
        `-- config/      # TO KEEP: your config
        `-- data/        # TO REMOVE: local DB and resources (note: you will lose your runtime data if you remove this)
        `-- log/         # TO REMOVE: just log files
  4. Create a new branch in your git repository.
  5. To simplify the steps below you should define the following:

    export NEW_ARCHIVE="<>"
    export NEW_VERSION_FOLDER="<folder_where_you_unzip_the_new_hybris>"
    export PROJECT_HOME="<path_to_your_project>"
  6. Execute the following code to replace the old platform code with the new one:

    Assumption is you have a hybris/ parent folder under your ${PROJECT_HOME}., as that's how the hybris archive is structured. Adjust if needed

    cd ${PROJECT_HOME}/hybris/
    # delete the SAP Commerce extensions that ship with the solution
    rm -rf bin/platform bin/ext-*
    # delete temporary local data and stuff we don't want to conflict with to start afresh
    rm -rf {data,log,tmp}/
    # unzip the target version
    unzip -d "${NEW_VERSION_FOLDER}" -qo ${NEW_ARCHIVE}.zip 'hybris/*' 
    #Overlay the New Hybris on Top of Your Project
    cp -prf ${NEW_VERSION_FOLDER}/hybris/bin/* ${PROJECT_HOME}/hybris/bin/

    The cp options are here for a reason:

    • -rf: you want to copy everything recursively and override stuff that's in your way (though probably should not have anything to override, remove the f if you aren't confident in forcing override)
    • -p: you want to leave the files timestamps unmodified (or your Hybris build will break because it will think that some of your new dependencies are obsolete).
  7.  If you're doing a functional upgrade and you want to understand how much has changed in the templates you used during the second step, then remove any of the custom extensions and regenerate the extensions using the target version modulegen. Your analysis will not include the customizations you made to the generated templates. (Optional)
  8. Commit it without any further modifications.
  9. Generate a pull request against your master branch to report of all the changes made.

    git format-patch master --stdout > Upgrade.patch

Analyze Code 

There are 5 main areas of focus when it comes to analyzing platform code under a new platform version:

  1. Build
  2. Launch 
  3. Update
  4. DB/ImpEx Scripts
  5. Smoke Test


  1. You should be able to rebuild your code:

    cd ${PROJECT_HOME}/hybris/bin/platform
    ant clean && ant customize && ant deploy && ant all && ant initialize -Dtenant=master
  2. Apply any additional changes and commit them to your branch.

Here are some tips on how to make it easier:

  • Fixing/detecting deployments - Specifying a Deployment for SAP Commerce Platform Types has guidance on detecting missing deployments in types.
  • Comparing platform properties - Configuration Properties Reference  has information about the kinds of properties files to compare between platforms.
  • Use your IDE find/replace function to quickly replace method calls whose signatures have changed between releases due to API changes.
  • Check console logs to detect errors and warnings during compilation that will provide guidance on areas to refactor.
  • OOTB (out of the box) Accelerator (compare with canonical accelerator, fix/mock accordingly to new standard)

This process requires a fix or a mock for any issue. Every mock or fix needs to be committed separately, like your development workflow. One approach you might want to consider, is creating epics for functional areas identified during the build phase and then creating tasks (linked to an epic) for each issue that is found. That way, all issues are fixed, documented, and tracked as tasks.


After a successful build, try to launch your SAP Commerce solution. Initial types of problems during launch are caused by Spring:

  • Spring versioning 
  • Jalo using beans before context is generated 
  • Deprecated beans 
  • New converters 

Here are three useful articles that can help you with those problems:

This step might be time-consuming because you won't see all errors. After fixing each Spring context error, you need to commit it and launch the platform again. 

After a successful start-up, make sure you can access SAP Administration Console and Backoffice. 


After launching the platform you need to perform update running system, so that the type system generates correctly. There is a high probability that this will fail because of the following:

  • New deployment has been added
  • Type code for deployment has been changed
  • Name of deployment has been changed
  • Extension name of deployment has been changed
  • Table name of deployment has been changed
  • Properties table name of deployment has been changed
  • Super name of deployment has been changed
  • Package name of deployment has been changed
  • Modifier of deployment has been changed
  • Deployment has been removed
  • Parent of composed type has been changed (require change of super type PK and inheritance path)
  • Item JNDI name of composed type has been changed
  • Jalo class name of composed type has been changed
  • Extension name of composed type has been changed
  • Type code of composed type has been changed

DB/ImpEx Scripts 

During steps above, you might encounter cases that require data adjustments. If so, they should be noted and any produced ImpExes or scripts should be committed to version control.

Smoke Test

This step is optional since you might run out of time because of the steps above. However, if you do have time there are a different kinds of tests:

  • Running cronjobs (creating, enabling, and scheduling)
  • Adding products to carts
  • Checking other cockpits and verifying basic operability
  • Other test scenarios identified during team meetings
  • And many more

Report Findings

During the steps above, take notes and add them to the analysis outcome documents. Here are two suggestions:

  • Upgrade assessment analysis sheet
  • Upgrade assessment analysis report

Upgrade Assessment Analysis Sheet

To understand the changes you made, you could create a pull request for a merge (from your branch to master) or you could use the following:

git log --pretty=oneline

  • Extension - a list of extensions that are included and their location. Prepare the list while you prepare the local environment.
  • Extension hierarchy - this should present extension dependencies.  
  • Effort estimation - based on your findings, estimate how long it will take to solve found issues.

You may also want to run a final:

git format-patch master --stdout > Upgrade.patch

You can then use this patch to kick-start the actual migration by running the following in your team's git repository:

git am Upgrade.patch

Upgrade Assessment Analysis Report

This document describes the upgrade assessment analysis process, scope, high-level estimation and focus areas:

  • Analysis of properties
  • Initial upgrade assessment scope definition
  • Effort estimation
  • Recommended upgrade approach
  • Technical challenges
  • Extensions change analysis
  • Upgrade risks
  • Upgrade benefits
  • High-level upgrade plan (provided that alignment on the timeline is possible at this early stage)
  • Project team’s responsibilities


By following the steps above, you can quickly see how many changes were made between your customized source version of SAP Commerce and your target version. Depending on the extent of the changes, you can start estimating your upgrade's duration. The goal of this assessment step is to get the target version up and running as fast as possible by locating the gaps. It's not supposed to be production ready, but it can help identify what work needs to be done.