Merging variants rule

How to merge item variants

In this post you will learn:
  • What is the use of the rule Merge variants of items
  • How to recognize a format that is so-called variant
  • Setting the Merge variants rule
  • Example of the most common use (Heureka → Shoptet]
  • Frequently asked questions and answers

What is the Merging variants rule for?

:warning: Important Note: Currently, this new Merge Variants rule is only available to the :mergado: Research group user test group. Stay tuned as we will soon make it public for every one.

The rule is intended to ensure the conversion of several separate products that form a group of items within the input feed, combined (most often) using the ITEMGROUP_ID element. The Shoptet format is then complete at the output).

For example, within the Heureka feed, different sizes, colors, patterns, product sets can be variants. The same group of these products is then marked in the feed in the ITEMGROUP_ID tag.

In the feed, these variants are then treated as separate products that have the same value within the ITEMGROUP_ID element

On the other hand, other formats, such as Shoptet or UpGates, have product variants embedded within the main item - the so-called Master product, which contains variants.

The Variants Merging rule can thus ensure conversion between formats that have variants separately and those that have them “combined” within the Master product.

Graphical representation of the merging of multiple products forming variants into “one product with variants”:

How to recognize a format that is so-called variant

Sample feed with ITEMGROUP_ID:
(Feed Heureka, 3 color / size variants)
The individual variants are here as separate items bounded by the SHOPITEM element and grouped using the ITEMGROUP_ID, which has the same value “34”.

Conversely, within the Shoptet feed, individual variants are located within the Master product and are delimited by the VARIANT element.

Sample feed with Master product:
(One item with 3 variants inside)

If you look at the structure of the variant feed, you can see that some elements are common to all variants (typically item name, category, images,…) and some elements are only included in the variant ( EAN, price, item code,…)

This is logical, as it is assumed that, for example, the location of an item within an e-shop category will always be identical. On the contrary, the price, EAN, availability, codes of individual items will often be different and therefore these data must be listed directly with the variant.

And the rule for Merging Variants allows you to precisely define the behavior you want - that is, the placement of each element within the feed:

  • Common element
  • Variant element located directly next to the variant

Sample of common elements in the Master product:

:pushpin: The philosophy behind the Merge Variant rule is as follows:
When the element is set as part of the Merging Variants rule, it is a “Common Element”. If the element is not set within the merge rule, it will be transferred to the variant of the item.

How to set the Variant Merging rule:

Sample rule setting:

1. Master item selection element
It is used to define an element that will be used to search for a suitable “Master Item”, under which all variants fall.

I want to know more exactly how the Master Item option works
  • Example: If the ITEM_ID element is selected, the system will search for the most suitable item within the item ID value as follows:

    • First it looks to see if the item ID happens to be the same as the ITEMGROUP_ID. If so, this will be the Master item under which all variants will fall. “Common elements” will then be taken from the Master product

    • In the case when the ITEMGROUP_ID is different from the ID of all items within the group of variant items, the so-called Lexicographic order is used - more info [here](�% A9_uspo%C5%99%C3%A1d%C3%A1n%C3%AD).
      Simply put: If we were to take as a sample solution a situation where item IDs are only numerical values, then we can say that: “The master item will always be the variant with the lowest number” :wink:

    • In the event that no value was specified for even one item within the ITEM_ID element, the (lowest value) Mergado ID will be used for the calculation. The Mergado ID is an internal item identifier that is assigned by the system during data import and is always available.

2. Element with association code
Specifies an element that contains an ID used to combine variants into one item. Most often, this element is ITEMGROUP_ID. The code in this element must be identical for all variants of one item.

3. Element selection field
Select the elements that should be common to all variants of the item.

Subsequently, select the type of action, how the values are to be taken from the variants (or originally separate products at the input that form a group with the same ITEMGROUP_ID).

4. Action type:

  • Copy from Master Item
    The value is taken from the element that is listed in the Master item. By default, that is, the item that has the lowest ITEM_ID from the group of all items with the same ITEMGROUP_ID.

  • Merge values from variants
    Takes the values from the elements of all items with the same ITEMGROUP_ID and merges them.

If the elements have the same value, the data is merged. If the elements have different values, then the elements are listed multiple times, see the IMAGE element in the example above.

How to properly prepare data for Merging Variants in case of Shoptet format

In the following example, we will show you how to prepare data for the Shoptet platform using the Variant Merging rule. In our sample example, we will count on the fact that we have the Heureka format as input, which has the ITEMGROUP_ID set for the items.

:information_source: For the future, we are preparing automated rule settings for the most frequently used “variant formats” - Shoptet / Upgates. However, for now, the correct settings need to be ensured by you when creating the rule.

Set the Variant Merge rule correctly

  1. Set the element ITEM_ID in the field called Element for selecting the Master item.
  2. Then select the ITEMGROUP_ID value as the Element with the grouping code.
  3. Set all elements that are supposed to be common to all variants + define the action you want:


Note: Other Shoptet elements and their recommended placement can be found here.

Select the parameters that make up the product variant (color / size,…)

This is a key part of the whole process. In this phase, it is first necessary to ensure the preparation of data for variant items before the actual merging of variants, which only takes place as part of the data export. Currently, the rule does not yet create the product parameters during export, but ensures “only” the creation of the correct variant feed structure.

Appropriate parameters must therefore be pre-prepared by the Bulk copy values rule, from the PARAM element on the input format side and added to the PARAMETERS elements.

The Merging variants rule will then ensure the conversion of the copied parameters into the correct structure within the variant feed.

So the following procedure is as follows:

1. Create helpers for future parameters
On the Elements page, first create new elements for the parameters in the scheme shown in the figure below, so that the rule set in point 2 has somewhere to copy the individual values.

:warning: Important: It is necessary to ensure the creation of new PARAMETERS elements at the first level of the format structure, i.e. immediately below the SHOPITEM element. In case you copied the values straight into the VARIANTS | VARIANT | PARAMETERS will not be the correct solution, paradoxically.

In this case, an item that already contains a variant structure would be prepared before the Merging variants rule, and the Merging variants rule is set in such a way that it does not interfere with items that already have a variant structure set and "only takes the already created variant and moves it to Item master.

This behavior is intentional and is meant to respect the structure of already pre-made variants for items and not interfere with the form of variants of such products.

2. Choose the appropriate parameters that should form the variants (color, size,…)
As part of the input feed, the parameters may also contain values that are not important to us (pattern, destination, product type, etc.), but which are not suitable for the parameters. In addition, the Format Converter has already converted these data into TEXT_PROPERTY elements.

It is therefore necessary to set which parameters are important to us (in our case, color and size) and these should form product variants.

:information_source: In the future, the setting of the parameter selection will be addressed directly in the setting of the Merge variants rule. However, at this stage it is necessary to ensure the creation of this auxiliary rule.

Use the rule Bulk copy values to set the transfer of information about the color, size and any other parameters that make up the variant and should thus be listed for the product variant.

Sample rule setting:

3. Create an optimal name for variant products
Do not forget that the name of one of the variants of the item will be the common name for all variants of the product after the variants are merged. However, it should be taken into account that the names may contain information about size and color of the item, which is undesirable for you at this time.

A typical example of variant item names:

  • Short-sleeved T-shirt Color: White, Size: M
  • Short sleeve T-shirt Color: White, Size: XL
  • Short-sleeved T-shirt Color: Red, Size: S
  • Short-sleeved T-shirt Color: Green, Size: XXL

As you can see such a name is undesirable for us. Within the Mergado Editor, however, we can create a new Variable, within which using a regular expression we will process the names of the items to suit our needs.

Sample variable setting:

The above settings will ensure that:

  1. A new variable named Name_without_variant is created
  2. The new variable will contain the original name of the item, which will be cleaned with text related to the size and color of the item

The regular expression we used here is: (.*?)(?=\s*Color|\s*Size)(.*)

Then you just set this variable with the Rewrite rule as a new value to the NAME element for variant items.

:information_source: Of course, you can modify the regular expression as needed, taking into account the names of the selected parameters.

:information_source: It is ideal to set the restriction of the rule only to the selection of items that have the ITEMGROUP_ID element set, so that you do not needlessly edit items that are not supposed to be variants in the future.

Questions and Answers:

(click on the title to see the answer)

Why don't I have the Merge Variants rule available at all in the rules selection?

The Merging variants rule is only available if a format that supports the variant element is set on the output within the project. Currently they are Shoptet formats (complete / supplier), UpGates, Pepita, Samba, Spartoo, or even your “Custom format”, which has a “variant” element defined.

[details=“Why can’t I see merged products on the Products page even after turning on the “Merge variants” rule?”]
The rule for Merge Variants is currently resolved in such a way that products are merged only within the export of items. In the future, however, we plan to ensure that merged items are displayed before export.

What if I want to work on the products page with already merged products?

At the moment, the only solution is to “chain” projects to each other. In the first project, you ensure the merging of variants and use the output feed with the already merged data from the first project as the “input feed” for the second project. This way (in the second project) you will already have merged data on the Products page and will be able to work with them easily.

How can I quickly find out on the Products page from which item the data common to all variants will be taken?

Under the name of the item, information is placed as to whether it is a Master product from which common information is taken.

At the same time, it is possible to click on a link that will display all items that will make up future variants:

!! x24bbONdbuASgCRdzo1Wzw-kxIz4ddYdg)

At the same time, for each (future) variant of the item, you can see info about which item is the main item:

!! Gvu3gtIhH2c1xIopFX7q1KgCHBoeDf35BfO9Y)

How to ensure the ideal Master Item Name?

This is possible using the Variable function as described above in the section titled:
How to correctly prepare the data for the Merging variants rule in the case of the Shoptet format.

Is it possible to use the Merge Variants rule even when I have variant formats not only on the output but also on the input?

Yes, it is possible. Running this rule is only possible if there is a variant format at the output, but it can also be used in the case of purely variant formats at the input and output at the same time.

A typical example may be the need to ensure the merging of color variants of items that are entered, for example, in the Shoptet format, but at the same time are listed as separate products. However, you need to ensure that they are merged so that they are then listed as one item that has color variants as part of the import to Shoptet.

The solution is to create a “merged element”, which will be hidden in the output and thus used only for the Merging variants rule.

Why can't I change the order in which the Merge Variants rule is applied?

The actual merging of the variants is only implemented when the data is exported. That’s why the Merge Variants rule is always the last rule in the sequence.

Why did Mergado take so long to develop the Merge Variants rule?

The merge rule is one of the most complex rules we’ve dealt with. The rule is unique across the entire Mergado application in that it works with values from multiple products within a feed. All other rules only work with values that are placed within one item (a group of elements bounding the item).

We believe you will welcome the rule. Of course, we plan to further develop the rule based on feedback. :slightly_smiling_face:

:information_source: Do you want to try the Merge Variants rule now?
Write to us at and we will make it available to you now.

1 Like