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 enricher.
Product catalogue items have a so-called 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.
Target
When setting up an enricher the first thing to determine is what kind of products the enricher should affect. Think of target as a filter that ensures that the enricher only affects products that is 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 there are two options.
- SKU / Variant
- Master At Level
The SKU / Variant option ensures that only products that are a 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, always use the SKU / Variant option.
Merge rules
Merge rules determine how PIM merges an attribute in the enricher's attribute collection into the target product's attribute collection.
Consider a common scenario. What should happen if product already has the attribute on it? Should it it be overridden? Should it be omitted?
Before getting further into this, let's go through the merge rules.
As illustrated there are four rules.
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 based on that. The following describes the implications of the various rules given specific cases that might occur.
General rules
General rules are rules that work 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.
These rules are the easiest to manage and maintain but allow least flexibility.
Add new
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) |
Replace existing
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 |
Add new or replace existing
This is a hybrid of Add new and Replace existing.
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 |
Specific rules
If there are special rules that apply to different attributes, then the Merge merge rule (don't be confused about the name - it is a specific merge rule called merge) is the way to handle it.
This top level rule allows specifying individual merge rules per attribute. This makes it the most flexible rule but also the one most difficult to maintain. Especially if you have many attributes in the collection.
Merge
By choosing the Merge merge rule, this screen will appear:
We choose the Description attribute as an illustrative example.
The Merge Rule dropdown offers the following options.
Merge rule | Description |
---|---|
Replace single valued / append multi valued unless exact value is already in value list | 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. |
Replace single valued / append multi valued unless part of value is already in value list | 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. |
Replace single valued / append multi valued | 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 |
Replace | Replaces the value of an existing attribute |
Remove | Removes an existing attribute. |
Single valued attributes
All merge rules whose name starts with Replace single valued + the Replace rule act the exact same on single valued attributes. They are equivalent.
The scenarios for those 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
Replace single valued / append multi valued
This 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. |
Replace single valued / append multi valued unless exact value is already in value list
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 tose values won't be appended |
Replace single valued / append multi valued unless part of value is already in value list
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. |
Replace
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.