Skip to content

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.

Attribute collection as shown on the product details page

Attribute collection as shown on the product details page

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.

A product enricher linked to a category

A product enricher linked to 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.
  • By selecting 'Product Hierarchy' enrichers will be run based on the current categories the products in the bulk operation are placed in.
    By selecting 'Product Hierarchy' enrichers will be run based on the current categories the products in the bulk operation are placed in.
  • By selecting 'Product Enricher(s)' one or multiple product enrichers can be selected to run on the products in this bulk operation.
    By selecting 'Product Enricher(s)' one or multiple product enrichers can be selected to run on the products in this bulk operation.

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:

Example of product enrichers attached to categories
Example of product enrichers attached to categories

Placing a product into categories from the example hierarchy shown above, would lead to the following result:

Result of product enrichers after running the place product bulk operation
Result of product enrichers after running the place product bulk operation

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.

Selecting a product enricher's target

Selecting a product enricher's target

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.

Four top level merge rules are available

Four top level merge rules are available

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.

  • Configuring merge rules for individual attributes
    Configuring merge rules for individual attributes
  • Configuring a specific merge rule for the 'Description' attribute
    Configuring a specific merge rule for the 'Description' attribute

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.