Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Upgrading Elastic Path

Upgrading Elastic Path

This document provides generic instructions to upgrade a version of Elastic Path Commerce to a newer version of Elastic Path Commerce. However, this document does not provide step by step instructions to upgrade your Elastic Path software. Depending on your environment, data, and customizations you've made to Elastic Path Commerce, you might have to perform additional tasks before or after the upgrade.

The upgrade process consists of three phases:
  1. Preparation: Gathers information about your known customizations and decide how you want to mitigate your risks.
  2. Customization Analysis (Optional): Analyzes and determine what customizations you've made. This optional phase is for organizations who don't know what customizations have been made to the platform.
  3. Upgrade: Performs the upgrade to a newer version of Elastic Path Commerce.
Elastic Path recommends maintaining a working IDE & environment for the old version during the upgrade. This supports comparing functionality of the old code with the new code in a debugger.

Preparation

The preparation phase involves gathering information and mitigating risks before performing the upgrade. The following diagram shows an overview of the preparation process:

  1. Identify customizations: Create a list of all known Elastic Path platform customizations. If you don't know your Elastic Path platform customizations, see Customization Analysis and reverse engineer the code to find them.
  2. Determine versions: Get the appropriate source code for your upgrade.
  3. Identify modernizations: Do the following:
    • Review the documentation and technology stack for the new version of Elastic Path.
    • Review the Elastic Path Release Notes, for the current version of Elastic Path and for all versions until the version you are upgrading to, for bug fixes, new features, new technologies, code changes, or deprecations.
  4. Identify a regression test strategy: Identify customizations that lack written or automated test cases.
  5. Reduce risk where possible: Do the following:
    • Address the risks found during the Customization Analysis.
    • Improve test coverage.
    • Refactor code.
    • Provision the resources that require time to arrange ahead of time, such as new hardware or training.
    • Defer upgrades of independent systems (scope reduction).
  6. Train the team on new version: Create a training plan using the list at Identify modernizations to train the team on new technologies, if any.
  7. Identify components to upgrade: Identify the minimum set of components or dependencies that must be upgraded. Hosted infrastructure might need to be upgraded for the new Elastic Path platform.

Customization Analysis (Optional)

Customization analysis helps you derive a complete list of the customizations that are made to your organization's platform in a time-boxed investigation. This section focuses on the completeness of the list, not on the detailed understanding of each customization.

  • Apply reverse engineering patterns: Reverse engineering is a general software engineering practice. For more information, see Reverse Engineering in Chapter 2 Object-Oriented Reengineering Patterns at http://scg.unibe.ch/download/oorp.
  • Identify risks in the source code: Record the following problems if you find them while examining the source code:
    • No test coverage
    • Code smells
    • Cross-cutting concerns
  • Identify risks in the infrastructure: Record the following problems if you find them while examining the environment installation, build, deploy, and release processes:
    • No Continuous Integration
    • Manual deploy or release process
    • Lack of staging environments
  • Prepare upgrade action list: Arrange the unorganized list of features or customizations for one of the following upgrade actions:
    • Upgrade feature as-is
    • Problematic feature implementation that requires reimplementation
    • Implement a new feature using functionality in a newer version of Elastic Path Commerce
    • Remove unused code or feature

Upgrade

Workflow

Upgrading breaks the application for an extended period of time, so a normal workflow that includes QA is not possible until the upgrade is complete. Upgrade projects must transition between a normal and upgrade-specific workflow as in the following diagram:

The upgrade-specific workflow consists of the following issue transitions:

To Do > In Progress > Ready for Peer Review > In Peer Review > Done

Elastic Path recommends separating the upgrade backlog from other development projects. Derive a list of backlog items from the above time line diagram. JIRA users can use the simplified workflow for its easy workflow customization.

Upgrading Elastic Path Source Code
  1. Replace the customized source code in version control with the new Elastic Path release version.
  2. Apply available patches. For more information, see Elastic Path Support Portal.
  3. Reversion the code if required. For more information , see Updating Version Numbers.
  4. Commit the changes.
Upgrading Database
Liquibase manages upgrading database to newer versions. You must add the upgrade-related data fixes in an XML changelog at extensions/database/ext-data/src/main/resources/schema.
  1. Get a copy of the production database for testing the upgraded schema and data:
  2. Perform sanitization of data, which is deleting personal information, security credentials, and environment-specific data, such as URL's, IP addresses.
Warning: When upgrading database, ensure that database is offline. This causes downtime during the release.
Troubleshooting common data upgrade errors

  • Delete transient data, such as shopping carts and customer sessions, if it is problematic to migrate.
  • Enable the Elastic Path database clean-up jobs if disabled.
Extracting customizations
Elastic Path recommends creating a patch file containing the customized code.
  1. To create a path file, port the customizations between two versions by applying the patch to the source code's target version.
    1. Arrange the source code for each version of Elastic Path into two directories for each version, one for customizations and one for unmodified Elastic Path source code. For example, upgrading from Elastic Path Commerce 6.7 to 6.14 needs, "/commerce-legacy/ep6.7-original", "/commerce-legacy/ep6.7-custom" "/commerce-legacy/ep6.14-original", and "ep6.14-custom" folders.
    2. Remove unwanted files and build artifacts from the source folders.
    3. Break large patches into smaller patches and put them in your issue tracker.
  2. Run the following command to compare the code in the directory /a and /b, and extract the customizations in the directory /b in to a patch file: 
    diff -U 3 --ignore-all-space --recursive --unidirectional-new-file /a /b > all-customizations.patch
    Following is an example is for an upgrade without reversioning changes:
    diff -U 3 --ignore-all-space --recursive --unidirectional-new-file -I '<version>version number\.0\.0' -I 'Bundle-Version: version number\.0\.0' -I 'version=\"version number\.0\.0' /a /b > all-customizations-without-reversioning.patch
    Replace version number with the current version.
  3. Verify the diff command output by comparing the current and prior diff files each time you modify the arguments.
Re-apply customizations

Elastic Path recommends applying small patches with an IDE GUI-based patch tool. You can also use a three-way merge tool, such as P4Merge or KDiff3. Elastic Path does not recommend using rudimentary patch commands.

The Eclipse Apply Patch Wizard addresses inconsistent nesting depth with the ignore leading path segments feature.

Troubleshooting Guide

Resolving Ehcache diskPersistent Error

Elastic Path Commerce 7.3 and later versions do not support using diskPersistent="false" for default caching. When you upgrade Elastic Path Commerce to 7.3 or a higher version, you might get an ehcache diskPersistent error.

To resolve the error:
  1. In the command line, navigate to the extensions/database directory and run:
    mvn clean install -Preset-conf