Bulk copy values

[lehuy]

In this post, we will learn:

• How does the rule work?
• How to copy a structure?
• Most common uses
• Summary

What is it used for?

The basic principle of the rule is that the MERGADO Editor takes the values from the selected source element and copies them to the selected target element. The advantage is that this can be done in bulk for multiple elements within a single rule.

How does the Bulk copy values rule work?

In this section, we’ll describe how the rule works, what it can do, and what to watch out for.

Basic principle

The rule works intuitively. Consider the example XML feed, where the output looks like this:

It’s missing the IMGURL element containing the image URL, because we used a non-standard OBRAZEK1 element in the input. But we want the image URL here. So we use the Bulk copy values rule, where we select OBRAZEK1 as the source element and IMGURL as the target element.

After the re-generation, the IMGURL element will now appear in the output with the image URL we want.

The order of the lines matters

In the rule, the order of the lines matters. The values are copied line by line. First the value on the first line is copied, then the value on the second line, and so on. This means that if there are multiple rows, the value of the earlier row can be worked with on the later row. Let’s explain this with an example:

In the example, the value of the PRICE_VAT element is copied to the PRICE element on the second line. The PRICE element therefore now contains the original value of the PRICE_VAT element. Only after this copy on the second line, the value of the CENA element is copied to the PRICE_VAT element on the third line. So the PRICE_VAT element now contains the value of the CENA element.

If we swap the order of the second and third lines in the example, we get:

where first on the second line we copy the value of the CENA element to the PRICE_VAT element and then on the third line we copy the new value of the PRICE_VAT element to the PRICE element. The difference from the example before the line swapping is that in this example, the PRICE element contains the value of the CENA element in the result.

You need to specify the exact path to the element

 This section does not apply to MERGADO 1, since MERGADO 1 did not work with an XML structure like MERGADO 2.

What if we had a Shoptet complete format on the output, which has image URLs by default in the IMAGE element, and we wanted to copy the values from the OBRAZEK1 element into it? Since we always need to provide the full and exact path to the element - specifically the IMAGE element must be nested under the IMAGES element, which is what the dropdown tells us:

The rule will correctly look like this:

So it is not enough to write the IMAGE element itself.

How the rule works for multi-value elements

 This section does not apply to MERGADO 1, since MERGADO 1 does not handle multi-value elements like MERGADO 2.

In the case of simple elements, there is nothing to deal with. It takes a single value of the source element and copies it to the target element, replacing its single original value.

In the case of multi-value elements, the behaviour is a bit more complicated. All values of the source element are taken and copied to the target element, starting from the first position matching the path of the target element. After copying, the rest of the original values of the target element are deleted.

Let’s describe this in more detail using an example with images. Consider the following data:

and the Bulk copy values rule written as follows:

The rule performs the following 3 steps sequentially:

• Step 1: Take all values of the source element matching the specified path.
   
  

• Step 2: The first value of the target element matching the specified path is found.
   
  

• Step 3: The values from step 1 are copied to the target element. And they are copied starting from the first position selected in step 2. After copying, the rest of the original values of the target element are deleted.
   
  

After re-generation the feed looks like this:

We have to be careful not to accidentally delete some values of the target element.

How to specify the path to the element?
The target element path can also contain refining conditions. For example, if in our example we wanted the copy to start from the second value, we would write the more precise IMGURL_ALTERNATIVE { @@POSITION = 2 } instead of the generic IMGURL_ALTERNATIVE.

Copying the whole structure

 This section does not apply to MERGADO 1, since MERGADO 1 did not work with XML structures like MERGADO 2.

Consider parameters that have names in the PARAM_NAME element, values in the VAL element, and both of these elements are nested in the PARAM element for each parameter.

We want to copy these parameters into the INFORMATION PARAMETER, NAME and VALUE elements. The desired result looks like this.

How to achieve this? We might think that we want to copy the values of the PARAM_NAME element into the NAME element and the values of the VAL element into the VALUE element. So in the rule, just write:

But after re-generating, one finds that the values are copied strangely – all the values are in one parameter.

But that actually matches the behavior described in the previous section How the rule works for multi-value elements:

1. All values of the source element matching the specified path are taken, i.e. all names and parameter values.
    
   
    
   

2. For the target element, the first position of the specified path is found. Which in this case is the first position of the NAME and VALUE elements (and not the first position of the INFORMATION_PARAMETER element, as one might think).
    
   

3. The values from point 1 are copied to the target element from the position selected in point 2, i.e. all values from the PARAM_NAME and VAL elements are copied to the NAME and VALUE elements, but within a single INFORMATION_PARAMETER element.
    
   

So this is not the right way. Therefore, we will help ourselves with rule’s special behavior: the Bulk copy values rule copies values while taking into account the element structure in case the given element structure (parent-child) appears in the form over multiple lines. Thus, in our case, if we want to copy the values of the PARAM_NAME and VAL elements structurally into the NAME and VALUE elements, we just need to write their respective parent elements (or the whole path) - PARAM and INFORMATION_PARAMETERS | INFORMATION_PARAMETER - into the form in the line above them.

and the values are copied as we want them.

→

You can use the XML feed itself or the Elements page as an aid. In both cases, the element structure is shown.

What if we only want to copy some selected parameters, e.g. Size and Color, structurally? This is also possible, just specify the path to the element using conditions. The condition must be specified for all elements (parents and children) that we want to copy structurally. For our example:

→

 Structural copying will only take place if (vertically) adjacent rows contain the same parent element. In all other cases, the rule will behave as described in the previous section How the rule works for multi-value elements.

What else does the Bulk copy values rule form offer?

The rule form offers several features to make our job easier:

1. The button fills the left side with all the elements from the Elements page. This makes it easier if we are going to copy values from multiple elements.

2. The button downloads CSV file with filled fields. It will contain 2 columns and the corresponding number of filled rows.

3. The descriptive text Rows without values will be ignored tells us that rows with empty fields (on the left or right side) will be deleted when the rule is saved. This can be used in combination with the Autofill left side button, where we fill in the entire left side and then fill in the right side for only some of the rows and don’t worry about the rest, because it will be deleted when saved.

4. Button to delete the row.

Comparison with other rules

Why should we use the Bulk copy values rule when in some cases, such as copying the value of one element to one other element, we can just use the Rewrite rule?

The Bulk copy values rule is more efficient for cases where we want to copy values from or to 2 or more elements. After all, we don’t want to have 10 Rewrite rules and unnecessarily slow down the re-generation of our project when we can easily do the same thing in one rule. On the other hand, a Rewrite rule is only useful for copying in one case, and that is when copying a value of only one element to only one other element.

Most common uses

We show a list of examples of the uses of the Bulk copy values rule that we encounter most often to give you a rough idea of what it can be used for.

The format converter did not convert all values in the way we wanted

So we want to finish or modify the value conversion ourselves. This case mostly applies to projects where custom format is selected or a format having non-standard elements for which we have no equivalent in MERGADO XML.

Example 1: We want to copy the values of element code (Shoptet CSV) to element PartNumber (Alza.cz - Dropshipment). This is a typical example. In the rule form, select the code element on the left side and the path to the Product | PartNumber element on the right side.

You’re done! Save the form, re-generate the project and the changes will be reflected in the output.

Example 2: We want to copy the values of the multi-value Category element (custom format) into the CATEGORY and DEFAULT_CATEGORY elements (Shoptet complete). Specifically, we want the first value from the Category element in the DEFAULT_CATEGORY element and all the Category values in the CATEGORY element.

I.e. we have in the input:

and on the output we want to get:

The rule will look like this:

Example 3: We want to copy the PARAM, PARAM_NAME and VAL (Heureka) parameters into INFORMATION_PARAMETERS, INFORMATION_PARAMETER, NAME and VALUE (Shoptet complete).

→

We’ll take advantage of the fact that the rule can copy structurally, and make our job easier. The rule will look like this:

We have selected the Plain CSV format for the output, which we will use as the file in the Data file import rule in another project.

Example 4: This example is the subject of a separate article We want to get Heureka stock availability information into the Heureka product feed (only in Czech).

Example 5: We have a Heureka format on the input and we want to get values from nested elements under DELIVERY, e.g. DELIVERY | DELIVERY_ID, into non-nested elements, e.g. DELIVERY_ID.

The rule will look like this:

Swapping the values of two elements

Example 6: We want to swap values between two elements, e.g. IMGURL and IMGURL_ALTERNATIVE.

To do this, we first need to create a help element (on the Elements page).

Then we just need to create a rule like this:

or as follows:

Both variants of the rule work the same.

 There is also a publicly available macro for swapping values that is easy to use.

Summary

• How does the rule work?
  • The rule takes the values from the selected source element and copies them to the selected target element. This can be done in bulk for multiple elements within a single rule.
  • In case of multi-value elements, it takes all the values of the source element and copies them to the target element by starting from the first position matching the path of the target element. After copying, the rest of the original values of the target element are deleted.
     
• How to copy a structure?
  • If you want to copy an element structurally, put its parent element above it:
    
    
    
    
     
• Most common uses, for example:
  • The format converter did not convert all values in the way we requested.
  • We have selected the Plain CSV format in the output to use as a file in the Import Data File rule in another project.
  • Swapping the values of two elements.