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

Upgrade Engineering for SAP Commerce

38 min read

Upgrade Engineering for SAP Commerce

We've covered the other phases of an SAP Commerce upgrade in Upgrade Project Framework for SAP Commerce Cloud. This article outlines the Upgrade engineering activity of an SAP Commerce upgrade, which is where you will spend most of your time and effort. During this phase you will perform all the work to make the upgrade happen by implementing the project plan created in the planning phase. The end result of this phase is an upgraded code base that is ready for more thorough testing .

Table of Contents

The main activities for this phase are outlined in the diagram below. A high-level description of the activities will follow, while in-depth description is covered in child pages.

Upgrade Engineering

During this activity, you will perform the necessary preparation and technical upgrade (re-engineering) tasks outlined below, in order to deploy your upgraded solution to your chosen environment/environments. At a high level, this will result in a potential release candidate build that includes:

  • Upgrade platform binaries running in target version
  • Technically migrate data model, type system, and business data that is compatible with your target version
  • Technically migrate custom code and configurations (where needed)  that make the code compatible with your target version
  • Any other changes not affected by platform version change. Custom functionality will remain unchanged
  • System performance that is as good as your source version
  • New features that are only available directly through the upgrade platform binaries
  • Cherry-picked critical features (like security mechanisms)

The resulting solution architecture at the completion of a technical approach is dependent on whether your source version was built using a template (B2C, telco, financial, etc). Regardless of your solution architecture, the individual upgrade steps with technical approach are mostly the same. 

Th provides definitions for the items in the solution diagrams below.

Core Platform

Platform core functionality. This is what is found in the hybris/bin/platform directory

Platform extensions

Platform core extensions usually placed in hybris/bin/ext-(...) . These extensions provide extensive functionality and are built upon the core platform

Business Tools

The tools that are used for performing business functionality. These are comprised of SAP Administration Console, hMC, backoffice and cockpits

Custom extensions

Any extension that changes or extends behavior of the platform, usually placed in hybris/bin/custom

Platform Template

Standard templates that can be used to accelerate development. These include B2C/B2B accelerator, Telco etc.

Template Customizations

Any customization that extends/overwrites the behavior of the generated code from the platform template

Non-Accelerator Based Solution

The technical approach for a non-accelerator based solution results in the platform binaries being upgraded to the target version, with technical upgrade (re-engineering) of custom extensions code, configuration, and data. This can best be summed up in the following diagram: 

Upgraded? Technically Migrated? Comments
Core Platform


No N/A

Platform extensions

Yes No N/A

Business Tools

Yes No N/A
Business Tools customizations and custom configuration No Yes When customer build additional configuration (implementation) in hMC or Cockpits to provide custom business logic

Custom extensions


Yes Will probably require changes to your custom code to ensure it can compile, system can start, and upgrade running system can run without errors

You can see there will still be some code changes to your source version customizations. These technical upgrades include changes to your custom code to ensure it builds/runs correctly. Even though the upgraded platform binaries may provide new functionality via changes to the API, the technical approach should not be focused on implementing new code in your solution that reuses this API to take advantage of this new functionality. Unless, there is a blocking issue that would be resolved by implementing it.

This technical approach should introduce very little technical debt. As long as your customization continues to function with the target version API and platform binaries, you aren't taking on any new technical debt. However, if a feature you implemented as part of the custom code is added to the API in the platform target version, you can potentially incur additional technical debt. Your solution should still work, but now you have customization for something that is on the platform. In this case, ayou should create a new issue and prioritize it as part of future non-upgrade projects.

Accelerator Based Solution

When your SAP Commerce instance uses an accelerator to kickstart development (most commonly in the form of the accelerators), the upgrade process with a technical approach will be slightly different from the non-accelerator based solution above. This is because code generated from an accelerator uses the version of SAP Commerce to generate the code. With each release it is possible the code generated by the template changes to introduce/remove new features. When using the technical approach for upgrading to the target version the change will be as follows:

Upgraded? Technically Migrated? Comments
Core Platform


No N/A

Platform extensions

Yes No N/A

Business Tools

Yes No N/A
Business Tools customizations and custom configuration No Yes When a customer builds additional configuration (implementation) in hMC or Cockpits to provide custom business logic

Custom extensions


Yes When a customer builds additional configuration (implementation) in hMC or Cockpits to provide custom business logic

Accelerator Storefront

No Yes Storefront is not regenerated but may need changes to ensure it compiles

Non-storefront Accelerator Extensions

No Yes There are minimal changes to non-storefront accelerator extensions, no regeneration. You may need some changes to ensure it compiles
Ported features from Target Version No No Crucial features like Security mechanisms introduced in new version of accelerator - may be ported from generated code in target version.

The accelerator storefront and related extensions are considered custom extensions and require a technical upgrade like other custom extensions to make everything build and run correctly. It is recommended to include cherry-picked code from the generated accelerator in the target version to include crucial functionality that you need (e.g. security updates). 

At the end of an upgrade project, with a technical approach for an accelerator based solution, your target system should be running the latest version. However, your Accelerator code will be based off the same as your source version. You will be able to take advantage of all the new features provided in the platform, but new features in the Accelerator would not be available. To take advantage of new features in the Accelerator go through the "Template Approach". Using the Technical Approach with Accelerator Based Solutions will probably cause some features to be ported from the target version. These are features/functionality available in the target version that are cherry-picked into your upgraded solution because they are critical to your solution. You would need to generate the same accelerator extensions in your target version and port over any features required.

Because you aren't re-creating a new accelerator extension all customized accelerator extensions, could contain technical debt. This is because the accelerator template in the target version could introduce new features and functionality that you originally had to create customized code for.

Technical Approach Steps

We recommend you do the technical approach activities similarly to a traditional waterfall methodology; Phases and tasks are done one after each other with limited parallelization possibility. That being said, there are some steps that should reoccur after each task, so we split this section into recurring and general activities.

Recurring Activities

Recurring Activities should only begin once you've upgraded code that compiles (see "General Activities" below). Depending on how complex your upgrade is you may or may not be doing these activities. It is possible the code you get to compile will be the release candidate, which means you can move to the Testing activity.

There are some activities during a technical upgrade that will continue to occur or build up through this phase. When you complete each detailed activities you should consider whether you also need to execute any of the following activities:

Regression Testing

Regression testing typically involves executing the whole suite of tests (unit, integration, UI, security, performance) against the build to ensure nothing has broken. It should run continuously as part of your build pipeline, and if any test of your potential candidate for production fails, it should not be deployed. Because regression tests can be so long and tedious they should be  automated as much as possible. This will help you cover more of your solution in a consistent and timely manner.

A full regression, even one that is automated, may be very time-consuming. If this is the case, determine if there is a smaller subset of tests in your test suite that will give you confidence in the stability of each build. For example, only run unit tests that hit an agreed upon level of code coverage, smaller set of UI tests (login, single product add to cart, anonymous checkout), etc. A full end-to-end regression would only be run against the potential release candidates and will be handled as part of the Testing activity.

In an upgrade project regression, tests are important because they make sure your existing functionality is working and nothing is broken as part of the upgrade. This means 2 things:

    • Before you start the upgrade make sure all your regression tests are completed and successful. Proceeding with broken/incomplete regression tests will make it harder to identify issues later
    • If you are enabling/porting over any new functionality from the target version make sure you create new regression tests for this functionality

Update Deployment Procedure

Every upgrade will require a minimum set of tasks that needs to be completed to move all environments from source to target version. At the very least, you will need to move your code to your servers and update the type system. Sometimes, there are additional steps prior and post-deployment of the code. Consolidate the steps into a single document that is available to all developers and the deployment team, as they arise. Here's a sample Upgrade Deployment Procedure to give you an example of what a deployment procedure should look like for an upgrade. It is split into a few sections including:

    • Pre-requisites: Do you have the correct SAP Commerce binaries on your build server? If you're using SAP Commerce Cloud, has your manifest file been updated to pinpoint all of the correct properties and configurations? Are there upgrades to any of the third party integrations or systems (DB, Java, etc.) that need to be made? Do you have the necessary artifacts? Have you considered who will be a part of the deployment? Who should be told an upgrade is going to occur? Does there need to be any messaging via social media, email, etc. prior to the start upgrade?
    • Prior to deployment: What steps need to be made before you deploy the target version of the code? This will typically include taking your site down (if applicable) and putting up a maintenance page, executing any scripts to remove types that are changing or not required, and so on.
    • Deployment: Starts with the deployment of your upgraded code and includes all the steps to upgrade your system and have it ready for final testing.
    • Post Deployment: Once all deployment steps are completed these are the steps that need to be completed to ensure the site is working correctly. From making it available to your customers to ensuring all stakeholders are aware the upgrade is complete.

By the end of the technical upgrade approach, you should have a step by step process that can be tested and executed by the deployment team.

Business Data Technical Migration

During an upgrade, your type system may change, including types/attributes being added or removed. This means you need to add/remove data, and you should account for the step(s) in your deployment procedure. This requires you to understand how your data model is changing and determine what to do with your existing data:

    • Remove the data because it is not needed
    • Move the data to a new attribute/type: Create the necessary IMPEX/Groovy/SQL scripts to move the data from one place to another
    • Create new data: sometimes you're adding a new attribute/type, which requires having the correct IMPEX/Groovy scripts or integrations in place to load the data into the created attribute/type

It is critical to document and test all data technical migration steps as early as possible, to make sure nothing is missed and the application is still functioning as expected.

General Activities

The following activities need to be completed in order to complete this phase and move into the testing phase of your project.

Configuration Technical Migration

The following is a list of configuration elements that should be investigated and if required, technically migrated during the Upgrade Project to ensure compatibility with the target version. file.

The following is the standard location of file:


Often between SAP Commerce releases the product team may remove or introduce properties into the system. New properties are required with new features in order to prevent some important system related values from being hard-coded. If a new property is introduced in the platform its key with a default value is added either to one of three places:

    • Global SAP Commerce internal property file:

    • Core-related property file:

    • Extension-related property file:


Problems may arise if the default value that was set in a particular release by Product Tea doesn’t match or interferes with your solution or its configuration. When upgrading we recommend you analyze all these files for any potential conflicts with your solution. If necessary, include the particular property key with the correct value in

localextensions.xml file

The following is the standard location of localextensions file:


This file contains the configuration of the extensions used in your solution. It contains a list of entries that describe which extension will be compiled, started with the platform, and which extension data model will be stored in the database during Update Running System process. There are many changes in this area between releases of SAP Commerce. There are several possible changes done to extensions between releases:

    • New extensions are being included into the product.
    • Deprecated extensions are being excluded from the product.
    • Business logic and data model are being moved between extensions.
    • Extensions are also being moved between modules I.e. from “ext-commerce” to “ext-backoffice."

All the above changes in the Product will probably impact the content of your localextensions.xml file

We advise the following actions be taken when upgrading:

    • Analyze the content of this file in the Planning phase of the Upgrade Project.
    • Make sure the list is ordered; extensions should be grouped by modules to make it easier to identify what is being used.
    • Remove any unused extension from solution.
    • Explicitly add extensions that are implicitly included in the solution (by requires-extension directive in extensioninfo.xml) to localextensions.xml, to have a full list of all extensions being used.
    • Analyze and list any changes in extensions between the source and target version. This step should have been done during the Planning phase, but if not, this step should be completed now.
    • Appropriate changes to localextensions.xml that reflect found changes should be introduced to this file

buildcallback.xml files

buildcallback files can be localized in an extension’s main directory. Example:


These files contain hooks for most important actions during platform build (see here for more information). Adding ant targets into a particular hook results in execution of this task before or after particular platform targets.

Buildcallbacks are present in platform extensions, but you might place your own ant targets into buildcallbacks of any custom extension.

Such ant targets may perform some platform-independent tasks, but there is always a risk the person responsible for the implementation did not follow best practices and included  actions in the buildcallbacks that hard bind to the platform. Examples include replacing particular jar files within platform binaries and deleting or including additional external files into the platform core extensions or configuration.

For buildcallbacks we recommend:

    • Review all buildcallbacks.xml files of all custom extensions.
    • Identify all customer ant targets included and what they do.
    • Assess if these actions are platform binaries related.
    • iF this is the case – actions content should be analyzed and technically migrated in order to assure that after Upgrade the result of these actions will be exactly the same in the target version.

customize folder

The customize folder should only be used for on-premise SAP Commerce solutions as it is not supported for SAP Commerce Cloud

The customize folder can be found in the following location of a typical SAP Commerce solution:


The mechanism of the customize target works like this: the contents of the customize folder are being copied onto deployed platform files starting in following directory:


This allows you to overwrite platform files and change the content of the platform binary files during the deployment. Customization is triggered by executing a standard built-in ant target (see more info here):

ant customize

This mechanism brings potential risk during Upgrade projects because the content of the customize folder was created for particular platform version, so it might not be compatible with your target version. This could result in target platform files being replaced with the customized source (old) version.

Actions required in cases where content in the customized folder is present:

    • Compare the content of the customize folder with their counterparts in source platform version.
    • Extract and understand customization (changes to platform files that were done by solution implementation team).
    • Perform a list of customization changes and consult with the implementation team of the purpose of each change (good practice).
    • Compare files that are on the customized list to see if they were changed between source and target version
    • Files that were not changed in product between source and platform version don’t require any actions
      • Files that were changed in product between source and platform version require a merge:
        - Customization (changes between original files in source version and in customized folder
        - Changes between source and target version
        - Possible removal of the customization file if the target platform files work the way you need them to

Tomcat and TcServer Configuration

Tomcat and tcServer are delivered as part of SAP Commerce product. Predefined configurations are bundled in the Product to ensure these artifacts work with SAP Commerce. During the execution of the built-in ant target:

ant clean

a few things happen. For the very first time (directory hybris/config doesn’t exist) the platform asks whether to use DEVELOP or PROD predefined version of the configuration. After choosing one option the hybris/config directory is created with default Tomcat and tcServer configurations copied (depending on the option chosen) from one of the following directories:


These predefined configurations may be further adjusted and developed, but most of it usually persists unchanged. It is important to ensure compatibility with the platform version they were generated with . Exchanging platform binaries to target version may lead to configuration errors in places where predefined configuration has been changed in target version.

Actions required:

    • Generate a set of clean predefined configurations using the source version.
    • Compare these configurations with your current configurations to identify and document what was customized.
    • Generate a set of clean predefined configurations using the target version.
    • Apply any changes from your list of customization that are still valid for your target version.

Data Model Changes

With any new version of SAP Commerce, there is the potential for data model changes like:

  • Types are added / removed
  • Type attributes/relations are added / removed
  • Type attribute modifier changes

When moving to the target version you should be aware of how the type model will affect your application. If your code or data is dependent on any of the changes, you need to plan accordingly. We recommend you either compare all the items.xml from your source version with the corresponding items.xml in the target version or review the data model changes for each version release, between the source and target versions (example). You should list out each of these changes. Once you understand the changes to the data model you'll understand how it affects your solution.

When a new type is added it will probably affect your upgrade and there is no harm having the new tables created as part of the update process. When a type is removed you need to evaluate how it affects your data requirements. Is the table that will be removed relevant to your business users reporting/metrics? Does any of the customization to your solution require data from the removed item type? If your solution is not utilizing the type then it can be removed without issue. If the data or functionality associated with the type is still being used, you can recreate the type as part of a new deployment table and technically migrate the data over or you can change the functionality to remove the dependency on the type. When a type attribute/relation is added or removed, you should ask similar questions.

As part of the upgrade deployment, we recommend you execute the steps to cleanup your type system. This makes sure you aren't storing unnecessary data in your database for removed types.

Custom Code Technical Migration

The goal of this task is to compile your solution with target platform version. When you first try to compile your code using the target version it will fail, but it's expected. The API of the target version will be different from your source version, which means you will have plenty of compilation errors to work through. Some of your existing code will need to be changed. With each released version, we include an API compatibility report that lists out all the API changes. This is a good resource, but it's easier to use a combination of your IDE and code build to identify changes to the API that prevent your code from compiling. Examples can include methods being removed, moved, or having their method signature change. Unfortunately, there is no quick way of dealing with these types of issues. They will need to be handled one by one because each issue is unique. Also, once you fix a compilation issue, other compilation issues will arise. You will find there will be a continuous fix, build, and repeat cycle untiall compilation errors are resolved.

Detailed instructions are as follows:

  1. Java Code

In order to perform custom code technical migration, you need to fix all Java compilation problems after exchanging SAP Commerce binaries to the target version. In order to make comparison easier, we recommend you set up two separate working sets (also called workspaces):

    • Original Workspace – referenced environment
    • Upgrade Workspace – working environment

The Original Workspace should contain the following elements.

    • All required platform extensions from the Source Version
    • Custom code (extensions)
    • All custom development configurations

If this workspace is properly prepared, according to your development guidelines, the following standard system operations should be possible to perform standard operations like:

    • Compile Java Custom code without compile errors.
    • Start your SAP Commerce instance using Tomcat or tcServer servlet container.
    • Perform update or initialization according to the way you have set up your working development environment.

Also, it should be possible (considering present and available integrations) to login to Storefront landing page, browse through test categories and products (considering content of essential data). You might need to use a database dump from your development environment. You should be able to perform a set of basic eCommerce operations like:

    • Add a product to cart
    • Perform checkout steps
    • Create an order in the system

It is very helpful in this step to use standard development environment setup procedure.

The Upgrade Workspace should contain following elements (and their correct locations):

    • Custom extensions in the following location:

    • Target version of the platform binaries in:

    • Target version of the platform extensions in:

    • Technically migrated configuration (see above) in:

    • Customer media files in:


Once this is complete you should be able to run from hybris/bin/platform:

ant clean

This will remove all compiled, temporary and deployed files from the SAP Commerce Suite and all extensions. It will also check if the whole extension structure is correct.

Errors may appear in this step if:

    • New SAP Commerce extensions are required by target version of SAP Commerce core or external extensions.
    • Extension hierarchy changed in target version.

In order to fix these errors you'll most likely need to make changes to your localextensions.xml and extensionsinfo.xml files (see above). Once you can successfully execute an "ant clean" execute the following ant task:

ant all

This will run a build of the SAP Commerce Suite and all extensions. It also runs the gensource ant target implicitly. Because the current custom code is not compatible with target core and external extensions, as a result of execution of this task, a list of compilation errors will be displayed.

Order of extensions which are in the build process is set based on extension hierarchy that is a result of entries in extensioninfo.xml files in required-extension tags.

The build process is trying to process given extension in build order and:

    • If no compilation errors are found - next extension in order is processed.
    • If compilation errors are found - list of compilation errors is displayed and the whole process is terminated.

Technical migration of code is about to fix compilation errors in current extension and repeat above steps for all extensions with compilation errors until whole solution is build successfully.

Consider the following list during fixing compilation errors:

    • Analyze the compiler error message
    • Locate the place in the code that the error message refers to
    • Identify the type of Java error
    • Analyze the code affected by the error and all other methods and classes that are referenced
    • Understand the root cause of the problem (this step is crucial in the process of fixing the error)
    • Based on the correct understanding of the root cause, prepare a solution from a technical migration standpoint.
    • Apply this solution to the code
    • Verify if the solution worked as expected (the compilation error is no more on the error list in the next build)

Most often, errors are caused by an API change in target platform version. If you need more information about the types of changes you can refer to the API, Data Model and Spring Changes page for each version between your source and target version. There are several kinds of API changes:

    • Method signature has changed
    • Method name has changed
    • Method was moved to another class
    • Method is deprecated or was removed
    • Method visibility has changed
    • Interface has additional method declarations
    • Class was renamed
    • Class location (package) has changed
    • Class is deprecated or was removed
    • Functional module (set of interfaces, classes or methods) was re-engineered (refactored) between the source and target version and now works in a different way. This kind of problem requires a lot of engineering time because it requires the developer to perform a reverse engineering of the module in the source version and in the target version, r to understand how it works. Based on the collected knowledge, the correct solution to the problem should be prepared.

2. Spring Context

We recommend you update your Spring context while you fix code errors (described in the previous steps). If affected classes are registered as beans, your implementation's spring context configuration should be updated to correspond with the changes to your code while getting it to run on the target version. This usually happens when:

    • Class hierarchy changes in the custom code caused by a custom code technical migration. If these classes are beans implementation – changes hierarchy should be reflected in spring beans hierarchy (changes are required in spring context configuration files). It is better to fix context configuration with fixes in code. If this is not done, context will not be initialized properly and you will see additional errors during platform startup – you'll have to come back to this problem and fix them a second time in spring.
    • Fields in java class have changed. If class is bean implementation, these changes should be reflected in bean property list

Make sure you review the Spring API changes for more details.

3. Third Party Libraries

You might need to update some of the 3rd party libraries included in custom extensions:

    • Check whether any third-party libraries you've added in your custom extensions are included as part of the target version of SAP Commerce. If it is, remove the libraries from your custom extensions, so you don't have any duplicates.
    • Whenever it is possible, update third-party libraries to the latest versions available. That way, you are taking advantage of any bug/security fixes that come with the new version of the library.

4. Integrations

Your target version could include updates to third-party libraries and integrations within the SAP Commerce platform. When upgrading to the target version you need to take into account the answers to questions like:

      • Will the version of my JVM need to be updated?
      • Do I need to upgrade my database server?
      • What changes will I need to make sure my Solr Indexing still works?
      • Will changes to any 3rd party libraries break any of my integrations (tax, payment, etc.)?

It is important to go through the Release Notes and Third Party Compatibility pages for your target version and make sure it aligns with the supported versions of all your integrations. If any of your servers need something upgraded (e.g. JVM) make sure you document it in your deployment procedure, prior to deploying the code.

5. Cherry-pick required elements

When you use a technical approach during an upgrade project of accelerator-based solutions, your custom code is being technically migrated to ensure it compiles and builds on your target version. This means, there might be functionality within the target accelerator version that is not available to you because your custom code is based on source accelerator version. There may be a desire to enable all the functionality, but this is not the main goal of the technical approach. That being said, we recommend you port certain key functionality from the target accelerator version to your custom code:

    • Performance fixes
    • Security

By porting in the code from the target accelerator version for these 2 things you are not adding any new features. Instead, you are taking advantage of the improvements to the security and stability of your application.

To achieve this execute the following:

  1. Use your source version to generate any modules you've used for custom code (e.g. accelerator, ybackoffice)
  2. Use your target version to generate any modules you've used for custom code (e.g. accelerator, ybackoffice)
  3. Perform a comparison of the output from the first 2 steps, using the diff tool of your choice. This will show you changes made by SAP Commerce between the source and target versions.
  4. Cherry-pick into your code any changes related to performance/security

Deprecation and Discontinuation


In general, if parts of the SAP Commerce  (methods, classes, extensions) are marked as deprecated, it means there's a risk that the particular part of code will be removed in the future The deprecation status is used, instead of immediately removing code, in order to provide backward compatibility and give developers time to re-engineer their custom code to make it compliant with the new standard. Typically when a part of code is deprecated a mitigation option is provided in the documentation.

The General rule for deprecated code during migration:

  • Custom code that uses deprecated API should be refactored during a migration project if possible.
  • Extensions or modules marked as deprecated should be exchanged with their replacements during a migration project, if possible.

If the above code engineering was not considered, as part of the Upgrade Project scope, we recommend you include them in the backlog in following sprints of custom code release cycle.


General upgrade procedure for discontinued extensions or modules are the following:

  • Refactor the custom code in order to use the replacement, if a replacement is available –– the migration procedure should be available on CX Works pages.
  • If there is no replacement available or the customer doesn't want to use the replacement, for business reasons– ask SAP for the source code of the discontinued extension from the last supported release.
  • Include it in your custom part and make it run on the newest commerce version.
  • Maintain this extension because it's a custom extension.

Database Upgrade

The Process

The process of updating your database is usually executed in several steps:

1)      First startup

The first startup of the platform with the upgrade custom code and configuration on the original database is very important. During the first startup, dedicated platform mechanism examine the type system within the database schema that the platform is connected to and if the platform discovers legacy parts - automated migration procedure is launched. The goal is to prepare the database for an automated migration procedure executed without errors. The following package in platform Bootstrap contains classes responsible for automated type system upgrade:

It should be considered as one unbreakable operation which is performed from the beginning to the end without errors. If errors occur during the first startup, these errors should be investigated and a database fix should be prepared. Afterwards, the database should be reverted from original database dump in order to continue.

2)    Update Running System (URS)

During the Update Running System process, the type system definitions from all extensions items.xml files are read in and the type system within the database is modified according to the type definition of all extensions items.xml files. This process should be executed during the database upgrade process, in order to reflect the changes in data model from xml files of the target version to type system in database.

3)      Orphaned type cleaner

The opposite operation of URS (which adds new elements) is cleaning orphaned types. If any item types were removed from the data model in the target platform version, we may also remove them from type system in the database.

Focus Areas

The process mentioned above lets you update your database automatically, but there are situations where platform is not able to process some changes. In such cases, manual correction to the database is required. Typically you will see indicators such as an error during first startup, running a URS, cleaning orphaned types, or stopping the process.

Places in the database that are part of type system and are potentially affected by migration:

  • attributedescriptors
  • attributedescriptorslp
  • composedtypes
  • composedtypeslp
  • maptypes
  • maptypeslp
  • collectiotypes
  • collectiotypeslp
  • atomictypes
  • atomictypeslp
  • enumerationvalues
  • enumerationvalueslp
  • metainformations
  • numberseries
  • systeminit
  • typesystemprops
  • ydeployments

In most cases you can find the cause of the problem in the areas mentioned above. Once you've located the problem apply the appropriate solution.

Missing Deployments

All itemtypes and relations should have their own deployments. If there are custom relations and itemtypes that extend directly from GenericItem and don't have dedicated deployments, their data should be migrated.

The problem with such migration is that PK of re-imported instances will change. This change is necessary because:

  • together with adding deployment to itemtype, both values must be set: tablename and typecode
  • typecode number is hashed in every instance PK.

When you change all reimported instances PKs all references to reimported instances must be updated to perceive correct relations.

Notice that adding deployment to an itemtype in items-xml file and executing URS will not change the effective type system deployment that is stored in database.

In order to do this, manual SQL script should be executed to reflect deployment changes and tell hybris platform to search data of particular itemtype in dedicated table.

Such script should update following tables:

  • composedtypes
  • ydeployments

Collection Type Relations

In older Hybris releases, there was a model of creating 1-n relations by creating:

  • collection type of given itemtype type elements
  • attribute of created earlier collection type

As in the example below:

         <collectiontype elementtype="TargetItemType" code="TargetItemTypeCollection" autocreate="true" />

<itemtype code="SourceItemType" autocreate="true" generate="true">
                 <attribute qualifier="targets" type="TargetItemTypeCollection">
                          <modifiers read="true" write="true" search="false" optional="true" />

The above model was replaced during a time with dedicated definitions in items.xml of 1-n relations as in example below:

In all cases where in custom code collection based relations are found, it is advised of refactoring of collection based relations to 1-n relations. There are following reasons:

  • performance
  • keep existing data model close to the standard

The reason why collection based relations may have impact on the performance is the database representation of relation referencing data.

Collection based relations are in fact attributes of collection type. They are stored in database as a String that contains comma separated PK list (See Figure 1). On the other hand, hybris 1-n dedicated relation types use only PK number references. They are stored in database as separate records on n-end of the relation. There is a dedicated reference column containing PKs that point to entity on 1-end of relation (See figure 2).

Second solution database representation is more efficient and suggested as best practice that may improve performance of the solution.

Figure 1


Once you've finished all the activities of Upgrade Engineering you should have code and deployment instructions that are ready for more extensive testing. For more information, please view Testing.