{
"products": [
{
"targetDemographic": {
"value":"MENS" // Supported
}
},
{
"targetDemographic": {
"value":"Men's" // Also supported
}
}
]
}
- v1.0.0-latest-prod
This document covers unique behavior, advanced features, and configuration options for the comprehensive product endpoint. This includes custom Data Driven Enum configuration, product option generation, and pricing.
When class names are mentioned, unless the classes belong to another service (e.g. Product, DataDrivenEnum`), they will be referring to classes located in the com.broadleafcommerce.dataexchange package or a child of this package — typically com.broadleafcommerce.dataexchange.service.catalog
During the creation/update of a product, Data Driven Enums are read in bulk at the beginning of the persistence flow. Reads are supported on the DataDrivenEnum#name or DataDrivenEnum#displayValue fields.
All out of box fields on the Product domain are supported by default. This includes brand, merchandisingType, targetDemographic, etc.
Assume we have a target demographic enum with name "MENS" and displayValue Men’s as the display value. A basic example of providing a targetDemographic for a product is shown below:
{
"products": [
{
"targetDemographic": {
"value":"MENS" // Supported
}
},
{
"targetDemographic": {
"value":"Men's" // Also supported
}
}
]
}Custom fields utilizing Data Driven Enums on the Product domain are supported without need for extension/customization and may be configured via property. Both Collection<DataDrivenEnum> and single DataDrivenEnum custom fields are supported.
The structure of the properties is:
broadleaf:
dataexchange:
catalog:
data-driven-enum:
custom-mappings:
property-name-on-my-custom-product:
type: {{ data-driven-enum-type }}
collection: {{ true|false }}The collection property is optional and defaults to false.
Assume we have this product extension:
public class CustomProduct extends Product {
private Collection<DataDrivenEnum> colors;
private DataDrivenEnum size;
}If colors has a DataDrivenEnum#type of COLOR and size has a type of SIZE, the following configuration would be required:
broadleaf:
dataexchange:
catalog:
data-driven-enum:
custom-mappings:
size:
type: SIZE
colors:
type: COLOR
collection: trueThese values will now be automatically resolved when supplied on the request payload.
Extension should generally not be necessary, but if required there is a single class responsible for the resolution of Data Driven Enums. This is DataDrivenEnumBatchLoaderProcessor. The high level flow is:
Collect all enum types/values supplied in the request payload
Query the catalog service for all Data Driven Enums where type=[type] and value in [values]
Populate the id of found Data Driven Enums on the request payload. If a Data Driven Enum is not found, an error will be returned, informing the caller of which enum was not found.
Option generation via option templates/template groups is supported by the comprehensive product endpoint. Generation simply requires the user to supply a template type (defaults to TEMPLATE) and template name.
Both OptionTemplate and OptionTemplateGroup are supported. To generate product options, supply the generateOptions array as a field on the product.
From an API consumer perspective, the two relevant fields on the generateOptions object are generationType and templateName. generationType is optional and defaults to TEMPLATE, which will generate options from an OptionTemplate. To generate options from a OptionTemplateGroup, set generationType to TEMPLATE_GROUP. templateName should simply be the name of the template or template group.
For example, to generate options from a template named "Sizes", this would be a field on a product in the supplied payload:
{
"products": [
{
"name": "T-Shirt",
"generateOptions": [
{
"generationType": "TEMPLATE", // Optional. Defaults to TEMPLATE. May also be TEMPLATE_GROUP
"templateName": "Sizes"
}
]
}
]
}When generate options are supplied on the request, a read request is made to the catalog service to retrieve the template or template group. The IDs of the templates are then set on the product. This behavior occurs in DefaultOptionTemplatePreloader.
Actual option generation is its own step and must occur after the product is saved. In the Data Exchange service, the behavior is that option generation occurs immediately after the product is saved, before other product related entities (assets, variants) are handled. As a result, this step occurs in the same handler that persists the product. To extend or customize the behavior, see ProductBatchItemHandler#generateProductOptions.
The Comprehensive Product API integrates with Broadleaf’s Pricing service and allows the user to supply product pricing information in the request payload. The most basic implementation requires that the user supplies a price list ID and price data for the product. However, currency based pricing is supported and may be used in cases where the system supports multiple currencies and has a single price list per currency.
ID based lookup is the default behavior. ID based pricing requires that the user knows the ID of the price list they wish to associate with the product. The price data is then supplied in the request payload. For example:
{
"products": [
{
"name": "T-Shirt",
"sku": "T-Shirt-Sku",
"prices": [
{
"identifier": "price-list-id",
"identifierType": "ID", // Optional. Defaults to ID
"priceData": [
{
"target": {
"targetId": "T-Shirt-Sku",
"targetType": "SKU"
},
"price": {
"amount": 10.00,
"currency": "USD"
},
"activeStartDate": 1738887572.500748000 // Optional. Defaults to current time
}
]
}
]
}
]
}Multiple price lists and price data may be supplied in the request payload. The targetType field will typically be SKU, but may be any target type that is supported by the system, such as PRICING_KEY.
Currency based pricing is supported by setting the identifierType to CURRENCY. This informs the system that it should look up price lists by currency code. The identifier field is not required for currency based pricing. The currencies are determined by the currency field on the price object.
The CURRENCY type supports specifying prices for STANDARD or SALE price lists.
An example payload for currency based pricing is shown below:
{
"products": [
{
"name": "T-Shirt",
"sku": "T-Shirt-Sku",
"prices": [
{
"identifierType": "CURRENCY",
"priceListType": "STANDARD", // STANDARD or SALE
"priceData": [
{
"target": {
"targetId": "T-Shirt-Sku",
"targetType": "SKU"
},
"price": {
"amount": 20.00,
"currency": "USD"
}
},
{
"target": {
"targetId": "T-Shirt-Sku",
"targetType": "SKU"
},
"price": {
"amount": 25.00,
"currency": "EUR"
}
}
]
}
]
}
]
}The identifierType defaults to ID, but may be configured to another value via property. To set CURRENCY as the default, for example, use the following configuration:
broadleaf:
dataexchange:
pricing:
price-list:
default-identifier-type: CURRENCYSimilar to enums and option templates, price data/lists are read in bulk at the beginning of the persistence flow.
DefaultPriceDataPreloadProcessor is responsible for pre-loading existing price data, price lists, and setting IDs as appropriate. This class may be extended if custom behavior is required. Alternately, common functionality that may be useful for a completely custom implementation (for example, a custom price identifier type) can be inherited by extending AbstractPriceDataPreloadProcessor.
Actual persistence of price data occurs in PriceDataBatchItemHandler, though extension of this class is generally not necessary as all required data for persisting price data should be populated by DefaultPriceDataPreloadProcessor.
Product assets are difficult to determine whether they should be created or updated without the user supplying an entity ID. As a result, the system treats the supplied product asset array as a complete replacement of the existing assets. There are two exceptions to this behavior:
If the payload contains an entity ID, the system will attempt to update the existing asset.
If an existing asset and an asset on the payload have the same URL, the system will assume these are the same asset and update the existing asset.
As is the case with every other product related entity, to perform no product asset operations the assets field should be omitted from the product payload.
Because assets are treated as a complete replacement, assets are deleted before all other product related entities are handled. Finding and deleting assets occurs in ProductBatchItemHandler#deleteAssetsFuture.
Actual persistence of assets is handled in ProductAssetBatchItemHandler. This class doesn’t do anything particularly special aside from persisting the assets and their translations.