Skip to main content

Best Practices: ElasticSync

Plugin update?

Before creating syncs or export formats, go to Plugins » Plugin overview » Open plugin set and make sure that you use the latest version of ElasticSync.

This page contains best practices for the plugin ElasticSync.

Before you start using the best practices described on this page of the manual, you should familiarise yourself with the general functionality of ElasticSync. To do so, read the Importing data with ElasticSync page of the manual before you start on this best practice.

1. Best Practice: Creating variations with ElasticSync

This best practice teaches you how to create items using ElasticSync.

To benefit from this best practice, you should be familiar the basic functionality of ElasticSync. Check the Importing data with ElasticSync page of the manual for general information about how the plugin works.

1.1. Requirements

To import items and variations using ElasticSync as described here, the following data must be saved in the system:

  • Attributes

  • Attribute values

  • Categories

  • Sales prices

1.2. Info

Go to System » Settings » ElasticSync to find the button Delete cache.

This button allows you to reset the ElasticSync cache once per hour in order to reimport a file that does not contain any changes.

Also helpful is the Test run button.

testrun
Figure 1. Useful for testing syncs

This imports the first 10 rows of a file without cache. This allows you to check if all values have been assigned correctly before you start syncing all rows.

Check the plugin description and the manual to find out which values are valid for these fields.

Go to Data » Log to access the error messages related to the sync.

1.3. Structure of the file

The following sample file has been used for the sync.

1.3.1. General

The data that is saved globally at the item level, e.g. the name, the description, etc. is saved to the row of the main variation. During the sync, this should be saved in a separate mapping.

Data that is variation based must be entered into the relevant rows of the variations.

When creating the variations, it is important that the structure of the attributes and values are saved in the file matches that of the mapping.

1.3.2. Variation numbers

In this example, we will create a main variation with 4 variations. For mapping the variations, we use the main variation number.

Because the sync imports data row by row, the main variation is at the top of the file.

There, we manually save the variation number in the field of the same name. The field Main variation number remains empty.

This variation number is now written into the field Main variation number of the variations in order to map them to the main variation. Otherwise, the variations would be imported as separate main variations.

You can also enter the variation numbers of the child variations. If you leave the field empty, the system generates the numbers automatically.

The file will look like this:

hvnumber
Figure 2. Entering the numbers for main variation and variations
Variation numbers must be unique!

Both the number of the main variation and those of the child variations must be unique. The import fails if numbers are assigned more than once.

1.3.3. Attributes

In our example, we selected attribute selection combination:

attributes
Figure 3. Creating variations using the attribute selection combination

The first row of the main variation has not been assigned a combination so it is not linked to any attributes.

Main variation without attributes

If you work with variation items, we recommend that you do not assign any attributes to the main variation. This provides you with more flexibility when you create variations. If you assign an attribute to the main variation, you can only create variations with the same attributes.

1.3.4. Images

In our sync, we will import the image URLs using 2 separate columns and mappings. You can also do this in one row by comma-separating the URLs. For that, the field Multi URL must be selected in the mapping. The format of the URL is saved as follows: image1url;positionImage1,image2url;positionImage2

To link more than one category, you need to create several mappings. Also, make sure to specify the full path for the category links. The levels are separated by a semicolon.

categorylink
Figure 4. Correct spelling of separators and paths are essential for the import.
Mapping and file

Make sure that the values in the file match the mapping. This is because you can select different values in the mapping. For example, for the field Default category, you can select either the ID or the name. As such, the CSV file must contain either the ID or the name. You cannot use the ID in the mapping but the name in the file.

1.4. Synchronisation

For the synchronisation, it is important that a variation-specific synchronisation field is used. A good choice is the variation number or the variation ID.

Select the option to create a new data record if no synchronisation is possible.

1.5. Mapping

In the mapping, we map the fields in the CSV file with the fields in plentymarkets.

set values
Figure 5. Create a mapping

We recommend that you only map those fields that you actually want to import. Unnecessary fields can result in errors and should best be avoided.

There are some mandatory fields for creating items with variations. These fields must be mapped for the sync to work. Those mandatory fields are:

  • Default category

  • Main variation number

  • Variation number

  • If you want to import stock, the following values must be part of the mapping: Warehouse, Quantity, Storage location

1.6. Second mapping

The mappings are processed one after other. That means that the second mapping runs after the first one.

Using an additional mapping, we now want to import a second category, an additional image and the global item data (e.g. name, description, etc.).

In the mapping itself, we again specify the values and map the URL and the name of the category to the second column of our file.

second mapping new
Figure 6. Additional mappings are created in the same way as the first one.

The sync is now ready to go and you can start it.

Test run

We recommend that you do a test run before the first sync. This allows you to check if the sync functions as expected. If the sync does not perform as expected, you can now correct it before it is run for real.

This chapter describes how to export and import client links.

To benefit from this best practice, you should be familiar the basic functionality of ElasticSync. Check the Importing data with ElasticSync page of the manual for general information about how the plugin works.

2.1.1. Creating the format in the FormatDesigner

The clients currently linked to variations, i.e. active clients, can be exported using the FormatDesigner. To do so, go to Data » FormatDesigner and create a new format of the type Item.

After that, select the data fields:

  • To allow mapping during import, from the Variation area select the ID or the Number of the variation.

  • The actual client availability is then added in the VariationClient area. The field is called isActive.

Mapping for multiple clients

If you work with more than one client, the field isActive must be added more than once. Each field must be assigned to a specific client.

In the export, the field contains the value 1 if the client is active. If the client is not active, an empty field is exported.

After you have saved the format, you can set up the export in the elastic export.

2.1.2. Setting up the export in the elastic export

Go to Data » Elastic export to set up the export of the format you created.

To do so, click on New export and save a name, the type Item, the format you created, a limit and a file name.

Exporting the file in CSV format

If you want to download the file in CSV format, specify the suffix .csv as part of the file name.

Once you save the format, you are done setting it up.

2.1.3. Exporting data

There are several ways of exporting the data:

  • In the export, click Download.

  • Open the URL in a browser.

  • In the export overview, click Download.

2.2. Importing the client availability

2.2.1. Creating the sync in ElasticSync

To import the client availability, you can go to Data » ElasticSync and create a sync of the type Item. Alternatively, you can add the fields to an existing sync.

The synchronisation must be based on a variation-specific field, for example the Variation number.

In the sync’s mapping, select the field Active in the Client (store) area. Then click on the green plus icon to add the clients. To map the column of the CSV file, click on the pencil icon.

You need to specify the value 1 to activate. To deactivate, specify a 0.

Working with your own values

Instead of using one column in the file, you can also use your own value and enter yes or no for all rows of the file in the mapping.

That is all you need for the link. The sync is now ready to go and you can start activating or deactivating clients.

This chapter describes how to export and import property links.

To benefit from this best practice, you should be familiar the basic functionality of ElasticSync. Check the Importing data with ElasticSync page of the manual for general information about how the plugin works.

3.1.1. Creating the format in the FormatDesigner

The properties currently linked to variations can be exported using the FormatDesigner. To do so, go to Data » FormatDesigner and create a new format of the type Item.

After that, select the data fields:

  • To allow mapping during import, from the Item area select the ID of the item or from the Variation area select the ID or the Number of the variation.

  • You then add the actual property links in the VariationProperty area:

You can select between 3 values:

  • value: Returns the value of the property mapped in the format.

  • all: Returns all linked properties of an item with values.

  • allIds: Returns all linked property IDs of an item without any values.

After you have saved the format, you can set up the export in the elastic export.

3.1.2. Setting up the export in the elastic export

Go to Data » Elastic export to set up the export of the format you created.

To do so, click on New export and save a name, the type Item, the format you created, a limit and a file name.

Exporting the file in CSV format

If you want to download the file in CSV format, specify the suffix .csv as part of the file name.

Once you save the format, you are done setting it up.

3.1.3. Exporting data

There are several ways of exporting the data:

  • In the export, click Download.

  • Open the URL in a browser.

  • In the export overview, click Download.

3.2.1. Creating the sync in ElasticSync

To import the property links, you can go to Data » ElasticSync and create a sync of the type Item. Alternatively, you can add the fields to an existing sync.

The synchronisation can be based on a variation-specific field, for example the Variation number, or based on the item ID if the links are created using a separate sync.

In the mapping of the sync, you can select different fields to create or edit the links. For example, you can add the fields ID, Value and Language (you need to add all 3 fields) or instead the field Property combination. The latter must be structured as follows in the file:

InternalName1:Value1:Language;InternalName2:Value2:Language

If you want to delete property links, use the field Delete (Yes/No). In the file, the value 1 must be specified if the links are to be deleted. Specify the value 0 if you do not want to delete the link.

That is all you need for the link. The sync is now ready to go and you can start linking properties.

This chapter describes how to export and import cross-selling links.

To benefit from this best practice, you should be familiar the basic functionality of ElasticSync. Check the Importing data with ElasticSync page of the manual for general information about how the plugin works.

4.1. Exporting cross-selling links

4.1.1. Creating the format in the FormatDesigner

The currently linked cross-selling items can be exported using the FormatDesigner.

To do so, go to Data » FormatDesigner and create a new format of the type Item.

After that, select the data fields:

  • To allow mapping during import, from the Item area select the ID of the item or from the Variation area select the ID or the Number of the variation.

  • The actual cross-selling links are added in the ItemCrossSelling area. The field all returns all linked cross-selling items in the format ItemID:Type:IsDynamic.

After you have saved the format, you can set up the export in the elastic export.

4.1.2. Setting up the export in the elastic export

Go to Data » Elastic export to set up the export of the format you created.

To do so, click on New export and save a name, the type Item, the format you created, a limit and a file name.

Exporting the file in CSV format

If you want to download the file in CSV format, specify the suffix .csv as part of the file name.

Once you save the format, you are done setting it up.

4.1.3. Exporting data

There are several ways of exporting the data:

  • In the export, click Download.

  • Open the URL in a browser.

  • In the export overview, click Download.

4.2. Importing cross-selling links

4.2.1. Creating the format in ElasticSync

To import the cross-selling links, you can go to Data » ElasticSync and create a sync of the type Item. Alternatively, you can add the fields to an existing sync.

  • The synchronisation can be based on a variation-specific field, for example the Variation number, or based on the item ID if the links are imported using a separate sync.

  • In the sync’s mapping, in the Cross-selling are, link the field Add cross-selling links and assign the corresponding column in the CSV file.

  • You can save more than one cross-selling link per row. The structure will be as follows:

ItemID:Type;ItemID2:Type2

  • Use the field Delete all cross-selling links to delete all links of an item. Specify 1 for yes, 0 for no. This is a good idea if, for example, you want to update your cross-selling items.

  • Using the field Delete cross-selling links, you can delete one or more item IDs. The format should look like this:

itemID;itemID;etc

That is all you need for the link. The sync is now ready to go and you can start linking or unlinking cross-selling items.

5. Best Practice: Exporting and importing ASIN and ePID

This chapter describes how to export and import ASIN and ePID data.

To benefit from this best practice, you should be familiar the basic functionality of ElasticSync. Check the Importing data with ElasticSync page of the manual for general information about how the plugin works.

5.1. Exporting ASIN and ePID

5.1.1. Creating the format in the FormatDesigner

The ASINs and ePIDs currently linked to variations can be exported using the FormatDesigner. To do so, go to Data » FormatDesigner and create a new format of the type Item.

After that, select the data fields:

  • To allow mapping during import, from the Variation area select the ID or the Number of the variation.

  • The actual links are added in the VariationMarketIdentNumber area.

You can select 3 values:

  • countryID: Returns the ID of the country.

  • type: Returns the type, i.e. ASIN or ePID.

  • value: Returns the value that was saved for the ASIN or ePID.

The type has to be mapped for all 3 fields. As such, if you want to export all ASINs and ePIDs, every field must be added to the format twice.

After you have saved the format, you can set up the export in the elastic export.

5.1.2. Setting up the export in the elastic export

Go to Data » Elastic export to set up the export of the format you created.

To do so, click on New export and save a name, the type Item, the format you created, a limit and a file name.

Exporting the file in CSV format

If you want to download the file in CSV format, specify the suffix .csv as part of the file name.

Once you save the format, you are done setting it up.

5.1.3. Exporting data

There are several ways of exporting the data:

  • In the export, click Download.

  • Open the URL in a browser.

  • In the export overview, click Download.

5.2. Importing ASIN and ePID

5.2.1. Creating the sync in ElasticSync

To import and edit the ASINs and ePIDs, you can go to Data » ElasticSync and create a sync of the type Item. Alternatively, you can add the fields to an existing sync.

  • The synchronisation must be based on a variation-specific field, for example the Variation number.

  • To map the sync, in the ASIN/ePID area the fields Country, Type and Value must be saved and linked to the columns in the CSV file.

  • You need to save the ID of the country and the type must be either ASIN or ePID.

That is all you need for the link. The sync is now ready to go and you can start linking properties.

6. Best Practice: Importing package numbers from fulfilment service providers

This chapter describes how you can use ElasticSync to import package numbers for orders that are processed by your fulfilment service providers into your plentymarkets system.

It makes sense to use a CSV file containing the order ID as well as the respective package number as a source file. Your fulfilment service provider usually provides you with such a file.

6.1. Creating the sync in ElasticSync

To import the package numbers, go to Data » ElasticSync and create a new sync of the type Order.

Creating a new sync

To ensure effective cooperation with your fulfilment service provider, we recommend that you create a separate sync for importing package numbers and only use this sync for this purpose. If the fields described below are added to an existing sync, wrong matching and malfunctions are likely to occur.

  • It is mandatory that the matching is carried out via the Order ID. It is not necessary to add further matching fields.

  • Add a new Mapping for the package number. Select the mapping field Package number as well as the option Standard package.

  • Use the Edit function within the Standard package mapping to select the name of the column whose values should be imported from the source file.

  • Save the settings.

After carrying out and saving the settings, go to Sync » Mapping and test the sync. Once the package number has been successfully imported, it is displayed in the Settings tab of the respective order.

To top