Document Properties
Kbid
H31080
Last Modified
29-Nov-2023
Added to KB
29-Nov-2023
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
  • ICM 11
  • ICM 12
Concept - Price Webhook

Introduction

The Price Webhook enables Intershop Commerce Management (ICM) to retrieve prices from external systems using a predefined standardized REST API. This REST API is the central interface where the ICM acts as client, which calls the endpoint that has to be implemented by external systems providing external prices. The REST API is defined by an OpenAPI model that is used to generate the API documentation as well as the client code on the ICM side. Depending on the external system, it could also be used to generate or at least to validate code on the server side.

The client side located in the ICM consists of two parts: Managed Service and Price Provider. The Managed Service uses its configuration to connect to the external system, by using the mentioned REST API. The Price Provider connects this external price retrieval to the internal price determination and therefore checks if the Managed Service is available and passes all incoming price requests to it.

The exact procedure and mode of operation are explained in more detail below.

References

The following documentation is related to this feature:

General Workflow

Prices are always requested through the ProductPriceMgr, which delegates it to the Price Providers. More on that is described in Concept - Pricing | Price Retrieval.

To get the prices, the following steps are executed:

  1. Prices are requested with a list of products and the prices another Price Provider might already have found.

  2. This product list is given to the PriceService (Managed Service).

  3. Check what prices are cached.

  4. Transform the list of products for which no cache entries were found to a ProductPriceRequestRO.

  5. ProductPriceRequestRO is given to the Service Executor.

  6. A REST request is sent containing the ProductPriceRequestRO.

  7. A response is returned to the Executor Service, containing a ProductPriceResponseRO.

  8. Prices from the response are given back to the PriceService.

  9. In the PriceService, the prices will be transformed to a price container with Price Scale Tables and custom attributes and get cached (if caching is enabled).

  10. The PriceServicePriceProvider receives a list of price containers from the PriceService.

  11. The retrieved prices are compared to the ones from other Price Providers, according to the chosen Product Price Selection Strategy, and updated.

  12. The updated prices are returned.

REST API

With the Price Webhook, the ICM operates as a client, sending REST requests to an external system.

In order to retrieve prices, a POST request is sent to a configurable endpoint. That endpoint needs to implement the REST interface as defined by the Price Webhook Open API Specification. It defines the structure of the request the ICM sends and the response the ICM expects. For both, the used data format is JSON. Due to a limitation in the definition of parameters in Open API, custom header and query parameters, as described in Managed Service Configuration, are not specified there.

The Open API Specification can be found in Reference - Price Webhook REST API 1.0.0 (Beta).

Caching

The Price Provider uses multiple caches, to improve performance and reduce load on the external system. All instances of this service share a Web Target and an Outer Price Cache.

For each service configuration, there is one Web Target in the Web Target Cache. It is responsible for creating the actual connection to the external system. In case of a service configuration change, the Web Target will be removed and with the next request a new one will be created and then cached.

The Outer Price Cache holds all hit-and-miss caches for prices. If a service configuration changes, the hit-and-miss caches for this service instance will be removed from the Outer Price Cache. If a new price request is made, new hit-and-miss caches will be created and added to the Outer Price Cache. This provides a simple and performant way to invalidate outdated cache entries. It also prevents cache entries of one Price Webhook instance overwriting cache entries of another Price Webhook instance.

Default Values are:

initialCapacity

maximumSize

concurrencyLevel

recordStats

Outer Price Cache

8

64

4

true

Web Target Cache

4

32

4

true

For an explanation on how to change the Web Target and Outer Price Cache configurations, please see Cookbook - Price Webhook | Recipe: Change Price Provider Cache Configuration.

For each price service instance, there is one hit cache and one miss cache. Every cache entry of these two caches is associated with the customer for whom prices were requested, the currency, price type and price list type. Meaning when prices of product X are requested for customer A, they will be cached only for customer A. When prices of product X are requested for customer B, cache entries from customer A will not be used. This way, we can represent customer specific prices. All prices returned with the response will be cached in the hit cache. If the response is missing prices for some requested products, they will be stored in the miss cache.

The hit-and-miss cache has a caching duration, which starts after the entry has been put into the cache. Caching duration can be set in the managed service configuration. 3600 seconds (one hour) is the default value. Setting cache duration to zero disables caching, although it is not recommended to do so. Some operations may need to request prices multiple times, causing increased latency without caching. They can each hold up to 2000 entries by default. This can also be changed in the managed service configuration.

If any of the caches has reached its maximum size and another entry is to be added, an entry that has not been used very often or recently will be removed.

Prices

All prices are treated as Scale Prices. But because the ProductPriceMapping can only handle one price per product, additional price information is stored as price information. This information includes the Price Scale Table, a map of all Price Scale Entries and the best fitting Price Scale Entry. The best fitting Price Scale Entry is the one whose minimum order quantity is either the same or the closest below the product quantity. This information is only available if the Product Price Selection Strategy chooses the price of this Price Provider.

If the response of the external service contains multiple prices for the same minimum order quantity for a single product, there is no guarantee that a specific price, e.g. the lowest, will be chosen. If no quantity for a price is given, it is always assumed to be one.

To get this information, you can use the following code:

import static com.intershop.component.pricing.capi.pricelist.PriceListConstants.PRICEINFO_PRICE_SCALES;
import static com.intershop.component.pricing.capi.pricelist.PriceListConstants.PRICEINFO_PRICE_SCALE_ENTRY;
import static com.intershop.component.pricing.capi.pricelist.PriceListConstants.PRICEINFO_PRICE_SCALE_TABLE;
import static com.intershop.component.pricing.capi.pricelist.PriceListConstants.PRICELIST_PRICE_INFO;
import com.intershop.beehive.xcs.capi.price.ProductPriceMapping;
import com.intershop.component.pricing.capi.scale.PriceScaleEntry;
import com.intershop.component.pricing.capi.scale.PriceScaleTable;
...

Map<String, Object> priceInfo = productPriceMapping.getPriceInfo(productRef, PRICELIST_PRICE_INFO);
PriceScaleTable scaleTable = priceInfo.get(PRICEINFO_PRICE_SCALE_TABLE);
PriceScaleEntry bestPriceScaleEntry = priceInfo.get(PRICEINFO_PRICE_SCALE_ENTRY);
Map<BigDecimal, PriceScaleEntry> priceScaleEntries = priceInfo.get(PRICEINFO_PRICE_SCALES);

Additional Response Data Handling

Custom Attributes

Custom Attributes can be added to each product in the response. They will only be stored as price information and will not be processed further by default. The Custom Attributes are only available if the Product Price Selection Strategy chooses the price of this Price Provider.

They can be accessed by using the following code:

import static com.intershop.adapter.priceservice.webhook.capi.provider.PriceServicePriceProviderConstants.PRICEINFO_CUSTOM_ATTRIBUTES;
...

Map<String, String> customAttributes = productPriceMapping.getPriceInfo(productRef, PRICEINFO_CUSTOM_ATTRIBUTES);

Messages

Messages of level WARN and ERROR will be logged by the ICM. The INFO level is intended to be used together with response data logging of the Managed Service.

Managed Service Configuration

This section describes the configuration options provided by the Price Webhook and their effect.

Configuration

Description

Endpoint URL

Specifies where the Price Service Webhook sends its request to. This can be for example the Intershop Integration Hub.

Username/Password

Username and Password are used for basic authentication on the external system.

Tenant ID

The Tenant ID is intended to distinguish different Price Service Webhook instances that use the same endpoint.

It is set as the header “tenant-id”, and as the field “tenantId” in the data part of the request body.

Timeout

Allows to configure a timeout for the connection to an external system.

In case the timeout is reached, the Price Provider will return no prices. The requested products will not be added to the miss cache.

Cache Duration

The amount of time hit-and-miss caches holds their cache entries. It starts when the cache entry is added. More Details are described above in Caching.

Max. Cache Entries

The number of entries that can be cached by each hit-and-miss cache. More Details are described above in Caching.

Query Parameter Key

Optional parameter that can be added to the request. If set, they will be added at the end of the Endpoint URL.

Query Parameter Value

The value for its related Query Parameter Key. It does not need to be set, in order for the key to be added to the request. But if the key is not set, the value will be ignored.

Header Parameter Key

Optional parameter that can be added to the request. It will only be used in the request. If the response contains this header parameter, it will be ignored.

Header Parameter Value

The value for its related Header Parameter Key. It does not need to be set, in order for the key to be added to the request. But if the key is not set, the value will be ignored.

Disclaimer
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.
Home
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 supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.