Introduction
Webshops sell products. Which product is available for the end customer and which is not may depend on many conditions. For example:
- Does the product have a price?
- Is the product assigned to at least one category?
- Does the product have a long description?
- etc
In a shop hosting thousand or even million of products the management of all these conditions may become cumbersome and error prone. The product completeness check provides the possibility to perform an automated data validation. The rules that are applied to the products should be customizable and in the same time custom projects should be able to easily implement their own rules. This document provides a high overview of the product completeness check framework. Specific tasks are described in a separate cookbook.
The product completeness check framework uses the services provided by the object validation framework. Thus knowledge of this framework is required for the understanding of the concepts behind product completeness.
The terms completeness check and validation are used interchangeably in the present document.
References
Cartridge Structure
The whole feature is implemented with a single cartridge - bc_product_validation. The cartridge contains:
- Definition of completeness check rule descriptors
- Definition of completeness check rule configurations and the related BO layer
- Implementation of the BO layer, based on ORM
- Standard rule implementations
Completeness Check Rule Descriptors
A completeness check rule in the object validation framework is a statically defined piece of code that is able to validate an object and produce a validation result. However, the default implementation is not sufficient for a proper Product Completeness Check.
- The validation rules need to be configurable by the shop managers (e.g., a product needs descriptions that are longer than 150 characters).
- These configurations must be persisted.
Thus a new entity - validation rule configuration had been introduced. It consists of a dynamic configuration and a static part which represents the completeness check rule in terms of the object validation framework. The static part is named validation rule descriptor. It contains the ID of the rule, references to several ISML templates that are used to represent the rule to the shop manager as well as references to some pipelines that can process rules and attach dynamic configurations to them.
Completeness Check Rule Configurations
The completeness check rule configuration is a dynamic configuration attached to a static rule. Rule descriptors and rule configurations are similar to classes and objects (instances) of these classes. A BO layer is defined which is able to manage validation rule configurations and retrieve a list of validation rule descriptors. The configurations are stored in the database through the ORM layer.
On the image below you can see the rule description (1) and the dynamic configuration (2) attached to it and the desired action (3) to execute if the product validation fails.
Product Assortments
A product assortment descriptor is used in the product validation process in order to provide products to be validated. The name of the assortment and its type must be persisted. Thus a new entity - product assortment had been introduced. It contains the ID of the assortment, references to a editing ISML that is used to display the information to the shop manager as well as to reference some pipelines that can process assortments.
On the image below you see the product assortment description (1) and the type of the assortment (2) (All, Category and etc).
Wiring It Together
The next diagram summarizes the interfaces discussed so far.
The table below describes the used interfaces.
| Interface | Description |
|---|---|
| ValidationRuleDescriptor | Describes a validation rule. This is a description of a class of rules that can be instantiated. For example - the rules for the validation of standard product attributes. Each specific rule descriptor implementation should implement this interface. The rule descriptors are registered in a container for rule descriptors with the componentization FW. The descriptor should be able to return an instance of ValidationRuleFactory. The factory is the "bridge" between the product validation and object validation frameworks. Later these factories are used to create a custom ValidationRuleSetProvider and feed it to the object validation FW. |
| ValidationRuleDescriptorCtnr | Describes a container for validation rule descriptors. New rule implementations register themselves in the provided container. The container itself is used by the BO repository. |
| ValidationRuleAction | Describes a validation rule action. For example - for all products that fail the product validation the online status has be changed to offline, thus no invalid products are online. Each specific rule action implementation should implement this interface. The rule actions are registered in a container for rule actions with the componentization FW. |
| ValidationRuleActionCtnr | Describes a container for validation rule action. New rule actions register themselves in the provided container. The container itself is used by the BO repository. |
| ValidationRuleConfigurationBO | Describes a dynamically configured rule. Consists of dynamic configuration represented by a Configuration instance as well a static part represented by a ValidationRuleDescriptor. |
| ValidationRuleConfigurationBORepository | Manages the life-cycle of ValidationRuleConfigurationBO- s. |
| ProductValidationAssortmentDescriptor | Describes a product validation assortment. This is a description of a class of assortmentss that can be instantiated. For example - the assortment for all the products in the system. Any concrete valiation assortment descriptor implementation should implement this interface. The validation assortment descriptors are registered in a container for rule descriptors with the componentization FW. |
| ProductValidationAssortmentDescriptorCtnr | Describes a container for product assortment descriptors. New product validation assortment implementations register themselves in the provided container. |
Register New Rules
Custom projects may want to add new product validation rules to the system. This happens in the following steps:
A class that implements ValidationRuleDescriptor should be implemented, e.g.:
public class ProductBOStandardAttributeValidationRuleDescriptor implements ValidationRuleDescriptor { }The validation rule descriptor should be registered into the descriptor container. The provided container implementation in bc_product_validation is named ProductValidationRuleDescriptorCtnr:
<implementation name="ProductValidationRuleDescriptorCtnr" class="com.intershop.component.product.validation.internal.config.ProductValidationRuleDescriptorCtnrImpl"> <requires name="validationRuleDescriptor" contract="ValidationRuleDescriptor" cardinality="0..n"/> </implementation>The instance in which the custom projects are expected to wire their rule descriptors is named ProductValidationRuleDescriptorCtnrInst. Below is an example that shows the registration of a rule descriptor.
<instance name="ProductValidationRuleDescriptorCtnrInst" with="ProductValidationRuleDescriptorCtnr"> <fulfill requirement="validationRuleDescriptor"> <instance with="ProductStandardAttributeValidationRuleDescriptor"> <fulfill requirement="compoundResultValidator" with="ProductBOCompoundStandardAttributeResultValidator"/> </instance> </fulfill> </instance>
Register New Actions
Custom projects may want to add new product validation actions to the system. This happens in the following steps:
A class that implements ValidationRuleAction should be implemented, e.g.:
public class ProductBOChangeOnlineOfflineStatusValidationAction implements ValidationRuleAction<ProductBO> { }The validation rule descriptor should be registered into the descriptor container. The provided container implementation in bc_product_validation is named ProductValidationRuleActionCtnr:
<implementation name="ProductValidationRuleActionCtnr" class="com.intershop.component.product.validation.internal.config.ProductValidationRuleActionCtnrImpl"> <requires name="validationRuleAction" contract="ValidationRuleAction" cardinality="0..n"/> </implementation>The instance in which the custom projects are expected to wire their rule actions is named ProductValidationRuleActionCtnrInst. Below is an example that shows the registration of a rule descriptor.
<instance name="ProductValidationRuleActionCtnrInst" with="ProductValidationRuleActionCtnr"> <fulfill requirement="validationRuleAction"> <instance with="ProductChangeOnlineOfflineStatusValidationAction"/> </fulfill> </instance>
Register New Product Assortment
Custom projects may want to add new product validation assortments to the system. This happens in the following steps:
A class that implements ProductValidationAssortmentDescriptor should be implemented, e.g.:
public class AllProductsValidationAssortmentDescriptor implements ProductValidationAssortmentDescriptor { }The validation assortment descriptor should be registered into the descriptor container. The provided container implementation in bc_product_validation is named ProductValidationAssortmentDescriptorCtnr:
<implementation name="AllProductsValidationAssortmentDescriptor" class="com.intershop.component.product.validation.internal.assortment.AllProductsValidationAssortmentDescriptor"/>
The instance in which the custom projects are expected to wire their assortment descriptors is named ProductValidationAssortmentDescriptorCtnrInst. Below is an example that shows the registration of an assortment descriptor.
<instance name="ProductValidationAssortmentDescriptorCtnrInst" with="ProductValidationAssortmentDescriptorCtnr"> <fulfill requirement="productValidationAssortmentDescriptor"> <instance with="AllProductsValidationAssortmentDescriptor"/> </fulfill> </instance>
DBinit for Product Completeness
A customer may want to create predefined validation rules and assortments. For that purpose, there are preparers that use property files to persist in database.
- For initializing validation rules can be used ProductValidationRulePreparer ( bc_product_validation ). For more info about property file content, take a look at preparer source code.
If there is a need to do customized processing of an attribute value, a handler class needed to be implemented. There is our of the box such handler implementation - for "Category Assignment Rule" - AttributeValueClassificationCatalogTypeHandler.
- For initializing validation assortments an ProductValidationAssortmentPreparer (in bc_product_validation ) can be used. For more info about property file content, take a look at preparer source code.
If there is a need to do customized processing of an attribute value, a handler class needed to be implemented. There is out of the box such handler implementation - for "All Products in Selected Category/ies" - AttributeValueCategoriesTypeHandler.
In ucm_demo cartridge there are 2 property files - for rules and assortment initialization - ValidationRules.properties and ValidationAssortments.properties.