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:

• Concept - Managed Service Framework

• Concept - Pricing

• Cookbook - Price Webhook

• Reference - Price Webhook REST API 1.0.0 (Beta)

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:

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.