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.

What's New for Elastic Path Commerce 7.0.0

What's New for Elastic Path Commerce 7.0.0

Release Highlights

Elastic Path Commerce 7.0.0 improves system administration and system security. The highlights of the release include:

  • Web based administration: The Elastic Path Commerce admin interface is now web-based, and we have retired the Commerce Manager thick client. This change provides the obvious benefit of not having to download an application to administer Elastic Path Commerce, as well as providing an improved user interface, better performance, test automation and faster development.
    Note: In developer documentation, the administration interface component will continue to be called the Commerce Manager.
    Warning: Reports are not available in this release. They will be included in Elastic Path Commerce 7.1.
  • Enhanced security and code quality:
    • Elastic Path Commerce source code is now analyzed by SonarQube for security and quality on every commit.
    • All identified security vulnerabilities were addressed, and many quality improvements were made.
  • Improved scalability: Quartz jobs that were previously in the CM Server were moved a new Batch server to allow horizontal scaling of the Commerce Manager and to ensure that batch processing does not impact Commerce Manager responsiveness.
  • Development improvements:
    • Support for configuring external authentication providers was added to the Commerce Manager.
    • New order states and events were added to minimize the customization required to implement order review processing.
    • The Cortex /wishlists and /registrations resources were converted to the Helix programming model, and several improvements were made to Helix to simplify development.
    • Support for running the Data Sync Tool from a web app was implemented. This enables the implementation of event-driven data synchronization from authoring to live environments.
  • Documentation and training improvements:
    • A new sample-data project was created to facilitate learning and training.
    • The Developer Center was restructured to improve navigation and searching of product documentation.
    • Tutorials were added for extending and creating Commerce Manager plugins.

System Requirements and Compatibility

The system requirements are documented at System Requirements.

Elastic Path Commerce 7.0.0 is compatible with the following:

Elastic Path Component Version Location Branch or Filename
Elastic Path CloudOps for AWS 2.0.x code.elasticpath.com release/2.0.x
Elastic Path Commerce Demo Package 7.0.0 support.elasticpath.com EP-Commerce-Demo-7.0.0.zip
Elastic Path Commerce for Adobe Marketing Cloud 1.6 support.elasticpath.com EP-Commerce-for-AMC-1.6.0.zip

Functional Changes

Core Commerce

  • PB-2126 - Expanded order states and events. See the upgrade notes below.
  • PB-2166 - Removed Product Type and Category Type templates. See the upgrade notes below.
  • PB-2169 - Removed image and asset management. See the upgrade notes below.
  • PB-2269 - Added two capabilities to support enhanced change set import processing in the Data Transfer Accelerator Kit - the ability to set an auto-publish flag when importing a change set, and a new query to find existing change sets by state and name.
  • PB-2270 - Refactored the Data Sync Tool into separate core and CLI modules to support event-driven change set publication by the Data Transfer Accelerator Kit.

Cortex API

  • PB-2040 - Implemented support for adding configurable items to wish lists and moving the items between the cart and wish lists.
  • PB-2170 - Removed the /assets resource. See the upgrade notes below.

Commerce Manager

  • PB-2149 - Added support for replacing the default EP authentication provider with an external authentication provider .
  • PB-2178 - Updated subject and body text for Commerce Manager user email messages (new account, password reset, password change)

Development Changes

Core Commerce

  • PB-1992 - Removed extensibility-tests module from the extensions project. This module is for internal product testing and is not useful for project teams.
  • PB-2155 - Removed Quova GeoIP plugin from commerce-engine. Specific vendor integrations do not belong in the core product, but should be implemented as accelerator kits instead.
  • PB-2178 - Removed unused assets and Velocity templates/macros from the extensions/ext-assets module.
  • PB-2196 - Added frequency based products to ep-mobee-demo-data module to support new Cortex system tests, and disabled them in the ep-snapitup-demo-data module.
  • PB-2210 - Removed AEM dependencies from the deployment package and the Pusher. See the upgrade notes below.
  • PB-2256 - Moved Quartz jobs from the old cmserver to the new batch server. See the upgrade notes below.
  • PB-2278 - Accessing an unloaded JPA field will now throw an IllegalStateException. This is useful in development to identify fields missing from JPA fetch plans.
  • PB-2323 - Upgraded ActiveMQ to 5.14.3. See the upgrade notes below.
  • PB-2413 - Removed ep-cryptotool.
  • PB-2432 - Added a new sample-data module to the commerce-data project and included into the default local data population configuration. See the upgrade notes below.
  • PB-2446 - Removed unused system settings. See the upgrade notes below.
  • PB-2474 - Removed references to unsupported webservers from POMs.
  • PB-2732 - Renamed the cmclient project in the release package to commerce-manager.
  • PB-2927 - Modified versioning of Elastic Path projects. See the upgrade notes below.

Cortex API

  • PB-2147 - Converted the /wishlists resource to the Helix programming model. See the upgrade notes below.
  • PB-2212 - Added link from root to shopper's default wishlist and exposed this in Cortex Studio.
  • PB-2244 - Expanded filter for request scope caching to support instrumenting extension packages as described in the Cortex Caching section in the Cortex Caching.
  • PB-2246 - Removed create(E entity) and findAll() methods from Repository.java as they have been replaced with methods that take scope as a parameter.
  • PB-2255 - Eliminated supportTypes method from Repository and CollectionRepository interfaces. See the upgrade notes below.
  • PB-2327 - Enabled request scope caching of RxJava results in repository classes as described in Cortex Caching.
  • PB-2332 - Improved Cortex exception handling. See the upgrade notes below.
  • PB-2378 - Updated the Cortex Java SDK to return structured errors on all Cortex calls.
  • PB-2666 - Enabled injection of repositories into Helix prototypes using annotations. See the upgrade notes below.

Commerce Manager

  • PB-2756 - Upgraded Eclipse Tycho to version 1.0.0 to support offline builds.

Security Fixes

Core Commerce

  • PB-2280 - Fixed Improper Output Neutralization for Logs vulnerabilities by removing unnecessary logging and sanitizing logging output using the ESAPI log wrapper in the Cortex ExceptionTranslatingFilter.
  • PB-2335 - Removed obsolete Google Checkout code and libraries to address a potential security vulnerability in the google-checkout library.
  • PB-2414 - Fixed Path Traversal vulnerabilities by removing Utility.getLocalizedFile and FileDownloadService which are no longer used.
  • PB-2814 - Mitigated Cross Site Scripting (XSS) vulnerabilities in Pusher deployments by setting httpOnly for Tomcat cookies.

Bug Fixes

Core Commerce

  • PB-2029 - A ConcurrentModificationException occurred intermittently when formatting email messages with Velocity.
  • PB-2267 - Cortex Cucumber tests did not always shut down properly.
  • PB-2323 - The ActiveMQ admin console didn't work with Java 8. Fixed by upgrading ActiveMQ to 5.14.3.
  • PB-2341 - Linked categories were not synchronized by the Data Sync Tool (CUST-1184).
  • PB-2525 - ActiveMQ web console wasn't accessible.
  • PB-2860 - Adding a coupon to a public cart added the coupon to all subsequent public carts (CUST-1207).

Cortex API

  • PB-1485 - The wishlist movetocartaction did not redirect to the cart.
  • PB-2180 - Cortex Studio request headers were not cleared when pressing the "X" buttons.
  • PB-2208 - Attempting to load a JAR that is not an OSGi bundle generated a NullPointerException instead of logging a meaningful error.
  • PB-2491 - The Cortex webapp would occasionally start in an invalid state that caused all batch item lookups to fail with a ClassCastException (CUST-1192).
  • PB-2766 - A structured error was not returned when making a purchase and a required customer profile attribute is missing.

Commerce Manager

  • PB-2330 - Newly created linked categories did not have an object name when added to a change set (CUST-1198).
  • PB-2734 - Exchange functionality was disabled if a payment token was used for the original purchase.
  • PB-2777 - Adding a new category type to a change set failed with a null pointer exception.
  • PB-2837 - The list of objects in a change set did not include objects that were added to the change set and then deleted.
  • PB-2862 - Creating a global catalog attribute failed with a null pointer exception when change sets were enabled.
  • PB-2904 - An IndexOutOfBounds exception occurred when creating a shipping promotion for a store without defined shipping service levels.

3rd Party Library Changes and Upgrades

Library New Version Previous Version
Apache ActiveMQ 5.14.3 5.11.1
Apache Commons Pool commons-pool2-2.4.2 commons-pool-1.6
Apache Tomcat (CloudOps for AWS) 7.0.75 7.0.65
Eclipse Tycho 1.0.0 0.26.0
Oracle JDBC driver ojdbc7-12.1.0.2.0 ojdbc6-11.2.0.2.0
RxJava 1.2.4 1.1.6
Servlet API 3.0.1 2.5

Upgrade Notes

The Upgrade Guide provides general advice on upgrading Elastic Path projects. Specific upgrade considerations for Core Commerce 7.0.0 and Cortex API 7.0.0 are covered below:

New web based administration

A new based web administration interface replaces the Commerce Manager Client desktop application. The Commerce Manager was ported from Eclipse RCP (Rich Client Platform) to Eclipse RAP (Remote Application Platform) which renders a web based interface. The underlying Commerce Manager code base is fundamentally the same as before, but required multiple enhancements to adapt it to a web-based multi-user environment, implement an extension model and support Selenium test automation.

Some of the most significant structural changes are:
  • The cmclient project was renamed to commerce-manager and reorganized:
    • Plugins were moved to a cm-plugins sub-module
    • The com.elasticpath.cmclient.libs and com.elasticpath.cmclient.testlibs modules were moved from extensions
    • A cm-invoker module was added to support building the mixed Maven/Tycho project as a single Maven reactor.
    • A new com.elasticpath.cmclient.docs module contains the user manual which is authored in markdown and converted to HTML
  • A new cm module was added to the extensions project that supports:
    • An extension model for project customizations (ext-cm-libs and ext-plugins)
    • A horizontally-scalable web application (ext-cm-webapp)
    • Cucumber + Selenium system tests (system-tests)
    • A single Maven reactor for both Maven and Tycho modules (ext-cm-invoker)

The key deployment changes are:

  • The new cm web application is horizontally scalable behind a load-balancer configured with sticky sessions
  • FTP/SFTP is no longer utilized
  • And, of course, there is no desktop application to deploy

The Cucumber + Selenium tests require a deployed CM server instance when run as part of the CI pipeline. The CM server needs to be run with a JVM parameter of -Dorg.eclipse.rap.rwt.enableUITests=true which activates special non-production logic that generates stable object identifiers (test-ids) used by the test scripts.

When upgrading:

  • Spend the time to understand the options and strategies for porting customizations and extensions to the new model as described in the Upgrading Commerce Manager section.
  • Remember that the cmclient, cmserver and extensions/cmserver modules have been extensively refactored.
  • Update your CI pipeline to accommodate the special requirements of CM system tests. One strategy is to deploy a Dev environment with test-ids enabled, and all other environments with test-ids disabled.
  • Make sure all deployment environments are updated:
    • For Pusher deployments, add cm server configuration to all Pusher conf files.
    • For CloudOps deployments, EP CloudOps for AWS 2.0 is required to deploy the new cm server.

New batch server webapp

A new batch server webapp was introduced in this release to provide a single-instance server for batch processing. All Quartz jobs that cannot be scaled horizontally were moved from the CM server to the batch server. Jobs related to CSV import processing and cleanup were not moved.

Repetitive logging in the batch server was changed from INFO to DEBUG level to avoid log pollution.

When upgrading:

  • Make sure all deployment environments are updated.
    • For Pusher deployments, add batch server configuration to all Pusher conf files.
    • For CloudOps deployments, EP CloudOps for AWS 2.0 is required to deploy the batch server.
  • Any customizations or extensions to CM server Quartz jobs will need to be migrated to the batch server.

Changes to build environment

Several changes were made that affect the build environment.

  • The overall build sequence has changed.
    • The commerce-manager project now needs to be built before extensions.
    • The deployment package can now be created as part of the extensions reactor instead of in a separate step.
  • Special invoker modules are required to orchestrate building Tycho modules within a Maven reactor:
    • For the commerce-manager project, you need to build commerce-manager/cm-invoker.
    • For the extensions project, you need to build extensions/cm/ext-cm-invoker.
Warning: Multi-threaded builds will not work for reactors that contain Tycho invoker modules, i.e. commerce-manager and extensions.
When upgrading:
  • Modify your build environment to reflect these changes. See Setup CI Server for more information.

Changes to versioning

The following changes were made to project and artifact versioning.

  • As a result of combining Tycho and Maven builds into a single reactor, the extensions project now requires a snapshot version of 0.0.0-SNAPSHOT instead of 0-SNAPSHOT.
  • Elastic Path product artifacts that are consumed as binary dependencies have an additional 5 character commit hash at the end of the version number, e.g. cortex 1.18.0.20170628004753-c02e8. See README.txt in the source distribution zip file for a list of artifact versions.
  • Cortex API modules that are included in the source distribution now have the same major version number as commerce-engine (i.e. 7.0.0). Cortex binary components continue to be versioned independently (i.e. 1.18.0)
  • Cortex documentation is no longer versioned separately from the rest of Elastic Path Commerce to make it easier to filter search results.

When upgrading:

  • Reversion extensions to 0.0.0-SNAPSHOT.

New order states and events

Orders are now created in an ORDER_CREATED state instead of IN_PROGRESS. This makes it easier to introduce custom order review processing.

By default, orders are automatically transitioned to an IN_PROGRESS state by the InitiateFulfilmentCheckoutAction to maintain backward compatibility with previous releases. Project teams should modify or remove this checkout action if they are implementing order review processing.

Three new order events have been introduced:
  • ORDER_HELD - when an order transitions to an ONHOLD state
  • ORDER_CANCELLED - when an order transitions to a CANCELLED state
  • ORDER_RELEASED - when an order transitions to an IN_PROGRESS state

When upgrading:

  • If you have customized order states or events, you may need to remove or modify your customizations based on the new order states and events. See Order States and Asynchronous Processing for more information.

Converted /wishlists and /registrations resources to Helix

The Cortex /wishlists and /registrations resources were converted to the Helix programming model.

When upgrading:

  • If you have extended these resources, you will need to convert your extension code to the Helix programming model.
  • The associated repositories were refactored to return RxJava results. This refactoring may impact custom resources that depend on these repositories.

Used annotations to inject repositories into Helix resources

The @ResourceRepository annotation is now used to inject repositories into Helix resources. The RepositoryRegistry and manual repository wiring in Helix prototypes have been removed.

When upgrading:

  • Convert all your customized Helix resources to use the @ResourceRepository annotation to inject repositories.

Improved Cortex exception handling

  • The Helix runtime now handles exceptions that implement the StructuredErrorMessageException or InvalidBusinessStateException interfaces. These exceptions don't have to be caught by application code and manually transformed to structured errors.
  • Legacy resources still need to catch exceptions and transform them into structured messages. This is done using a new ExceptionTransformer class, instead of using ExecutionResultFactory.

When upgrading:

  • Upgrade exception handling as needed.

Eliminated supportsTypes method from repository interfaces

The supportsTypes method was removed from the Helix Repository and CollectionRepository interfaces because the underlying functionality can be implemented using reflection rather than requiring explicit code.

When upgrading:
  • Remove implementation and usage of the supportTypes method from your extension Helix repositories and resources.

Upgraded ActiveMQ

Apache ActiveMQ was upgraded to version 5.14.3. The new version includes Java 8 compatibility and critical bug fixes.

The updated version of ActiveMQ is included in the extensions deployment package and in EP CloudOps for AWS 2.0 deployments.

When upgrading:
  • Make sure all deployment environments are updated.

Upgraded Tomcat

Apache Tomcat was upgraded to version 7.0.75 for EP CloudOps for AWS 2.0 deployments. Version 7.0.65 is still a supported version and is used for Pusher deployments.

When upgrading:
  • There are no changes required for Pusher deployments.

Removed Product Type and Category Type template fields

The Product Type and Category Type template fields were removed from the database schema. These fields were previously used by the Velocity storefront to specify the front-end template to be used, and have no functional purpose in an API-driven architecture.

For backward compatibility, the Import/Export tool will continue to accept a <template> element in import XML files.

When upgrading:

  • No changes should be necessary.

Removed image and asset management

The Velocity storefront previously depended on images that were defined in the catalog and dynamically resized and delivered at runtime. The Commerce Manager Client had the ability to upload and manage catalog images and assets. These capabilities are not appropriate for an API-driven architecture, where images and assets are best managed in a Digital Asset Management (DAM) system, and delivered via a Content Delivery Network (CDN).

Images can still be defined for categories, products and SKUs using image attributes.

The following functionality was removed:

  • All Commerce Manager user interface elements related to image and asset management, except for image attributes for categories, products, bundles and SKUs.
  • All server-side functionality related to image and asset management.
  • Export of the following elements in the Import/Export tool. Note that the corresponding fields have not been removed from the database schema.
    • Product <image>
    • SKU <image>
    • SkuOptionValue <image>
    • Brand <image>
  • For backward compatibility, the Import/Export tool will continue to accept these <image> elements in import XML files.

When upgrading:

  • No changes should be necessary, unless customizations make use of any of the removed functionality.

Removed Cortex /assets resource

The Cortex /assets resource was removed because it depended on server-side image and asset management.

When upgrading:
  • No changes should be necessary.

Removed unused settings

The following unused system settings were removed from the database:

COMMERCE/APPSPECIFIC/RCP/updateSiteEnabled
COMMERCE/APPSPECIFIC/RCP/updateSiteHomebase
COMMERCE/APPSPECIFIC/RCP/ASSETS/vfsProtocol
COMMERCE/APPSPECIFIC/RCP/ASSETS/vfsHost
COMMERCE/APPSPECIFIC/RCP/ASSETS/vfsPort
COMMERCE/APPSPECIFIC/RCP/ASSETS/vfsUsername
COMMERCE/APPSPECIFIC/RCP/ASSETS/vfsPassword
COMMERCE/APPSPECIFIC/RCP/ASSETS/vfsRootpath
COMMERCE/STORE/restrictedAccessPasscode
COMMERCE/STORE/seoEnabled
COMMERCE/STORE/ASSETS/assetServerBaseUrl
COMMERCE/STORE/AUTOCOMPLETESEARCH/enable
COMMERCE/STORE/AUTOCOMPLETESEARCH/enablePrice
COMMERCE/STORE/AUTOCOMPLETESEARCH/enableThumbnail
COMMERCE/STORE/AUTOCOMPLETESEARCH/numberOfResults
COMMERCE/STORE/AUTOCOMPLETESEARCH/productDescriptionMaxLength
COMMERCE/STORE/AUTOCOMPLETESEARCH/productNameMaxLength
COMMERCE/STORE/POWERREVIEWS/powerreviewsEnabled
COMMERCE/STORE/POWERREVIEWS/powerReviewsMerchantid
COMMERCE/SYSTEM/assetHttpHost
COMMERCE/SYSTEM/storeCustomerCreditCards
COMMERCE/SYSTEM/urlRewriteConfig
COMMERCE/SYSTEM/userMaintainMode
COMMERCE/SYSTEM/ASSETS/imageAssetsSubfolder
COMMERCE/SYSTEM/ASSETS/digitalGoodsAssetsSubfolder
COMMERCE/SYSTEM/ASSETS/dynamicContentAssetsSubfolder
COMMERCE/SYSTEM/ASSETS/storeAssetsSubfolder
COMMERCE/SYSTEM/ASYNC/ThreadKeepAlive
COMMERCE/SYSTEM/ASYNC/ThreadMaxPoolSize
COMMERCE/SYSTEM/ASYNC/ThreadPoolCoreSize
COMMERCE/SYSTEM/ASYNC/ThreadQueueSize
COMMERCE/SYSTEM/EMAIL/emailCmUrl
COMMERCE/SYSTEM/IMAGES/dynamicImageSizingNoImage
COMMERCE/SYSTEM/IMAGES/dynamicImageSizingJpegQuality
COMMERCE/SYSTEM/GEOIP/enable
COMMERCE/SYSTEM/GEOIP/QUOVA/onDemandEndpointUrl
COMMERCE/SYSTEM/GEOIP/QUOVA/Password
COMMERCE/SYSTEM/GEOIP/QUOVA/Username
COMMERCE/SYSTEM/URLREWRITE/fieldSeparator
When upgrading:
  • You are not required to remove any of these settings definitions from your project's system_configuration.xml import files, but may wish to do so as a cleanup task.

Modified project versioning

The following changes were made to versioning of Elastic Path projects:

  • The snapshot version for extensions must now contain major, minor and incremental version numbers, e.g. 0.0.0-SNAPSHOT. This is a restriction imposed by Tycho now that Commerce Manager extension modules are included in the extensions reactor.
  • cortex-ep-integration now has the same product version as commerce-engine. Cortex and Helix components that are released as binary artifacts continue to have individual product versions.
  • All product version numbers now contain a git commit hash after the timestamp, e.g. 700.0.0.20170623012031-92b29. This ensures there is no ambiguity in references to product artifacts.

When upgrading:

  • Remember to reversion your extensions project to 0.0.0-SNAPSHOT.
  • Product versions in custom POMs may need to be updated.
  • The README.txt file in the source distribution package has a full list of version numbers for your reference.

Added sample-data module to commerce-data project

The new sample-data module is included in by default local data population configuration. The goal of the new sample data is to facilitate the learning and training process by using self-documenting names for business objects. The previously provided demo data modules required intimate knowledge of the products, promotions, catalogs, etc. in order to find business objects with a specific set of characteristics. So, instead of having to remember that "Finding Nemo" is multi-sku product, now you can simple search for products with "MultiSku" in their name.

When upgrading:

  • Ensure that the liquibase.contexts property in your extensions/ext-data/.../environments/local/data-population.properties includes the desired data sets for your project environment.
  • If you include sample-data, you will need to rebuild your database as described in Populate the Database.

Removed AEM dependencies

Elastic Path Commerce is a front-end agnostic product and should not contain dependencies for any front-end components. Consequently, AEM dependencies were removed from the deployment package and Pusher scripts. The Starting Construction Guide was also updated to remove all AEM references.

When upgrading:

  • If applicable, make sure your existing AEM build and deployment processes are not affected by these changes.