Using the import tool

This manual page describes how to import data using the import tool. Importing data is recommended if you want to add new items, customer data or stock etc. to your plentymarkets system and you already have this data available in digital format. The import tool allows to carry out data imports by creating imports. You can import your data manually or automatically.

1. Assigning user rights for back end users

Users of the type Back end can only access limited areas and menus in the plentymarkets back end. Thus, their access to the system is limited. If users of the type Back end should be able to work with imports and mappings, a user of the type Admin has to assign the rights listed in [table-user-rights-elastic-sync] to users of the type Back end.

Assigning user rights for back end users:

Go to Setup » Settings » User » Rights » User.
Use the search function () and open the user account that should be edited.
In the Authorisations section, activate the rights as listed in Table 1.
Save () the settings.

Table 1. User rights for imports and mappings
Setting	Explanation
Data > Import > Create	Authorises back end users to create imports.
Data > Import > Delete	Authorises back end users to delete imports.
Data > Import > Show	Authorises back end users to see imports.
Data > Import > Update	Authorises the back end user to update imports.
Data > Import > Mapping > Create	Authorises back end users to create mappings.
Data > Import > Mapping > Delete	Authorises back end users to delete mappings.
Data > Import > Mapping > Show	Authorises the back end user to see mappings.
Data > Import > Mapping > Update	Authorises back end users to update mappings.
Data > Data log	Authorises the back end user to create, delete, see or update the data log of an import.

2. Importing data with assistants

You want to import contact or item data and wonder what is the fastest way to do this in your plentymarkets system? In this case, use the corresponding assistants that will allow you to create an import template which you can fill with your data. The assistants will guide you step by step through all necessary settings and you can determine which data you want to import. Afterwards, you can use another assistant to directly upload the filled import template and carry out the import.

2.1. Completing the Contact data import assistant

If you want to import contact data, you can either use the import tool or the Contact data import assistant. This assistant will help you to create an import template tailored to your needs. Afterwards, you can download it and fill in your data.

You can find the Contact data import assistant in the menu under Setup » Assistants » Basic setup. With this assistant, you carry out the following settings:

You select the name for the import that should be displayed in the system later on.
You select which contact data, address data and company data you want to import.
You select which contacts and contact options you want to import.
You select which addresses you want to import.
You can download the import template as CSV file. Note that you must not change the first 3 lines.

If you now want to carry out the import, you can use the [Upload data assistant]. Alternatively, you can go to the Data » Import menu and upload the import file in the respective import.

2.2. Completing the Item import assistant

If you want to import item data, you can either use the import tool or the Item import assistant. This assistant will help you to create an import template tailored to your needs. Afterwards, you can download it and fill in your data.

You can find the Item import assistant in the menu under Setup » Assistants » Basic setup. With this assistant, you carry out the following settings:

You select the name for the import that should be displayed in the system later on.
You select which item data you want to import.
You select which sales prices you want to import and determine the formatting.
You can download the import template as CSV file. Note that you must not change the first 3 lines.

If you now want to carry out the import, you can use the [Upload data assistant]. Alternatively, you can go to the Data » Import menu and upload the import file in the respective import.

2.3. Completing the Upload data assistant

You can use the Upload data assistant to upload an import template containing your data and to directly carry out the import.

You can find the Upload data assistant in the menu under Setup » Assistants » Basic setup. With this assistant, you carry out the following settings:

You upload the import template containing your data.
Note: If you do not have an import template yet, use the respective import assistant to create one.
You carry out the import. Here you can determine whether you want to directly carry out the import by finalising the assistant. Alternatively, you can start the import in the Data » Import menu.

Afterwards, you can see the import that you created with the assistant in the overview of the Data » Import menu. A matching does not exist here, as these are new data. In the Mapping tab of the import, all fields of your CSV file have already been mapped automatically to the plentymarkets data fields.

3. Creating an import

The steps for creating and carrying out imports are identical for all import types. As such, the steps described in the following apply to all import types.

Go to Data » Import to create, edit and manage imports. Here, you can see an overview of all imports. With an import, you can assign the data of a file that is accessible via FTP or HTTPS to the data in plentymarkets and import them. When creating an import, you save information about the data source. Furthermore, it is important that you determine data for the matching and that you assign which data of your file corresponds to the data in plentymarkets. Use the matching to set what data is to be used to try to identify, if a data record already exists or not. Use the mapping to set which column in your file corresponds to which data field in plentymarkets. In the end, set an import interval. Proceed as described below to create an import.

Set the import interval in the end to avoid that an import is carried out too early

It is recommended to set the import interval in the end. By doing so, you avoid that an import is already carried out while you still carry out matching and mapping settings.

Creating an import:

Go to Data » Import.
→ The import overview opens.
Click on Add import ().
→ The editing area New import is displayed.
Carry out the settings. Pay attention to the explanations given in Table 2.
Save () the settings.
→ The import is created.
→ The matching settings of the import open.

Table 2. Creating an import
Setting	Explanation
Basic data
Name	Enter a name. This name is displayed in the overview and can be used for the search.
Interval	Select an interval for carrying out imports. By choosing the option Schedule you can determine how often and at what time the imports shall be started.
Type	Select the type from the drop-down list. Item = Select to import item and variation data. Attribute = Select to import attribute data. Orders = Select to import order data. Properties = Select to import properties. Facets = Select to import facets. Parts compatibility listing = Select to import parts compatibility listing data. Coupon codes = Select to import coupon codes. Manufacturer = Select to import manufacturer data. Campaigns = Select to import coupon campaigns. Categories = Select to import category data. Contacts, companies and addresses = Select to import contact, company and address data. Warehouse = Select to import storage locations. Characteristic = Select to import characteristic data. Newsletter recipient = Select to import newsletter data. Notes = Select to import notes. Stock = Select to import stock data. Incoming items = Select to import incoming item data.
Import
Data type	Select the file format of the import file. Currently, CSV/TXT is the only available option, as only CSV or TXT files can be imported.
Character set	Select the character set of the file or the option Detect automatically.
Starting in line	Select a line starting from which the data should be imported.
Header is included	Select whether the import file contains a header.
Use global cache	Determine whether the global cache should be used for a file or not. If the setting is activated, only modified data rows will be imported. If the setting is not activated, you can import one and the same file again at any time.
Automatic mapping	Select whether the mapping should be done automatically. The columns in the CSV or TXT file can be mapped automatically to the plentymarkets data fields. To ensure that the mapping works properly, the names of the fields that you selected in the FormatDesigner must not be changed.
Separator
Separator	The separator of the CSV or TXT file is automatically detected. This setting is activated by default. Alternatively, you can manually select the field separator that is set in the import file in order to separate the data fields (columns) of a data record from each other. Possible separators are Semicolon, Comma, Tab and Pipe.
Delimiter	Select delimiters within the fields that may contain multiple values. * " = individual values within one field are separated by double quotation marks. * ' = individual values within one field are separated by single quotation marks.
Source
Source	Select Manual upload, FTP, HTTPS or SFTP. Depending on the selected option, the following settings are displayed: Manual upload = Select and upload a local file. After running an import, the file is automatically deleted from the webspace. This is preset by default. In order to save the file you need to remove the check mark. *Note: storing the file on the webspace is subject to a fee. FTP* = Host, port, user name, password and file name are displayed. Host (mandatory field) = Enter the host of the FTP server. *Tip:* Use your plentymarkets FTP access. Port = Enter the port of the FTP server. If no port is entered, the standard port (22) is used. User name (mandatory field) = Enter the user name for the FTP access. Password (mandatory field) = Enter the password for the FTP access. File name = Enter the path and the name of the file from which the data is to be imported. The file name has to end with .csv or .txt. *Note:* You can use wildcard characters in the field File name by e.g. replacing a part of the file name with a . Only use wildcard characters in combination with the option Move file to archive when import was successful. Move file to archive when import was successful* = If this option is activated, the import file is automatically moved to the new Archive folder in the FTP directory once the import was successful. HTTPS = Select External URL. External URL = Enter the URL to access the import file. *Tip:* Save the file on your plentymarkets webspace. Authentication: Select whether an authentication is required to access the file. none = no authentication required HTTP authentication = an authentication is required for each user and password SFTP = Host, port, user name, password and file name are displayed. Host (mandatory field) = Enter the host of the FTP server. Port (mandatory field) = Enter the port of the FTP server. If no port is entered, the standard port (22) is used. User name (mandatory field) = Enter the user name for the FTP access. Password (mandatory field) = Enter the password for the FTP access. File name = Enter the path and the name of the file from which the data is to be imported. The file name has to end with .csv or .txt. *Note:* You can use wildcard characters in the field File name by e.g. replacing a part of the file name with a . Only use wildcard characters in combination with the option Move file to archive when import was successful. Move file to archive when import was successful* = If this option is activated, the import file is automatically moved to the new Archive folder in the FTP directory once the import was successful.

4. Setting the import options

The import options can be found in the Matching area. They apply both for the matching and for the mapping.

Before we get to the specific settings of the import options you now have the opportunity to learn more about the data import by watching the following videos. As already mentioned, data can be imported manually or automatically. If you are new to plentymarkets and you want to manually import your data one time, watch this video and learn how to initially transfer product or customer data into your system.

Manually import you data one time

This video shows you how to instruct plentymarkets to automatically import new files and archive old ones.

Automatically import new files and archive old ones

Back to the import options.

Setting the import options:

Go to Data » Import.
→ The import overview opens.
Click on the import in the import overview.
→ The settings open.
Switch to the Matching tab.
Determine the import options. Pay attention to the explanations given in Table 3.
Save () the settings.

Table 3. Import options for imports
Import option	Explanation
Select an import option	Import new data, update existing = If data can be found by means of the matching fields, a new data record, e.g. a new item or a new order, is added. At the same time, existing data is updated. Only update existing data = Existing data is updated. If no data can be found by means of the matching fields, the data record is not imported. Only import new data = Only new data records are imported, i.e. any data for which no matching data is found based on the synchronisation fields.
Decimal number	Select German spelling or English spelling. German spelling = Decimal numbers are separated by a comma and a full stop serves as thousands separator. English spelling = Decimal numbers are separated by a full stop and a comma serves as thousands separator.
Date format	Enter the date format. If the date in the file corresponds to the standard format Y-m-d H:i:s, it is not necessary to enter another format. Other formats, however, have to be entered here. All php-compliant date formats are allowed.

5. Setting the matching

After creating an import, open it to carry out further settings. First, select the fields that should be used for matching the data. Determine what should happen if no existing data can be found during the matching process.

Matching is optional

Matching fields are optional settings. If you do not select a matching field, the data in your file cannot be assigned to existing data in your system. You can determine one, multiple or all matching fields. The displayed matching fields are different for each import type.

Setting the matching:

Go to Data » Import.
→ The import overview opens.
Click on the import in the import overview.
→ The settings open.
Switch to the Matching tab.
Carry out the settings.
Save () the settings.

6. Creating a mapping

With a mapping, you specify which column of your file corresponds to which data field in your system. Without this mapping, no data can be imported. You can create new mappings in the mapping tab. A position is automatically assigned to each new mapping and can be adjusted in the settings tab if necessary.

Creating a mapping:

Go to Data » Import.
→ The import overview opens.
Click on an import.
→ The settings open.
Switch to the Mapping tab.
Click on Add mapping ().
→ A new window opens.
Enter a name for the mapping.
Save () the settings.
→ The mapping opens. → The available mapping fields differ according to the import type.
Select the data fields for the mapping by placing a checkmark in the fields.
→ The selected data fields are added to the mapping.
Select a column from your file for each data field or select the option Own value.
Save () the settings.

You want to import a file into plentymarkets, but it’s missing a few key pieces of information? No need to modify the file by hand! This video shows you how to use the import tool’s "Own Value" function to add missing information to your import.

Use the Own value to add missing information to your file

Own value

The option Own value allows to import a fix value for the data field. This fixed value is thus identical for each data record that is imported via this import.

Mathematical calculations

In the mapping overview, select the option Mathematical calculations in order to adjust values in a CSV or TXT file during the import. The options addition (+), subtraction (-), multiplication (*), division (/) and the adaptation of percentages (+)/(-) are available. The value that is being adapted in the CSV or TXT column has to be a number.

6.1. Activating lines of a mapping for the import

In the Mapping section, you can activate (and also deactivate) all selected lines for the import with just one click. Alternatively, you can decide individually for each line whether you want it to be active or inactive, thus, whether it should be considered in the import or not.

Activating lines for the import:

Go to Data » Import.
→ The import overview opens.
Click on an import.
→ The settings open.
Switch to the Mapping tab.
Click on a mapping.
→ The mapping opens.
On the left, select all lines you want to consider in the import.
At the top, click on Activate all (). By clicking on Deactivate all (), you can deactivate all selected lines again.
Alternatively, click on Activate row () on the right to activate lines for the import individually.
Save () the settings.

View of the mapping

On the left side of the mapping you can see the import data of the CSV or TXT file that have to be mapped on the plentymarkets page. The plentymarkets data fields are shown on the right. The preview () displays the first 6 values of the file.

Editing position and name

By clicking on Settings () in the mapping, the fields Name and Position become visible and can be edited.

6.2. Activating/deactivating mappings

If you manage several mappings in the same import, you can deactivate or activate specific mappings of the import in the mapping overview by clicking on the toggle button in the column Active/Inactive. New mappings are active by default.

6.3. Replacing values with the RegEx function

In order to consider a CSV or TXT file during the import as desired, the so-called RegEx function (Regular Expression) can be applied. Thanks to this function, data is manipulated during the import by using commands, so that the CSV or TXT file does not need to be changed anymore. Watch this video to learn more about the RegEx function.

Modify your data with the RegEx function

The following two examples will give an overview of the process.

Example 1:
Input: “24.12.2017”
Search pattern: /^(\\d+).(\\d+).(\\d+)$/
Replace pattern: $3﹣$2﹣$1
Result: “2017-12-24”

Example 2:
Input: “Doe, John”
Search pattern: /^(\\w+), (\\w+)$/ +), (\\w)$/
Replace pattern: $2 $1 +
Result: “John Doe”

Explanation of the examples:
Right at the beginning, there is the input. In a first step, the pattern to be searched for is inserted as search pattern. Afterwards, it is changed accordingly in the replace pattern, so that it is output during the import as required. Finally, the result is output as desired and will be considered in the CSV or TXT file.

Replacing values:

Go to Data » Import.
→ The import overview opens.
Click on an import.
→ The settings open.
Switch to the Mapping tab.
Click on a mapping.
→ The mapping opens.
In the field Source, select the value Regular expression.
→ The options for Regular expression open.
In the field Value, enter the column name of the CSV or TXT file (e.g. Package number, Order ID etc.).
In the field Search, enter the Search pattern.
In the field Replace, enter the Replace pattern.
Save () the settings.
→ The data fields are updated.

Info about RegEx

For further information on RegEx see this page or have a look here . On the latter page, the RegEx engine setting has to be changed to PCRE. This can be done in the drop-down menu on the top right where Javascript is preset.

6.4. Own assignment

With the own assignment you can assign existing values of a CSV or TXT file to other values in the system. This enables to define, which value is supposed to be imported for which ID. In addition, for values in the CSV or TXT file that are not assigned, you can specify a default value. If no default value is specified, the original value is imported.

Defining an own assignment:

Go to Data » Import.
→ The import overview opens.
Click on an import.
→ The settings open.
Switch to the Mapping tab.
Click on a mapping.
→ The mapping opens.
In the drop-down menu of the Source field, select the option Own assignment.
Fill in the fields. Pay attention to the explanations given in Table 4.
Save () the settings.

Table 4. Own assignment
Field	Setting
Type	Name of the CSV or TXT column (e.g. Delivery country)
Default value	Value, in case no assignment was found (e.g. 1)
From	Original value in the CSV or TXT file (e.g. DE for Germany)
To	Value, to which the original value shall be mapped (e.g. 1 for DE, 10 for GB etc.)

6.5. Manipulating an import file via the own assignment

In the following section we will demonstrate the usage of the own assignment shown by the example of Activating a shipping profile.
To do so, an item/a variation as well as a shipping profile has to exist. The following video gives you an introduction on how the Own assignment works.

Use the Own assignment to trade one piece of information for another

Figure 1. Shipping profile

In order to link an item/a variation to a shipping profile, the ID is required. Just the name of the shipping profile shown in the import file is not sufficient to create a link.

Figure 2. Item ID

Use the own assignment in the import tool, which manipulates the data during the import. As source for the import data, select the value Own assignment.

Figure 3. Own assignment

For type, select the column from the import file. In this case, it is the column Shipping profile.

Figure 4. Select the file format of the import file

Determine which value in the import file shall be changed to which value in order to successfully carry out the import. In this case, DPD shall be changed to the ID of the shipping profile (here ID 7). You can also do this for several shipping profiles by adding further own assignments. Afterwards, carry out the import. The shipping profile is linked.

Figure 5. Determining a value

The own assignment can be used for many other cases. This applies in particular where internal IDs of plentymarkets play a role (e.g. characteristic names, item flags, payment methods, country ISO codes etc.).

7. Filtering import data

You can use filters to limit the imported data. You find the filters in the Mapping area.

Multiple filters are linked with an AND condition

If you use multiple filters, only those data records that apply to all filters are imported. Thus, the filters are linked with an AND condition.

Adding a filter:

Go to Data » Import.
→ The import overview opens.
Click on the import in the import overview.
→ The settings open.
Switch to the Mapping tab.
Click on a mapping.
→ The mapping opens.
Click on Filter () in the toolbar.
Select the column from your file that you want to filter.
Select an operator.
Enter a value.
Click on Add filter ().
→ The filter is saved.
Add additional filters as necessary.
→ Only data that meets all filter criteria is imported.

8. Error messages and troubleshooting in the import tool

The import tool offers you various possibilities to identify incorrect imports beforehand and to perform troubleshooting. Thus, you can for example check imports for errors before running them or you can view a log of concrete error messages once the import has been carried out. The different possibilities are listed below.

8.1. Checking imports for errors before the run

With the validation, imports can already be checked for errors before the run to guarantee as smooth import.

Checking imports for errors before the run:

Go to Data » Import.
→ The import overview opens.
Click on an import.
→ The settings open.
In the settings, matching or mapping tab, click on Validation ().
→ A window opens and shows a table with the respective error messages.
In case an error occurred and you need help in the forum, click on Copy to clipboard () and paste the information in the forum.

8.2. Testing the import and importing sample data

In the import overview you can test () and run () imports. Testing allows you to quickly know whether your file can be imported correctly.

Testing the import

Note that stock is already being imported when testing an import. If you select Test import (), only the first 10 lines of the import file are imported.

8.3. Viewing the log of a completed import

A log listing errors that may have occurred is automatically created for each completed import.

Viewing the log of a completed import:

Go to Data » Status.
→ The status overview opens.
Or: Go to Data » Import.
→ The import overview opens.
Click on Status ().
→ The status overview opens.
Click on a completed import.
→ The detail view opens.
At the top, click on Log ().
→ A window opens and shows the log of the completed import.
In case an error occurred and you need help in the forum, click on Copy to clipboard () and paste the information in the forum.

8.4. Viewing success and error messages of imports

In the Data » Log menu you can see success and error messages of imports. To find messages of specific imports, select the reference type importId or importName and enter the respective reference value. The specific success or error messages can be found in the Message column.

9. Copying imports

You can copy one import or multiple imports at the same time. That way, you can use imports that you have already configured in order to quickly create a new import.

Copying imports:

Go to Data » Import.
→ The import overview opens.
Select one or multiple imports.
Click on Copy import.
→ The import is copied. (copy) is added behind a copied import.

10. Carrying out imports and exports

You can import and export imports. Furthermore, you can save imports locally and import them from other users. This video shows how to use preconfigured imports in order to safe time when importing data.

Carrying out imports and exports

Carrying out imports and exports:

Go to Data » Import.
→ The overview opens.
Select one or multiple imports.
Click on Export format ().
→ The import is automatically downloaded.
Click on Import format ().
→ The file overview opens.
Click on Upload file () and select a file.
Select the file that you would like to upload and click on Select.
→ A message appears checking whether you want to carry out the import.
Click Ok in order to confirm.
→ A message appears explaining that the import originates from another client.
→ The import has been imported successfully.

Carrying out imports from another plentymarkets system

If you would like to carry out imports from another plentymarkets system, you have to adjust the matching and mapping settings. It is only possible to import .json files.

Importing and updating imports

If you want to import and update an import, a mapping and a matching are required. Otherwise, it is not possible to test or run an import. In order to save the import, a data field has to be activated in the mapping overview.
If you just want to do an import, a mapping alone is sufficient.

11. Cancelling an import

Under Data » Status you can cancel an import that has already been started. Thus, this function is only available if the import is currently being processed.

Cancelling an import during the import:

Go to Data » Status.
→ The status overview opens.
Or: Go to Data » Import.
→ The import overview opens.
Click on Status ().
→ The status overview opens.
At the very right in the line of the import that you want to cancel, click on Cancel import ().
→ A window opens and you need to confirm your decision.
Click on Cancel import.
→ The import is cancelled and only those rows that had already been imported when cancelling are in the system.

12. Uploading files quickly and easily

In order to quickly and easily upload files, click on File upload () in the File name column.

Uploading files quickly and easily:

Go to Data » Import.
→ The import overview opens.
In the File name column, click on Upload file ().
→ Your files open.
Select a file and click on Open.
→ The file is uploaded and the file name is displayed in the column. After running the import, the file name disappears.

13. Processing jobs in the queue

The queue enables the import of large amounts of data. Before being imported, the import file is broken down into packages and processed in so-called jobs. A job consists of 750 lines of a CSV or TXT file. However, import files with less than 750 lines also make a job. Whenever an import is started, the file is split up into the respective jobs and is put into the queue. In the queue, new jobs are permanently retrieved and the imports are processed. There are two different statuses. The status Open jobs means that there are jobs in the queue waiting to be processed. Completed jobs on the contrary have already been processed and the data have been imported.

14. Viewing the status of imports

The status overview of the imports shows the current progress of import jobs and displays details of errors that may have occurred during the import process.

Viewing the status of imports:

Go to Data » Status.
→ The status overview opens.
Or: Go to Data » Import.
→ The import overview opens.
Click on Status ().
→ The status overview opens.

In each import line, there is also a separate status button you can use to open the status of this specific import.

Table 5. Import status
Setting	Explanation
Run ID	Each time an imports is started, a Run ID is created in order to better distinguish between the different imports.
Import ID	ID of the import
Name	Name of the import
Progress	Progress of the import jobs. As soon as all jobs have been completed, the date and end time are displayed.
Error	Errors that have been occurred in the import jobs
Imported rows	Number of lines that have been imported from the CSV or TXT files
Total rows	Total number of lines in the CSV or TXT file
Start time	Start time of the import

Cancellation when too many errors have occurred

In case too many errors occur during the processing of import jobs, the process is cancelled and an error message appears.

14.1. Filtering for imports

By using the filter in the status overview, you can filter for imports of the last 7 days and thus check the status of specific imports.

Table 6. Filter options
Setting	Explanation
Import ID	ID of the import
Name	Name of the import
Status	Current status of the import. Select between In progress or Completed.
Start date from	Select the date as of which you want to filter.
Start time from	Select the time as of which you want to filter. The start time refers to the start of the import.
Start date to	Select the date up to which you want to filter.
Start time to	Select the time up to which you want to filter. The start time refers to the start of the import.

14.2. Detail view of import errors

In the status overview, you can click on an import to access the detail view where you will find further information on errors that may have been occurred. By clicking on a line of an error in the detail view, a new window opens and displays the name of the table header, the raw data as well es the concrete error message.

Table 7. Details of import statuses
Setting	Explanation
Errors
Line	Line where the error occurred
Column name	Name of the column where the error occurred
Error	Concrete description of the occurred error
Outcome
Raw data	Raw data of the error

15. Restoring backups of imports

If you want to reset import data to a previous state or restore deleted import data, you can do so by using the backup function.

Restoring backups of imports:

Go to Setup » Settings » Hosting » Backup.
→ The backup overview opens.
In the line of the backup that you want to import, click on Restore backup () on the right.
At the top, select Partially import data base and tick the box Import.
Click on Restore backup.
→ The backup is restored.