Document Tree
Document Properties
Last Modified
Added to KB
Public Access
Doc Type
ICM 7.10
Guide - 7.10 API Changes


This document lists API changes for Intershop Commerce Management 7.10.x that can cause migration efforts.

For information on new APIs refer to the Public Release Note - Intershop Commerce Management B2C/B2X 7.10.

API Changes

DescriptionAPI ChangesHow to Migrate
Removal of pipelines in ViewPromotionTargetGroup_52.pipeline in sld_ch_consumer_pluginThe ViewPromotionTargetGroup_52.pipeline was reworked, in order to support paging and the following pipelines were thereby removed: DeleteCustomerGroup, DetermineCustomerGroup, GetCustomerGroup, SearchCustomerGroup, GetCustomers, GetAffiliates, IsAffiliate, FilterUserGroups, UpdateCustomerSegmentPaging

The following alternatives can be used instead:

  • DeleteCustomerGroup → DeleteCustomerSegments
  • GetCustomerGroup → GetCustomerSegmentsPageable
  • SearchCustomerGroup → SearchCustomerSegments
  • GetCustomers → GetExplicitlyAssignedCustomersPageable
  • GetAffiliates → GetAffiliatesPageable
  • UpdateCustomerSegmentPaging → UpdatePaging
See API Changes for LTS

API Changes LTS

DescriptionAPI ChangesHow to Migrate
Job and Process Chain processes are concurrently monitored for their liveness.

A new Process datetime attribute "lastLivenessDate" was introduced. Related to that, the ProcessMgr introduced new methods getAllProcesses(), getAllProcessesByState(...), getAllStuckProcesses(). The ProcessConstants have a new field STATUS_STUCK. Besides the existing ExecutorService wrapper, a new related ScheduledExecutorService wrapper was introduced. When a running process does not update its liveness anymore, changing its state to stuck can be controlled via the property "intershop.cartridges.core.process.liveness.periodProcessConsideredStuckInSeconds".

The default process chain timeout has been lowered from 24 hours to 1 hour.

Execute the DBPrepare to create the necessary columns in the process table and add the new job CheckProcessesState which finds and updates stuck processes accordingly.

If any of your individual process chain task takes more than 1h to complete, please break it down into smaller tasks not to run into a timeout or set the defaultChainElementTimeout process chain XML attribute accordingly.

API Changes LTS

DescriptionAPI ChangesHow to Migrate

Change in EnfinityManagement regarding exception throwing, server pausing/resuming and Inspector handling

Method EnfinityManagement.resumeAppServer() no longer throws a CacheListenerException.

Overall pausing and resuming the application server has been moved to ServerEnvironment which has equivalent methods which can be used.

Register Inspector based checks via EnfinityManagement.registerInspector(Inspector) or unregistration via EnfinityManagement.unregisterInspector(Inspector) no longer have an effect, instead use the SelfCheckTask from the server health checks as the successor concept.

If this exception is handled, that logic can be removed, otherwise there is nothing to do.

Instead of EnfinityManagement.pauseAppServer() use ServerEnvironment#pauseServer(). Instead of EnfinityManagement.resumeAppServer() use ServerEnvironment#resumeServer().

If a custom Inspector class is registered, convert it into a runtime SelfCheckTask, see Concept - Server Health Checks.

Change of enum values of SelfCheckTaskOutcome.StatusAn API break of the SelfCheckTaskOutcome.Status enum was necessary to externalize the view of the self check outcome meaning and unify its status values similar to commonly used values.See Guide - Server Health Checks.
Transition from ServerStatusConstants to ServerInfo.StatusThe (internal) ServerStatusConstants are no longer used and therefore have no effect anymore on the application server logic, use ServerInfo.Status within CAPI instead.See Guide - Server Health Checks.
The configuration.xml (share/system/config/cluster/configuration.xml) has one new entryThe configuration.xml has one new entry to find the file.

Add this entry to the configuration.xml file within the <sets> block:

<set finder="property" scope="cluster,server,domain" required="false" fileName="${IS_SHARE}/system/config/cluster/" />

The logback-main.xml (share/system/config/cluster/logback-main.xml) has one new logger entry

The logback-main.xml has one new logger entry regarding logging of EnfinityManagementImpl.

Add this logger entry to the logback-main.xml file within the <included> block:

<logger name="">
    <level value="INFO" />
    <appender-ref ref="ServerStartupConsole" />

API Changes LTS

DescriptionAPI ChangesHow to Migrate

Change of staging processor for staging group "Prices":

Prices used to be staged with FullDomainSpecificStagingProcessor. This has now been changed to MergeDomainSpecificStagingProcessor

Prices and according objects maintained in live systems will not be completely deleted/overwritten on replication. They will now be merged with the data from edit. This enables maintenance of customer - price list - relation in live system.

If this behavior is desired, there is nothing to do.

To enable the old behavior, change StagingProcessorName for PRICING_PriceScale in database table StagingGroup back to FullDomainSpecificStagingProcessor.

Deletion of price lists in ICM back office

The deletion of price lists in the ICM back office (batch mode) has been completely reworked for better performance and stability.

As a result the removed product prices from the deleted price lists are not saved in the product history anymore. (Note: New product prices, e.g. from Imported price lists are already excluded from product history).

No migration necessary
Changes related to quantity units of scale price quantities.See Guide - Quantity Units of Scale Price Quantities.See Guide - Quantity Units of Scale Price Quantities.

The configuration.xml (/share/system/config/cluster/configuration.xml) has two new entries: 

<set finder="domain-folder" scope="domain" matches="^${environment}_${staging.system.type}_[[\w&&[^_]]*$" fileExtensions="properties,xml"/>
<set finder="property" scope="cluster,server,domain" fileName="${IS_SHARE}/system/config/cluster/staging_${environment}_${staging.system.type}.properties" />

No change is necessary. 

However, now it is possible to have configuration files for each staging environment and staging system type at one place, and only the one matching the actual servers environment and type will be used.

API Changes

DescriptionAPI ChangesHow to Migrate
Removed and adjusted default connection time and retry properties for web adapter.
  • Remove 'cs.poll.maxtries' from configuration tools
  • Remove 'cs.poll.timeout' from configuration tools
  • Remove 'cs.socket.timeout' from configuration tools
  • Check new 'as.maxwait', 'as.maxtries' and 'as.connect.timeout' defaults in
The web adapter returns a HTTP 503 status code (old was HTTP 500 - internal server error) to the client if no configuration service is available.
Adjust clients to check for HTTP 503 codes if you want to check if ICM is available.
The class 'ApiTokenCookieLogin' has a new default method 'removeToken()'. This is used to remove a token cookie from the browser if the value is invalid and cannot be decoded. The default implementation does nothing.
Custom implementations should override the method to work the same way.

API Changes

DescriptionAPI ChangesHow to Migrate
Apache Tomcat was updated to version 9.0.50.
Deploy the application server.

API Changes

DescriptionAPI ChangesHow to Migrate
Cleaned up QualifiedNameGenerators for Junit 5 Tests

Obsolete/duplicate Classes

have been removed.

Use remaining class

as follows:


API Changes

DescriptionAPI ChangesHow to Migrate

DBInit and DBMigrate now use DBPrepare

The DBMigrate and DBInit tools now use DBPrepare internally.

This is a step to remove these old commands from the ICM system and use DBPrepare only.

Before updating to ICM 7.10.33, run DBPrepare one time if you have used DBInit/DBMirate before 7.10.33 

This procedure registers all old migration steps for DBPrepare. The next execution of DBPrepare only runs necessary migration steps.

API Changes LTS

DescriptionAPI ChangesHow to Migrate
Removed deprecated code from CMSSee Guide - Removal of Deprecated Code of bc_pmcSee Guide - Removal of Deprecated Code of bc_pmc

API Changes

DescriptionAPI ChangesHow to Migrate

Transactions rolled back in REST requests if status is 4xx or 5xx.


The REST transaction behavior changed. Automatically opened transactions will now be rolled back if the response has a status 4xx or 5xx.If a transaction has to be committed in case of an error, the transaction should be committed explicitly.

The configuration of the staging-preparer and decorator is now done in the code (Guice modules).

(IS-30950) does no longer contain preparer-configurations. This configuration is done in hard-coded modules.

The code is backward-compatible. 
If a configuration is found in, this configuration will be used.


Remove registration of staging preparer from and declare a Guice binding for that.

The standard modules with the staging-configuration can be overwritten with custom modules. Additional documentation can be found in Concept - Mass Data Replication | Staging Decorators.

API Changes

DescriptionAPI ChangesHow to Migrate

SQL-Script-Preparer uses UTF-8 character set for scripts. A named parameter 'encoding={CHAR_SET}' can be used if another encoding or character set is desired.


All SQL-Script-Preparer and its super-classes use UTF-8 character set for scripts instead the system's default character set.

If necessary, use named parameter 'encoding={CHAR_SET}' to use another character set.

Class42 = com.intershop.beehive.core.dbinit.preparer.database.SQLScriptPreparer \
          com/intershop/beehive/core/dbinit/scripts/dbindex.ddl \
          encoding=UTF_16 \

The SQL-Script-Preparer has an attribute singleScript to execute a script as one.


By default the SQL-Script-Preparer executes each statement separately. By adding the attribute singleScript, the configured script will be executed as ones.

Add the attribute singleScript=true to enable the single script mode:

post.Class1 = com.intershop.beehive.core.dbinit.preparer.database.SQLScriptPreparer \
                resources/core/dbinit/scripts/enfinitytable.sql \

API Changes

DescriptionAPI ChangesHow to Migrate

Some pipelines and templates are overwritten by OIDC-adapter cartridges.


pipelinecartridgeoverwriting cartridge
templatecartridgeoverwriting cartridge
If the mentioned pipelines or templates have been either overwritten or modified by custom variants, these variants have to be migrated to ensure compatibility with existing and newly created variants.

The pattern for the SSO-redirect-URIs has been changed.


  • login
    • old pattern: https://<host>:<port>/INTERSHOP/web/<servergroup>/<site>/-/-/-/OpenIDConnectLogin-Callback
    • new pattern: https://<host>:<port>/INTERSHOP/web/<servergroup>/root/-/-/-/OpenIDConnect-DispatchCallback

  • logout
    • old pattern: https://<host>:<port>/INTERSHOP/web/<servergroup>/<site>/-/-/-/OpenIDConnectLogout-Callback
    • new pattern: https://<host>:<port>/INTERSHOP/web/<servergroup>/root/-/-/-/OpenIDConnect-DispatchCallback

Adapt the configuration of your identity providers. Also see Guide - New Pattern for SSO Redirect URIs.

API Changes

DescriptionAPI ChangesHow to Migrate
Fixed constant names in ResponseStatusConstantsThe constants names SERCICE_UNAVAILABLE and SERCICE_UNAVAILABLE_CODE in are fixed.Use the constants SERVICE_UNAVAILABLE and SERVICE_UNAVAILABLE_CODE instead.

JUnit updated to 4.13.1

JUnit-Jupiter to 5.7.0

Added default configuration for HTTP2

(Status: beta)

A default configuration for HTTP2 support is added to the HTTPD configuration. The configuration is disabled by default. Please test the HTTP2 setting with your test environment and report problems.

How to enable the HTTP2 support:

  • Windows: Change the HTTP service configuration from:
    "<PATH>\server\local\httpd\bin\httpd.exe -k runservice -n Enfinity_ApacheWebServer16 -f <PATH>\server\local\httpd\conf\httpd.conf"
    "<PATH>\server\local\httpd\bin\httpd.exe -k runservice -n Enfinity_ApacheWebServer16 -f <PATH>\server\local\httpd\conf\httpd.conf -D http2"
  • Linux and MacOS:
    Change the "apachectl start" call within the init script to "apachectl http2 start" or call this manually
  • Linux (option with deployment tools):
    Add the line "ENABLE_HTTP2=true" to the file "<PATH>/local/httpd/bin/envvars"

We will enable HTTP2 as default with ICM 11. Please provide feedback.

Added default configuration to enable 'mod_status' in HTTPD

A default configuration to load Apache HTTPD module 'mod_status' is added. This is disabled by default. This can be used by some monitoring solutions to get insights from the Apache HTTPD server.

How to enable the mod_status module:

  • Linux (option with deployment tools):
    Add the line "ENABLE_STATUS=true" to the file "<PATH>/local/httpd/bin/envvars"

The URL is '/server-status' and the access is restricted to the host running the web server only.

This is only available for Linux at the moment.

Extended Cache Keywords for PromotionsThe cache keywords for a promotion now also include the PromotionID which can be set during the creation of a promotion in the back office. This is especially useful when dealing with a REST client because this promotion ID is used as identifier in the URL to determine a promotion.
Bug Fix in /products endpoint of REST API

The inStock attribute now returns data from the inventory service.

Previously the inStock and availability fields both returned the value of the "in stock" checkbox of a product in the ICM. This was not intended and did not match the documentation. Now the behavior is corrected.

In case the inStock attribute was previously used, an adjustment is required:

  • inStock returns inventory data from the inventory service (boolean; empty in case there is no active inventory service)
  • availableStock returns the stock level of a product from a quantity-based inventory service
  • availability returns the value of the "in stock" as maintained in the ICM

API Changes LTS

DescriptionAPI ChangesHow to Migrate
Parameter returnSortKeys now returns detailed sort key information in ProductListResourceProductListResource now returns a ProductLinkCollectionRO, which contains an extra field sortableAttributes. When returnSortKeys is true, this field contains extra information such as display name and direction for the sort keys, along with the old sortKeys field.
Messaging metrics available in Prometheus
Metrics from messaging component are available in Prometheus
Cache metrics are available in PrometheusMetrics from registered caches are available in Prometheus

Check for Web Cache Deception


To prevent a Web cache deception attack, it is checked if the URL of a request ends with an illegal dictionary ID. If that is the case, the server responds with 404 - 'resource not found'.

If this behavior is desired, there is nothing to do.
To enable the old behavior, a property has to be set.

intershop.validate.url.wcd = false

The Cartridge containing the e-mail templates for the headless application type (intershop.RESTwas renamed to better reflect the more specific usage intention of the included e-mail templates.

Cartridge app_sf_emails was renamed to app_sf_headless_emails.

Dependency definitions in build.gradle files have to be changed from:

compile group: '', name: 'app_sf_emails'


compile group: '', name: 'app_sf_headless_emails'

Bugfix for local SSO users created for wrong organization



  • An ICM uses the same identity provider for the organization Operations and an Enterprise back office organization

The symptom of the bug was:

  • If an SSO user logs in to an Enterprise back office using the site SLDSystem, the user is locally created (when missing) for the organization Operations
  • If an SSO user logs in to the Operations back office using an Enterprise back office site. the user is locally created (when missing) for the Enterprise organization

Migration step:

  • Delete those users using the appropriate back office

API Changes

DescriptionAPI ChangesHow to Migrate

Fill Factor removed for MSSQL indexes.


The fill factor was removed from Stored Procedure GetIndexCreationScript while creating a replication enviroment.

Execute DBMigrate for updating Stored Procedure.

For already created indexes rebuild them with FILLFACTOR = 100:

ALTER INDEX <@>index_name< ON <table_name> REBUILD WITH (FILLFACTOR = 100)

API Changes

DescriptionAPI ChangesHow to Migrate

The SSO implementation is now independent from Keycloak libraries


  1. cartridges ac_keycloak* removed
  1. Migrate code that depends on ac_keycloak* cartridges

The SSO-redirect-URIs have been made simpler


  1. Remove query parameters from each and every redirect URI configured inside the connected identity providers
JDBC Oracle driver updateThis release contains a reference to the new oracle jdbc driver

The following steps are necessary so that the old driver can still be used:

  • Create and publish the new driver to your artifact repository (this is just needed during deployment to resolve dependencies).
  • Override the version at your customization assembly to the old version.

For more details see Support Article - Handling the New Dependency of 3rd_oracle Version (valid to 7.10).

New role descriptions for B2B roles

For migration to these new descriptions, perform the following steps:

  1. Activate the AddRolesInformationPreparer in the following files:
    • %IS_SHARE%\system\cartridges\bc_costcenter_orm\release\
    • %IS_SHARE%\system\cartridges\init_b2b\release\
  2. Call the DBmigrate step.


    With the migration your customized changes will be lost.
The Java code for /products/variations was refactored.
  • Method ProductResource.getVariations() was removed.
  • Method ProductResource.searchVariations() was removed.
  • Both methods were moved to class VariationResource. VariationResource is now sub-resource of ProductResource.
  • VariationHandler was introduced to resolve variation based data (extracted from ProductResource.)
  • getPageableOfProducts was introduced (extracted from ProductResource.)
  • Add VariationResource to Component Framework and add it as sub-resource to ProductResource.
  • If ProductResource was overwritten in context of variations, make sure to move your custom code to an override of VariationsResource.

API Changes

DescriptionAPI ChangesHow to Migrate

The SSO implementation now supports Azure AD besides Keycloak.

For more information see Concept - Single Sign-On (SSO) and Cookbook - Single Sign-On (SSO).

  1. New cartridges ac_oidc*
  2. Removed cartridges ac_keycloak*
  1. Replace the configuration property keys intershop.authentication.<organizationKey>.<identityProviderKey>* by intershop.authentication.identityprovider.<identityProviderKey>*
  2. Replace type value keycloak by oidc


Sessions persisted using the Keycloak-specific implementation will be logged out.

API Changes

DescriptionAPI ChangesHow to Migrate
renderTemplate is now optional in Pagelet ModelsPagelet Models without renderTemplate are valid now. However, if used in an ISML-based storefront, a renderTemplate is still required.

API Changes

DescriptionAPI ChangesHow to Migrate

On MSSQL the stored procedure sp_deleteUserDataByDomain runs forever, if there is data that needs to be deleted in the tables BASICPROFILE/BASICADDRESS related to the deleted DOMAINIDs.

The stored precedure was modified, it is not an API change.

However, you have to update to the new API version

Execute DBMigrate

API Changes

DescriptionAPI ChangesHow to Migrate
New /productfilters endpoint for filter navigation This will replace the /filters endpoint which now is deprecated.

The Pipeline "ProcessOrders.pipeline" from bc_orderprocess was originally overwritten in "app_sf_responsive_b2b" (only B2B) in order to add an extension point at the end of the pipeline branch "AfterCheckoutProcessing". This pipeline extension point which was only available for B2B was called "ProcessOrders-AfterCheckout".

The overwritten pipeline ProcessOrders.pipeline includes the former extension point ProcessOrders-AfterCheckout has been removed. Instead the original pipeline in bc_orderprocess now contains a new pipeline extension point at the end of the pipeline branch AfterCheckoutProcessing which is called ProcessOrders-AfterCheckoutProcessingEnd.

API Changes

DescriptionAPI ChangesHow to Migrate
Changed default-persistence for bot sessions.The default-value for the property intershop.session.persistBotSession is now false.

Most likely, the bot-session should not be persisted. In that case, nothing is to be done.

If the bot-session should be persisted, the property has to be declared with the value true.

Update JGroups libs to version 4.2.0


common-messaging updated to 1.0.3No manual deployment. Redeploy server only.

Added extra logging to common-messaging


NoneEnable TRACE log level for package or class 'com.intershop.beehive.messaging.internal.jgroups.ChannelViewMonitor' . This logs all changes of the members of a messaging channel to the debug log for JGroups.

Extra configuration options added to the JGroups FILE_PING configuration to remove old .list files


NoneCheck the provided configuration file and move the changes to a custom file if you have adapted the JGroups configuration.

SSO for SMC. For more information see Concept - Single Sign-On (SSO) and Cookbook - Single Sign-On (SSO).

(IS-28733, IS-29700)

new persistent object com.intershop.beehive.core.internal.profile.IdentityProviderMappingPO and new tables identityprovidermap*.Execute dbmigrate OR dbprepare.
New basket validation for addressesTo detect changes of a referenced address which may cause a change in the tax jurisdiction a new validation handler was added. In case the validation was called while allowing adjustments, the address is updated and the calculation set to invalid. When the automatic correction is prohibitted an error message is returned.

The response of the REST request for validating the basket may contain an info message. The REST client has to decide on the current context if the info has to be shown or not. In other words on the address page such changes are intended to be done and the message should be suppressed. But if the buyer is, for instance, already on the review page, such a change has to presented to the buyer.

In case automatic adjustments are not allowed and the error basket.validation.address_changed_basket_calculation_invalid.error is returned, the REST client has to trigger a validation for addresses with adjustments allowed and finally a re-calculation to take the address changes into account.

API Changes

DescriptionAPI ChangesHow to Migrate
New optional query parameter omitHasOnlineProducts added to REST resource /categories

The omitHasOnlineProducts parameter has been added to the /categories resource. If set to true, the field hasOnlineProducts will not be resolved for:

  • all categories in the category list resource
  • subcategories in the category item resource

This is to improve performances in cases where this field is not needed, as the operation is expensive.

To support this change, the constructor for CategoryRO no longer sets the hasOnlineProducts field using the provided CatalogCategoryBO. In addition, this field is now a Boolean object, so it is set to null when not set.

A migration is only necessary if CategoryRO is created directly. If it is, fetch hasOnlineProducts using CatalogCategoryBO.hasOnlineProducts(Domain) (or another source), and set it using the setter CategoryRO.setHasOnlineProducts(boolean).
New field effectiveUrl added to attachments under the products resource.In order for external resources to be able to access product attachments, the effective url is now included in AttachmentRO.
New query parameter extended added to product resource for variation attribute information

A new optional query parameter extended has been added to the /products/{id} and /products/{id}/variations resources, which will provide more complete information about variation attributes and their values in the new field variationAttributeValuesExtended.

Category endpoint now supports category reference as a category id.

The category endpoint requires the full path to the category in order to resolve a category. This is not always feasible, therefore the category endpoint now also supports using a category reference instead.

This replaces the previous categoryRef query parameter. Format: /categories/<category id or ref>

The category reference for a category can be found in the field categoryRef in CategoryRO.

API Changes

DescriptionAPI ChangesHow to Migrate
REST resource POST /contact is now secured by CAPTCHAThe REST resource for sending a "Contact Us" e-mail (POST /contact) is now secured with CAPTCHA authentication.

If this is not wanted, the CAPTCHA authentication for this resource can be toggled off in the channel backoffice via Preferences | CAPTCHAs.

For information on how to integrate CAPTCHA authentication into a REST client, please refer to Cookbook - WebShop REST API.

Removed reCAPTCHA v1 serviceSince the reCAPTCHA v1 service is no longer supported by Google, it has been removed from ICM.Trigger DBMigrate to remove obsolete service configurations.

API Changes

DescriptionAPI ChangesHow to Migrate
Adapt default JGroups configuration XMLThis is not an API change but a configuration change:
  • Remove the multi cast flow control protocol (configuration uses uni cast only)
  • Limit the FLUSH timeout to five seconds (instead unlimited)
  • Remove the 'view_bundling' setting (is default 'true')
  • Adapt the 'min_threshold' value to prevent low credits for flow control handling
Merge these changes to your configuration file if you use a custom configuration file. No need to adapt configuration if you use the provided file.

API Changes

DescriptionAPI ChangesHow to Migrate
Refactoring of Basket REST API
  • IncludeResolver classes are now optional. If no includes are used for a REST request, then no IncludeResolver needs to be wired via Guice.
  • Classes that previously implemented the ObjectMapper interface now implement the java.util.function.Function interface instead. To unify the usage across the API, several classes which did not implement the ObjectMapper interface but had similar named resolve(...) methods had their methods renamed to apply(...) as well.

Old Name

New Name, Collection<String>), Collection<String>), UriInfo), UriInfo)<String, Map<String, Object>>, UriInfo)<String, Map<String, Object>>, UriInfo), C), C)


This list only shows the (CAPI) classes where the API has changed and does not include internal classes that have been changed because of this.
  • Removed request factories: Requests are now injected directly into the resource classes without the use of assisted injection via a factory. Parameters that have previously been part of the factory methods have moved to the invoke(...) methods of the requests. As a consequence, the RestRequest interface has also been removed, which means that requests are now addressed directly by the implementation class. To achieve an easier testability of the code, the requests now also use dependency injection via the constructor (instead of field injection).
A migration is only necessary if there is custom code which uses any of the mentioned changed classes directly. If there are already new custom REST resources or requests that still use ObjectMapper or assisted injection, then they should still work fine.
Removed deprecated codeThe deprectated method com.intershop.beehive.core.dbinit.capi.DBInit.prepareCartridge(Cartridge, String) has been removed.Use the method com.intershop.beehive.core.dbinit.capi.DBInit.prepareCartridge(Cartridge) instead as documented already.
Cache /categories callAdded logic for caching /categories call. After this functionality was added, the authentication token is missing from headers because this is the normal behavior. Only uncached calls return an authentication token in the and are now cached.
New requestable REST attribute  retailSet  was added to /products

By using the  /products  and  /categories/<catID>/products  REST endpoints, product stubs for display on family pages and search result pages can be retrieved. The optional attrs parameter allows to receive certain product attributes in that call to construct product tiles on said pages.

  • retailSet - shows if products from a list are retail sets or not. Allows to handle retail sets differently in lists (e.g., show a price range, instead of a price), without calling /products/<productID> first.

API Changes

DescriptionAPI ChangesHow to Migrate
DBMigrate to create a new Job which removes executed Impex Jobs (IS-27705 - Application servers dies during collecting data for job chain page)-Executing DBMigrate is optional if you do not need the Job.
In an effort to unify REST error codes, some codes for the new basket and order APIs have changed.

The following codes have changed:

Old Code

New Code






















































































































basket.promotioncode.add_not_successful.error (NoPromotionApplicable)


basket.promotioncode.add_not_successful.error (NumberOfApplicablePromotionCodesReached)


basket.promotioncode.add_not_successful.error (PromotionCodeAlreadyInBasket)


basket.promotioncode.add_not_successful.error (PromotionCodeAlreadyRedeemed)


basket.promotioncode.add_not_successful.error (PromotionCodeEmpty)


basket.promotioncode.add_not_successful.error (PromotionCodeMaxLength)


basket.promotioncode.add_not_successful.error (PromotionCodeNotAccessible)


basket.promotioncode.add_not_successful.error (PromotionCodeNotActive)


basket.promotioncode.add_not_successful.error (PromotionCodeNotFound)










































The following codes have been added:

If custom code relies on these error codes, it needs to be adapted. Note that both the basket and the order REST API are still in a beta state, so there may occur similar changes in the near future until finalized.

API Changes

DescriptionAPI ChangesHow to Migrate
Some basket validation errors have been changed/added/removed.

Changed/split up into multiple:

  • PromotionInvalid → BasketPromotionInvalid, LineItemPromotionInvalid
  • ShippingMethodInvalid → CommonShippingMethodInvalid, LineItemShippingMethodInvalid
  • ShippingMethodMissing  → CommonShippingMethodMissing, LineItemShippingMethodMissing
  • ShippingMethodWasSet → CommonShippingMethodWasSet, LineItemShippingMethodWasSet
  • ShippingRestrictions → LineItemShippingRestrictions
  • ShipToAddressMissing → CommonShipToAddressMissing, LineItemShipToAddressMissing
  • ShipToAddressWasSet → CommonShipToAddressWasSet, LineItemShipToAddressWasSet


  • TotalQuantityExceeded


  • TermsAndConditionsError (this has been moved and is now an error that occurs during order creation)

If there is custom code that specifically targets those error codes, it needs to be adapted to the new codes.

In case you are still using the pipeline based order creation process, you have to re-register the TermsAndConditionsValidatorHandler to the basket validation. Therefor you have to provide a custom replacement for the deleted extension file (BasketValidationTermsAndConditionsHandler.extension).

Support for Prometheus Open Metrics
  • Added Cartridge ac_prometheus
  • In case you want to use the Prometheus Metrics, you will find them at each appserver at 'http://<appserver-host>:<port>/metrics'.
  • You can disable the Prometheus monitoring support with the property 'intershop.metrics.prometheus.enabled = false'.
Foreign key definition for IMAGE objects are moved from bc_foundation to bc_image (IS-27551)The assignment of the IMAGE related tables was already moved from bc_foundation to bc_image with IS-26184. The foreign key definitions was not moved with the change. This is fixed now.Run DBMigrate
Updated some test libraries dependencies and versions
  • Updated Selenium libraries from 2.47.2(Sep 2015) to 3.141.59(Nov 2018) version
    • In the new Selenium version support for PhantomJSDriver has been dropped.
  • Removed PhantomJSDriver related libraries from the dependencies.
  • Added new librabries for ParameterizedTest and Mockito extension for jupiter(JUnit5) to the dependencies.
  • Default webdriver for execution of Geb tests changed from PhantomJs to geckoDriver, allowing to execute Geb tests using real Firefox browser in a headless mode

In case your project uses a custom assembly adapt the following Gradle files:

  • build.gradle
    • Remove dependencies to phantomjsdriver and webDrivers in Geb configuration
    • Add dependency to selenium-firefox-driver and support for geckoDriver in webDrivers in Geb Configuration
    • Set default webdriver for execution of Geb tests to be geckoDriver
  • src/remoteTest/resources/GebConfig.groovy
    • Remove import of phantomjsdriver classes and support for PhantomJsDriver in Geb environments
    • Add import of selenium.firefox classes and support for geckoDriver in Geb environments

In case your project runs Geb tests ensure Firefox browser is installed on the machine where Geb tests are executed.

For more details and examples see Guide - Update Assembly Geb Configuration.

New field "orderCreationReentryChain" at OrderPOA new field "orderCreationReentryChain" has been added to the persistent object for orders (OrderPO). This field contains information where the order creation process has been stopped (e. g. if a payment redirect is required). To get the new column in the database, a DBMigrate is needed.Run DBMigrate

API Changes

DescriptionAPI ChangeHow to Migrate
New order creation handlerMoved functionality to generate the requisition document number from the "ApprovalOrderCreationHandler" to a new order creation handler "RequisitionDocumentNumberOrderCreationHandler" (cartridge "bc_order_approval_orm", position 25 in "PreOrderCreationChain").If there is a custom handler at position 25 in the "PreOrderCreationChain" then this handler needs to be moved elsewhere.
SSH passphrase invalidation for log transfer to reporting service

A fix regarding the passphrase of the SSH keys was made. The old passphrases are not longer valid. The error log contains an entry as shown in the following example:

Could not connect (and open a session) with config SFTPConfig 
[user=xxx,, passPhrase=***********************] 
com.jcraft.jsch.JSchException: invalid privatekey
Regenerate the key pair and send the new public key to the consumer of the effected transfer (mostly

API Changes

DescriptionAPI ChangeHow to Migrate
Reworked text index creation for MS SQLThe definition of indexed columns is changed from a predefined query to a list of columns.See  Guide - SQL Server Text Indexes
DBMigrate on MS SQL to update procedure sp_compile_invalid_objectsThe procedure compiles objects which are part of the current schema only.Rund DBMigrate on MS SQL
Option to disable CSS file compressionThe used YUICompressor component to strip unsued characters from CSS files is not updated for some time. This can cause problems with recent CSS features. A property "intershop.css.compress.enabled" is added to disable (false) the CSS processing. The CSS will be send to the client without modifications. The Apache content compression (mod_deflate) can limit the data amount to transfer. This is added to all versions 7.6-7.10)See ISML Tag - ISRENDER
Override configuration by environment variablesIt is possible to override configuration settings by environment variables.See Concept - Configuration (7.10.12 to 7.10.41-LTS), section System properties
Update JGroups configuration for faster startup (IS-27260 - Slow startup of appserver after JGroups4 update)The server startup was slower if old '.list' files was part of the 'share/system/jgroups/*' directories. The messaging tried to contact the server instances registered in these files. This was not possible because these instances was stopped. It took around 5 minutes per file till the JGroups gave up.
Now the retry configuration is changes to 5 tries with 1 second wait time. Old files are ignored if the servers defined in the file are not available. Please recheck the directory for old files from time to time as the files are not removed automatically and the startup delay can increase.
A Java VM shutdown hook is added to stop the messenger instance if the VM does not stop with a shutdown to prevent remaining files. This does not work if the hook can not be triggered (kill -9).

The default configuration file is updated with the settings. Please adjust you configuration file if you deploy a custom version.

    <pbcast.GMS print_local_addr="true"
Creating text indexes using SQL ServerThe creation of text indexes is now separated into specialized preparers for Oracle and SQL Server. The configuration of Oracle Context indexes is untouched. But the configuration of SQL Server Fulltext indexes is completely reworked.See Guide - SQL Server Text Indexes
REST documentation updated from Swagger to OpenAPIThe REST API documentation is changed from Swagger annotations to OpenAPI annotations.
Storing of Promotion Information at OrdersThe order creation process has been adapted to store the relevant information of all used promotions directly at the order.See Guide - Storing of Promotion Information at Orders

API Changes

DescriptionAPI ChangeHow to Migrate
DBMigrate for MSSQLStagingGroups "FND_ImageReferences" and "FND_ImageDefinitions" moved to bc_imageRun dbmigrate after deploy new version.
DBMigrate for MSSQLUpdated the Stored Procedure "STAGING_DDL$copy_indexes" for MSSQL to handle also XML indexesRun dbmigrate after deploy new version.

API Changes

DescriptionAPI ChangeHow to Migrate
Rest Extension for productsAdding extension to show the default category

API Changes

DescriptionAPI ChangeHow to Migrate

JGroups messaging version updated to version 4.

The JGroups based messaging implementation uses the latest JGroups 4 version now.The update installs a new 'jgroups_udp.xml' matching the changed JGroups 4 configuration. Please review and change the file if you manually made modifications for the former JGroups version!
DBmigrate for MSSQLUpdated the stored procedure "sp_gather_table_stats" for MSSQL to prevent a data type issueRun dbmigrate after deploy new version.

Pipelines "ProcessBasketCalculation" and  "ProcessCartCalculation" no longer remove invalid PaymentBOs.

The basket calculation pipelines "ProcessBasketCalculation" and "ProcessCartCalculation" no longer check if the selected payment methods are still valid after the calculation. There are basket validation handlers which perform the same checks, which is why it has been removed from the calculation.If the basket calculation is triggered in custom (non-standard) code artifacts, then it may be necessary to trigger a basket validation for scope "Payment" afterwards (only if needed).
New requestable REST attribute  packingUnit  was addedBy using the  /products  and  /categories/<catID>/products  REST endpoints, product stubs for display on family pages and search result pages can be retrieved. The optional  attrs  parameter allows to receive certain product attributes in that call to construct product tiles on said pages.

API Changes

DescriptionAPI ChangeHow to Migrate
Changes in interface TransportConfigurationThe interface com.intershop.component.transport.capi.config.TransportConfiguration now extends ExtensibleObject.

API Changes

DescriptionAPI ChangeHow to Migrate
Changes in User RO classes has a new public method:

Date getBirthdayDate() has 4 new public methods:

String getPreferredInvoiceToAddressUrn()

void setPreferredInvoiceToAddressUrn(String)

String getPreferredShipToAddressUrn()

void setPreferredShipToAddressUrn(String)

New classes in app_sf_rest_smb cartridge:

New methods in SMBCustomerUserROValidator, SMBCustomerUserROOperator,  SMBCustomerUserHandler and CustomerBOGroupCustomerExtension interfaces interface has a new method:

void validateCreation(List<SMBCustomerUserRO>, UserBORepository) interface has a new method:

UserBO createUserBO(SMBCustomerUserRO, CustomerBO) interface is extended with 3 new methods:

void deleteUser(UserBO)

Collection<UserBO> addUsers(CustomerBO, List<SMBCustomerUserRO>)

Collection<UserBO> getUsers(UserBO, CustomerBO, CustomerSearchContext)

com.intershop.component.customer.capi.CustomerBOGroupCustomerExtension has a new method:

CustomerUserCreationResult createUser(CustomerUserCreationContext context)

Default implementation provided, no action needed.

New interfaces and classes in bc_customer cartridge

The following capi interfaces were introduced in bc_customer cartridge:




The following capi class was introduced in bc_customer cartridge:


JUnit 5 is introduced.
With a testrunner, a test can be exec​_uted as JUnit 5 Test
The JUnit 5 Interfaces beforeEach(...) and afterEach(...) are now implemented by the AbstractAllCartridgesAwareRule and the EmbeddedServerRule.

Any cartridge that uses Rule which is the EmbeddedServerRule or the AbstractAllCartridgesAwareRule or do extend on of this rules has a test-dependency to JUnit 5.
The build.gradle should therefore include in the test-dependencies:

compile 'org.junit.jupiter:junit-jupiter'
compile 'org.junit.jupiter:junit-jupiter-api'
compile 'org.junit.vintage:junit-vintage-engine'
compile 'org.junit.platform:junit-platform-runner'
MS SQL JDBC 7.2.1To access the ms-sql-database, the version 7.2.1 for java 8 is used.Everything should work fine with the new version of the driver.
If workarounds for bug in previous versions where used, it can be checked if this workarounds now can be removed.
Logback-UpdateThe com.intershop.beehive.core.capi.log.CSVEncoder is changed since it's superclass has changed too.Generally, the CSVEncoder should not be overwritten. In exceptional cases, it is to check if the overwritten methods are still generating the expected behavior.
DBMigrate with platform version 18.0.x and 19.0.x
The DBMigrate run(s) are necessary for MSSQL only. Some stored procedures are adapted. The Oracle database is not changed.

API Changes

DescriptionAPI changeHow to migrate

API Changes

DescriptionAPI changeHow to migrate
New requestable REST attribute availableStock  was added

It was added in REST response for all  /products  and / product  calls. It contains the quantity which is available for sale. The data comes from the Inventory Service.

API Changes

DescriptionAPI changeHow to migrate
SearchQuery of search query definition and searchquerydefinition.xsd has changed

Search query definitions can now include placeholders that are resolved at runtime. Therefore the searchquerydefinition.xsd was extended and the SearchQuery class has new methods:
public List<ParameterBinding> getParameterBindings()

public void setParameterBindings(List<ParameterBinding> bindings)

public List<ParameterBinding> getAvailableParameterBindings()

The fallback_searchquerydefinition product filter (search query definition) that is used by default for category navigation is used for search and search suggest queries as well.

For more information about this feature refer to:

Old product filter import files work without migration. The new parameter-bindings element in the searchquerydefinition schema is optional.

If your 'fallback_searchquerydefinition' product filter defines conditions or sortings that should not apply to search and search suggest queries, do the following:

  1. Create a new navigation query definition that define the settings from fallback_searchquerydefinition (Import/Export product filter)
  2. Update CMS View Contexts for category/family pages to use the new navigation query definition.
  3. Update fallback_searchquerydefinition to include only the conditions and sortings that should apply to search.
New requestable REST attributes  minOrderQuantity  and  inStock  were added. By using the  /products  and  /categories/<catID>/products  REST endpoints, product stubs for display on family pages and search result pages can be retrieved. The optional attrs parameter allows to receive certain product attributes in that call to construct product tiles on said pages.
  • minOrderQuantity  - can be used to add products to carts and quotes
  • inStock  - can be used to effectively render the family page in the list view

Now attribute groups on channel level get an  available via REST API  flag. A new checkbox and a new custom attribute are added for every attribute groupAvailableViaREST  with the values  true/false.  If an attribute group is  available via REST API , then the group and all contained attributes will be included in the regular  get product data  call. A new parameter  attributeGroups  is introduced. It returns the requested attribute groups with all their attributes. For the import/export process an additional attribute  <available-via-rest>  was added to the impex XML file. For attribute groups on organization level the value is always  false.

API Changes

DescriptionAPI changeHow to migrate
The BORules, which are used in the '_test'-cartridges were removed from the API.The BORules (extends BusinessObjectTestRule) and their Builders were moved from the 'capi' packages, because they don't belong the official API of IS7. These rules remain in their original test cartridge, but their package was adapted. Therefore classes, which are using these rules must be adapted

If the project use these BORules, the imports have to be adapted:

  1. remove the 'tests.unit.' sub-package
  2. replace the 'capi.' sub-package by 'test.'


Moved Rules
- import;
+ import com.intershop.component.order.test.OrderBORule;

API Changes

DescriptionAPI changeHow to migrate
Changes in the staging processors

The internal API of staging processors has changed.

FullDomainSpecificStagingProcessor$TableSizeComparator the inner-class compares StagingTasks instead of ReplicationTasks now.

DifferentialStagingProcessor the class is removed.


  • Instead of the parameterless constructor, the method initStatements() is overwritten.
  • Methods that use collections as parameter or return value are returning parameterized collections.
  • Some protected methods are partly removed, some are also added.

FullStagingProcessor$ContextIndexCreationMode the enumeration is removed.


  • Methods that use collections as parameter or return value are returning parameterized collections.
  • Some protected methods are removed.

DatabaseStagingProcessor the method initStatements() is overwritten with an empty implementation.

TableReplicator the deprecated methods are removed.

ForeignKey the return-value Vector is replaced with a List<String>

StagingEntityMgr the deprecated method getForeignKey(...) is removed from the interface.

Generally, the touched classes are for internal use only.
The interfaces of the search-expressions are extended

There is a new interface with a method that was in the parent interface before and a new method with a default-implementation.

SearchExpressionExactPhrase, SearchExpressionExclusionPhrase, SearchExpressionFuzzyPhrase the method getValue() is (re)moved.

SearchExpressionPhrase the method public String getXPathSnippet() was added.

SearchExpressionValuePhrase the new interface contains the method getValue() and has a default-implementation for getXPathSnippet().

SearchExpressionImpl, SearchExpressionWildCardImpl the method getXPathSnippet() was implemented.

Since there are default-implementations, no migration should be necessary.
The decorator-constructor removed.The decorator-constructor from the RemoveUnapprovedProductsDecorator was removed.The method setDecorator(...) can be called manually.
Cartridge renaming

The cartridge in was renamed to

Replace dependency declaration in build.gradle files in case ac_webhook_inventory is used.
The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to if you experience login issues,
or if you want to register as customer.