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.