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 6.17.0

What's New for Elastic Path Commerce 6.17.0

Release Highlights

Elastic Path Commerce 6.17.0 includes the following new features:

  • Configurable products let catalog managers define products that require shoppers to provide additional information when adding an item to their cart. Fields are configured at the product type level, with the catalog manager able to define field name, type and validation rules for each field. The definition can be done using either the Commerce Manager or the Import/Export Tool. Configurable products provide business flexibility and reduce implementation effort for this common business requirement. Electronic gift certificates are now modeled as configurable products.
  • The Helix programming model simplifies hypermedia API development and reduces project cost and time to market. Rapid API prototyping is enabled through the hot-deployment of Helix bundles into a running Cortex webapp. The easy to understand programming model allows developers to be onboarded quickly, and extensive documentation with working code examples provides hypermedia patterns and best practices for projects to leverage. Resources developed using previous programming models continue to be supported and can interoperate with Helix resources.
  • Dynamic fields allow the definition of Cortex entity and form fields at runtime. This is an essential capability when API fields are not known at design time, and was used to implement configurable products.
  • Cortex structured messages provide the abililty to return JSON-encoded error and informational messages. The representation of blocking conditions has been generalized and is intended to eventually replace needinfo. In the interim, a compatibility flag can be set to convert blocking conditions to needinfo links. All Cortex forms have been converted to return structured messages for validation errors.
  • Helix advisors provide the hooks for triggering structured messages and blocking conditions after resources are read and before they are updated.
  • A new tutorial model improves self-learning, concept retention and referencability of tutorial content. Concepts are first explained based on working code examples. Practical excercises along with working answers allow students to solidify their understanding and verify their work. Two educational repositories are available on the Elastic Path GitLab site at
    • helix-patterns contains comprehensive examples of hypermedia patterns implemented with the Helix programming model.
    • ep-commerce-examples-6.17 contains examples of extensions that are commonly performed by project teams. New tutorials will be added as they become available.
  • Developer improvements include new extensions/core/ext-core-itests and extensions/cortex/repositories modules and improved extensibility of product associations in Import/Export.

Documentation and Training

The following documentation and training resources were added or extended in this release:

Topic Resources
Configurable products
  • The Creating a Configurable Product section of the Commerce Manager User Guide.
Electronic gift certificates
  • The Gift Certificates section of the Commerce Manager User Guide.
Helix programming model
  • The helix-patterns GitLab repository describes hypermedia API development using Helix.
  • The ep-commerce-examples-6.17 GitLab repository contains examples of creating a new Helix resource and extending an existing one..
  • The API Development Programming Guide has been reworked to focus on developing Helix resources. Refer to previous versions of the documentation for resource development using the legacy programming model.
Dynamic API fields
  • The Dynamic Fields section of the API Development Programming Guide describes how to define and implement dynamic fields.
Structured messages and Advisors
  • The Structured Error Messages section of the API Development Programming Guide describes how to return structured error messages.
  • The Advisors section of the API Development Programming Guide describes how to implement Advisors and return the results as structured messages.
  • The Structured Messages section of the Touchpoint Development Guide describes how to handle structures errors returned on Cortex responses.
Source code organization
  • The Starting Construction Guide was updated to reflect that most projects are now organizing source code in a single source repository rather than using multiple repositories.
AWS deployment

Functional Changes

Core Commerce

  • PB-1914 - Introduced an InvalidBusinessStateException interface to mark service exceptions to be surfaced as structured errors in Cortex.
  • PB-1916 - Added configurable products core functionality.
  • PB-1950 - Added support for purchasing electronic gift certificates that are defined as configurable products.
  • PB-2041 - Added a constraint validator for email addresses.
  • PB-2083 - Added support to all applications for configuration files in ${user.home}/ep/conf or /ep/conf.

Cortex API

  • [Multiple] - Added support for Helix programming model and API advisors.
  • PB-1886 - Added support for dynamic form fields.
  • PB-1914 - Added support for surfacing InvalidBusinessStateException as structured errors.
  • PB-1917 - Added configurable item fields to add to cart form.
  • PB-1935 - Moved validation of profile, registration, email and address resource fields from Cortex to the commerce engine service layer.
  • PB-1969 - Added configurable item fields to purchases resource.
  • PB-2023 - Added display of structured errors to Cortex Studio.
  • PB-2055 - Prevented items with configurable fields being added to wish lists. This restriction will be removed in a future release.
  • PB-2083 - Added support for Cortex configuration files in ${user.home}/ep/conf/cortex or /ep/conf/cortex.

Commerce Manager Client

  • PB-1918 - Added configurable products support.

Development Changes

Core Commerce

  • PB-1941 - Moved the integration server's application name definition to serviceIntegration.xml to be consistent with other web apps.
  • PB-1982 - Improved extensibility of product associations in Import/Export.
  • PB-2019 - Added a core/ext-core-itests module to the extensions project for extension core integration testing.
  • PB-2011 - Changed the default payment processor from DemoPaymentProcessor to DemoTokenPaymentProcessor on multiple stores so that Cortex payments work with all demo stores.

Cortex API

  • PB-1964 - Corrected API definitions for multiple resources to fix issues detected by improved API validation logic.
  • PB-2020 - Added a cortex/repositories module to the extensions project for repository extension code.
  • PB-2067 - Converted the profiles resource to the Helix programming model.
  • PB-2130 - Removed Cortex resource archetypes. Use the examples in as the basis for creating Cortex modules.
  • PB-2152 - Converted Cortex authentication integration modules to use Declarative Services instead of Blueprint.

Bug Fixes

Core Commerce

  • PB-1942 - SettingValueBackedPredicate did not reflect changes to underlying settings values.
  • PB-1993 - Localized attribute values were not correctly exported if the locale contained a country code (e.g. en-US).
  • PB-2008 - Extension system tests were not using the extended schema defined in schema-customizations-changelog.xml.
  • PB-2117 - Integration server in webapp-smoketests module was not shutting down properly.
  • PB-2123 - The data population tool failed to create the schema for SQL Server 2014 databases.

Cortex API

  • PB-1815 - Entities that extend entities containing entities from other bundles could not be instantiated in Cortex at runtime
  • PB-2012 - Nested zooms didn't work in Cortex Studio Quick Links.
  • PB-2048 - An NPE was thrown when accessing StoreProductRepository with an invalid identifier.
  • PB-2117 - Cortex system tests did not always shutdown correctly because of Fixed by downgrading ActiveMQ Maven plugin version to 5.9.0 for Cortex Cucumber tests only.
  • PB-2129 - UriPartTransformers were not visible in the OSGi console.
  • PB-2142 - The @PostConstruct annotation caused deployment failures in some environments.

3rd Party Library Changes and Upgrades

Library New Version Previous Version

Upgrade Notes

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

Structured messages

Cortex now returns Structured Messages for field validation errors and business state errors on POST and PUT actions instead of returning unstructured error messages.

Note that no blocking conditions are currently being returned as structured messages. These will be introduced as additional resources are converted to Helix.

When upgrading:

Profiles resource

The profiles resource was converted to the Helix programming model.

When upgrading:

Gift certificates

Electronic gift certificates can now be defined as configurable products. Gift certificate configuration is documented in the Commerce Manager User Guide. You can also search for "giftCertificate_Mobee" in the commerce-data project for an Import/Export XML example..

When upgrading:

  • If you have a custom gift certificate implementation, you may want to consider converting it to use configurable products.

Configuration file locations

Configuration files located in the /etc/ep directory were not fully supported by all Elastic Path applications. This location has been deprecated in favor of configuration in either /ep/conf or ${user.home}/ep/conf (where ${user.home} is the path to your user home directory) .

The Cortex configuration subdirectory structure has also been simplified in these new locations.

When upgrading:

  • Move all Core Commerce environment-specific configuration files from /etc/ep to either /ep/conf or ${user.home}/ep/conf.
  • Move Cortex configuration files from /etc/ep/cortex/system/config to either /ep/conf/cortex or ${user.home}/ep/conf/cortex.
  • Move Cortex permissions files from /etc/ep/cortex/resources/config/permissions to either /ep/conf/cortex/permissions or ${user.home}/ep/conf/cortex/permissions.