Product enrichers
Product enrichers offer a way to add, replace, set, and update attributes of product catalogue items. This process is called enrichment hence the name enrichers.
Product catalogue items have an attribute collection, which is the container of attributes found on the product details page in the tabbed area.
Product enrichers themselves also have an attribute collection similar to products. An enricher's attribute collection serves as a template for enriching a product - in correspondence with the target and merge rules defined on the enricher.
Feature highlights
Product enrichers are a great tool to increase the efficiency of the product enrichment process. By linking one or multiple enrichers to product categories, or by manually running enrichment bulk operations, the following benefits become available:
- Automate the product enrichment process, by enriching products when placing them into categories.
- Define presets of attributes for specific product categories, to make sure certain types of products get populated with predefined attributes.
- Flexible merge rules allow for easy configuration, either for the entire attribute collection or for individual attributes.
Running a product enricher
There are two main ways of running product enrichers:
- Upon placement of products into a category
- As a manual bulk operation
Both ways have their own benefits, so it's important to consider which one best fits the use case.
Upon product placement into a category
Linking product enrichers to a category is typically relevant in the following cases:
- To make sure products within a specific category always have certain attributes/attribute values assigned to them.
- For automating part of the initial product enrichment process, by automatically assigning attributes/attribute values when placing products into a category.
As a manual bulk operation
Manually running the Enrich products bulk operation is typically relevant in the following cases:
- When changes have been made to the enricher configuration on a category, as those will be applied by triggering the enrichers associated with a category using the bulk operation.
- To run a custom set of product enrichers on a selection of products from the product list page.
Order in which enrichers are applied
Since it's possible to link multiple product enrichers to a category and categories are hierarchically structured, it's important to understand in which order enrichers are run. If multiple product enrichers touch the same attributes, the running order defines how the products are eventually affected.
Running order of product enrichers
The following rules apply when determining the running order of product enrichers based on categories:
- Multiple enrichers on a single category are run in reverse order as they're listed on the category, the bottom one first and the top one last.
- Categories on the same level in the hierarchy are handled from the bottom up. Enrichers on the bottom category are applied first, and enrichers on the top category are applied last.
- Inherited enrichers on a category are run before the enrichers linked to that category.
- Enrichers linked to a category marked as
Primary
are always run as the final ones in a sequence.
The reason for applying the running order from the bottom up is that categories/enrichers on the top of the list are considered more important, hence they should be applied last.
In the example box below, a visual shows two different cases of how a single product is placed into multiple categories. Each case has a different outcome regarding which attributes are being set on the product, depending on the running order of product enrichers.
Example
Given the following hierarchy with product enrichers linked to categories on multiple levels:
Placing a product into categories from the example hierarchy shown above, would lead to the following result:
Configuring a product enricher
Target
When setting up an enricher, the first thing to determine is what kind of products the enricher should affect. Think of the target as a filter that ensures the enricher only affects products that are meant to be enriched.
This is especially relevant during automatic enrichment based on product's primary category placement where we don't control exactly which products the enricher is told to enrich.
As illustrated above, there are two options.
- SKU / Variant
- Master At Level
Tip
Read more about master/variant hierarchies to learn about how this can improve the product data model.
The SKU / Variant option ensures that only products that are at the bottom level in a master/variant hierarchy (the variant level) and products that don't have a master (SKUs) are affected by the enricher.
The Master At Level option ensures that only products that are masters (by definition these are products that have variants) are affected by the enricher. The level must be specified such that 0 means top level master, 1 means masters that are immediate children of top level masters and so on.
Note
If there are no master/variant hierarchies for the products the product enricher is applied on, the Master At Level
option does not have any effect. In that case the SKU / Variant
option has to be used.
Merge rules
Merge rules determine how PIM merges an attribute from the enricher's attribute collection into the target product's attribute collection.
As illustrated above, there are four top level merge rules:
- Add New
- Add New or Replace
- Merge
- Replace
When an enricher is about to update a product, it reads the merge rule and analyzes the existence and non-existence of attributes on the product and figures out what it's allowed to do based on that. The following describes the implications of the various rules given specific cases that might occur.
General rules vs. specific rules
General rules are rules that apply on the entire attribute collection as it is on enricher. It's not possible to specify that some attribute should be handled one way and another attribute in another way. All attributes in the attribute collection are handled the same way. The following rules are considered general rules:
- Add new
- Replace existing
- Add new or replace existing
These rules are the easiest to manage and maintain, as they don't require any configuration, but allow least flexibility.
Specific rules are rules that apply on a single attribute in the attribute collection. The specific rules are bundled under the top-level rule called Merge
.
General rules
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be added to product exactly as is. |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | No | Unaffected by enricher since rule determines that it should only be added if it's new (meaning if it doesn't exist there) |
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | No | Unaffected by enricher since rule determines that it should only be set on target if it exists already on the target |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Attribute and value will be overwritten on the product such that it gets the same value as that of the enricher |
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be overwritten on the product such that it gets the same value as that of the enricher |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Attribute and value will be overwritten on the product such that it gets the same value as that of the enricher |
This is a hybrid of Add new
and Replace existing
.
Specific rules
When a product enricher requires a more specific configuration than what the general rules can provide, specific merge rules can be used to achieve this. The top-level Merge
rule allows specifying individual merge rules per attribute. This makes it the most flexible rule but also comes with a higher level of complexity, especially if there's a large number of attributes in the collection.
By choosing the Merge
merge rule, a new section is shown where specific merge rules can be configured for each attribute. For each selected attribute an individual merge rule should be set, which defines how that specific attribute should be handled by the product enricher.
The Merge Rule
dropdown offers the following options.
Merge rule | Description |
---|---|
Remove | Removes an existing attribute |
Add new or replace | Adds the attribute or replaces the value of an existing attribute |
Add new or replace single valued / append multi valued unless exact value is already in value list | Adds the attribute or replaces the value of an existing attribute if it is a single valued attribute. If the attribute is multi valued, the value is appended unless the exact value already exists in the value list. |
Add new or replace single valued / append multi valued | Adds the attribute or replaces the value of an existing attribute if it is a single valued attribute. If the attribute is multi valued, the value is appended to the value list without affecting other items |
Add new or replace single valued / append multi valued unless part of value is already in value list | Adds the attribute or replaces the value of an existing attribute if it is a single valued attribute. If the attribute is multi valued, the value is appended unless part of the value already exists in the value list. This rule is specifically designed to deal with segmented types such as translated strings. |
How each of these merge rules affects an attribute, depends on whether the attribute is single valued or multi valued.
Single valued attributes
All merge rules whose name starts with Add new or replace single valued and the Add new or replace rule act the exact same on single valued attributes. They are equivalent.
The scenarios for these are:
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be set on the product such that it gets the same value as that of the enricher |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Attribute and value will be overwritten on the product such that it gets the same value as that of the enricher. For segmented types this means that all segments will be overwritten on the product |
For the Remove rule it applies that attribute and its value will be removed entirely from the product in all cases.
Tip
The attribute doesn't need to be added to enricher's attribute collection for the Remove rule to work. The rule itself is enough.
Multi valued attributes
For multi valued attributes, there are three different merge rules that each affect an attribute differently.
This is the simplest rule to understand as it has no specific conditions.
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be set on the product such that it gets the same value(s) as that of the enricher |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Values on enricher will be appended to the existing value(s) on the product regardless of whether they exist already. Note, this might lead to duplicate values on products. |
This rule expands upon the previous one by putting a condition on it. This rule only appends values that don't already exist on product.
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be set on the product such that it gets the same value(s) as that of the enricher |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Values on enricher will be appended to the existing value(s) on the product but only if the value doesn't exist among the values already. For non segmented types this is straight forward to understand. For segmented types this means that if all segments of value(s) exist on product already then those values won't be appended |
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be set on the product such that it gets the same value(s) as that of the enricher |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Values on enricher will be appended to the existing value(s) on the product but only if the value doesn't exist partly among the values already. For non segmented types this rule is equivalent with the previous rule. For segmented types this means that if some segments of the value(s) exist on the product already then those values won't be appended. |
Scenario | Product updated | Outcome on product |
---|---|---|
Attribute only on enricher | Yes | Attribute and value will be set on the product such that it gets the same value as that of the enricher |
Attribute only on product | No | Unaffected by enricher since enricher doesn't touch attributes that aren't in its attribute collection |
Attribute on both enricher and product | Yes | Attribute and its value(s) will be overwritten on the product such that it gets the same value(s) as that of the enricher. Value that were on the product and not on enricher will thereby be removed from product. |
For the Remove rule it applies that attribute and its value(s) will be removed entirely from the product in all cases.
Tip
The attribute doesn't need to be added to enricher's attribute collection for the Remove rule to work. The rule itself is enough.