Using the import tool
This manual page describes how to import data using the import tool. Importing data is recommended in may situations. For example, it is useful if you want to add new items, customer data or stock etc. to your PlentyONE system and this data is available in a digital format. You can import data manually or automate the process.
You don’t know the Import tool yet? Then get to know the tool first.
1. Creating an import
Create an import.
Creating an import:
-
Go to Data » Import.
→ The import overview opens. -
Click on Add import (add).
→ The editing area New import opens. -
Carry out the settings. Pay attention to the explanations given in Table 1.
Important: Wait until the very end before you set the import interval. Otherwise, the first import might start while you are still working on the settings for the import matching or mapping. -
Save (save) the settings.
→ The import is created.
→ The matching settings of the import open.
Setting | Explanation | ||||||||
---|---|---|---|---|---|---|---|---|---|
Basic data |
|||||||||
Name |
Enter a name for the import. This name is displayed in the overview and can be used for the search. |
||||||||
Type |
Which type of data do you want to import?
Something missing? Find a list of the available import types here. |
||||||||
Interval |
In what intervals do you want to import the data? Important: Only set an import interval when you have finished all import settings. Otherwise, the first import might start while you are still working on the settings for the import matching or mapping.
|
||||||||
Schedule |
Click into the field. From the drop-down list shown, select one or more points in time. The import starts at these times. |
||||||||
Import |
|||||||||
Data type |
At the moment, you can only import CSV or TXT files. As such, select the option CSV/TXT. |
||||||||
Character set |
Select the character set of the file or the option Detect automatically. |
||||||||
Starting in line |
Select a line of the file 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 the file or not. check_box_outline_blank = During each import process, all data rows are reimported. |
||||||||
Automatic mapping |
Select whether the mapping should be done automatically. The columns in the CSV or TXT file can be mapped automatically to the PlentyONE 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 option Automatically detect is selected as default. |
||||||||
Delimiter |
What delimiter is used in the file in cases where the same field/the same column contains more than one value?
|
||||||||
Source |
|||||||||
Source |
Select Manual upload, FTP, HTTPS or SFTP.
|
2. Setting the import options
The import options are set in the view Matching. These import options apply to both the matching and the mapping.
Setting the import options:
-
Go to Data » Import » [Open import].
→ The view Settings opens. -
Open the view Matching.
-
Determine the import options. Pay attention to the explanations given in Table 2.
-
Save () the settings.
Import option | Explanation | ||||||
---|---|---|---|---|---|---|---|
Import options |
How do you want to import the data?
|
||||||
Decimal number |
How are decimal numbers formatted in the import files?
|
||||||
Date format |
How are calendar dates formatted in the import files? If the calendar dates in the file are formatted in the standard format Y-m-d H:i:s, you do not need to enter any format. All other formats must be specified. All php-compliant date formats are allowed. |
3. Show the first five rows of the import file
Use the preview function to view the first five rows of the import file in a table. For example, this is useful if you are not quite sure how the file is structured.
Showing a preview:
-
Go to Data » Import » [Open import].
-
In the toolbar, click on Preview ().
→ In a new window Preview, the first five rows of the import file are shown in a table. -
Click outside the window to close it.
4. Specifying matching fields
you have created an import. Now, open the import to continue with the settings. First, select the fields that should be used for matching data records. At the same time, you specify what happens if no existing record is found during the matching.
You can specify one, multiple or all matching fields. The matching fields are different for each import type.
Matching fields are optional
The matching fields are optional. However, if you do not select a matching field, the data in your file cannot be assigned to existing data in your system. So new data records are saved during each import. This can result in duplicate records in your system. |
Specifying matching fields:
-
Go to Data » Import » [Open import].
→ The view Settings opens. -
Open the view Matching.
-
Carry out the settings. These settings depend on the import typ you selected.
-
Save (save) the settings.
5. Mapping fields
Mappings allow you to specify which columns of your file are imported to which PlentyONE data fields. So without any mappings, no data can be imported. However, you do not need to map all sources of the import file. Only map the sources that you want to import.
5.1. Procedure
-
Create the mapping. In other words, you specify in which PlentyONE data fields you want to save the data of the import file. (How?)
-
You map the sources of the import file to the PlentyONE data fields in which you want to save the data. (How?)
Tip: You can also manipulate the data from the import file in different ways during the import:-
You specify your own value. By doing this, you will save the same value in a PlentyONE data field for all data records. (How?)
-
You create a regular expression to reorder the data of a source. (How?)
-
You create a mathematical formula to recalculate numerical values of a source during the import.
-
You create your own mappings to replace the values of a source with other values during the import. (How?)
-
-
You activate the sources to be imported. (How?)
In CSV files, each column is a source. TXT files are structured differently. However, it makes it easier to also imagine the data they contain as columns.
5.2. Understanding the "Mapping" menu
-
The column Import data is a list of all columns in the import file. There is one row per column.
-
The column Preview shows the first 6 values of each column of the file.
-
In the column PlentyONE data fields, select the PlentyONE data field to be filled with the data of the column.

5.3. Creating a mapping
Creating a mapping:
-
Go to Data » Import » [Open import].
→ The view Settings opens. -
Switch to the view Mapping.
-
Click on Add mapping (add).
→ The window New mapping opens. -
Enter a name for the mapping.
-
Save the setting.
→ The mapping is created and opened.
→ The new mapping is active automatically.
Tip: The position of the mapping is assigned in ascending order automatically. In other words, the first mapping of the import has the position 1, the second mappings has the position 2, etc.
You can change the name and the position of mappings at any time:
-
In the toolbar of the mapping, click on Settings ().
→ To the right of the toolbar, the fields Name and Position are shown. -
Adjust the name and/or the position.
-
Save (save) the settings.
5.4. Mapping data fields
In the view Mapping, decide which column in your file is imported to which data field in PlentyONE.
Use the preview function to view the first five rows of the import file in a table. For example, this is useful if you are not quite sure how the file is structured.
Showing a preview:
-
Go to Data » Import » [Open import].
-
In the toolbar, click on Preview ().
→ In a new window Preview, the first five rows of the import file are shown in a table. -
Click outside the window to close it.
Mapping data fields:
-
Go to Data » Import » [Open import] » [Open mapping].
-
Select a PlentyONE data field for each column that you want to import.
-
Save (save) the mappings.
5.4.1. Custom mapping: Own value
The option Own value allows to import a fix value for the data field. Thus, this fixed value is identical for each data record that is imported during this import.
You want to import a file into PlentyONE. 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 ElasticSync’s "Own Value" function to add missing information to your sync.
Note: The term ElasticSync is outdated and has been replaced by import.
Mapping your own value:
-
Navigate to the bottom of the view.
-
Click on add FIELD.
→ A new line is added.
→ The source Own value is shown by default. -
In the field Value, enter the information that you want to save in the PlentyONE data field for all records of the import.
-
Select the PlentyONE data field in which you want to save the value.
-
Save (save) the mapping.
5.4.2. Custom mapping: Regular expressions
In order to consider a CSV or TXT file during the import as desired, the so-called RegEx function (Regular Expression) can be applied. This functionality manipulates data during the import based on commands. This means that no changes need to be made in the import file.
Handle regular expressions with care!
Regular expressions are a powerful tool. However, they can also be tricky. As such, use regular expressions carefully and only if you are confident that they will work as expected. Some examples of external resources:
|
Watch this video to learn more about the RegEx function.
Note: The term ElasticSync is outdated and has been replaced by import.
Replacing values with the RegEx function:
-
Go to Data » Import » [Open import] » [Open mapping].
-
Navigate to the row of the source that you want to map.
-
In the field Source, select the value Regular expression.
→ The options for Regular expression are shown. -
In the field Value, select the column name of the import file.
-
In the field Search, enter a search pattern.
-
In the field Replace, enter a replace pattern.
-
In the drop-down list Target, select the PlentyONE data field that you want to fill.
-
Save (save) the settings.
→ The data fields are updated during the import.
Value: "24.12.2017"
Search: /^(\\d+).(\\d+).(\\d+)$/
Replace: $3﹣$2﹣$1
Result: "2017-12-24"
Value: “Musterberg, Maxi”
Search: /^(\\w+), (\\w+)$/
Replace: $2 $1
Result: "Maxi Musterberg"
5.4.3. Custom mapping: Mathematical calculations
In the mapping overview, select the option Mathematical calculations in order to recalculate numerical values during the import.
The following calculation methods are available:
-
Addition (+)
-
Subtraction (-)
-
Multiplication (*)
-
Division (/)
-
Plus a percentage (+)
-
minus a percentage (-)
Updating values using mathematical calculations:
-
Go to Data » Import » [Open import] » [Open mapping].
-
Navigate to the row of the source that you want to map.
-
In the field Source, select the option Mathematical calculations.
→ The options for Mathematical calculations are shown. -
From the drop-down list CSV columns, select the column name of the import file.
-
From the drop-down list Operator, select the calculation type.
-
In the field Value, enter a numerical value.
-
In the drop-down list Target, select the PlentyONE data field that you want to fill.
-
Save (save) the settings.
→ The numerical values of the column are recalculated during the export.
Important: The numbers in the import file stay the same.
CSV columns: [Select the column containing the price]
Operator: positive %
Value: 5
PlentyONE data field: [Select sales price]
Result: The prices in the specified column are increased by 5% during the import. This higher price is saved as the price in PlentyONE.
5.4.4. Custom mapping: Own mapping
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.
Own mappings are particularly helpful when internal PlentyONE ID are at play. Examples are characteristic names, item flags, payment methods, countries/states, ISO codes, etc. Take a look at the video for own mappings to get to know the principle.
Learn more about own mappings in this video.
Note: The term ElasticSync is outdated and has been replaced by import.
Defining an own assignment:
-
Go to Data » Import » [Open import] » [Open mapping].
-
Navigate to the row of the source that you want to map.
-
In the dropdown menu of the Source field, select the option Own assignment.
-
Fill in the fields. Pay attention to the explanations given in Table 3.
-
Save (save) the settings.
Field | Setting |
---|---|
Type |
Which column of the CSV or text file contains the values that you want to change? |
Default value |
Which value do you want to save in PlentyONE if a record does not contain any of the values that you entered in the field From? |
From |
Which value of this column do you want to change during the import? |
To |
What value do you want to save in PlentyONE instead of the original value From? |
5.5. Activating sources of a mapping for the import
Now decide which information for your import file you want to import into PlentyONE. Because only active sources are exported.
Example: You received a CSV file with product data from a manufacturer. For now, you only want to import the purchase price (PP) and check the rest of the data later. Instead of deleting all the columns you do not need from the file, you only activate the import for the source/column of the file that contains the purchase price. Nifty, right?
Activating sources for the import:
-
Go to Data » Import » [Open import] » [Open mapping].
-
To the left of the source, click on the toggle button Activate row.
-
toggle_off = The source is inactive. The source is ignored during the export.
-
toggle_on = The source is active. During the import, the data of this source is imported.
-
-
Save () the settings.
-
Go to Data » Import » [Open import] » [Open mapping].
-
To the very left, place a checkmark for all sources that you want to include in the import.
Tip: Click on the check box at the very top to place a checkmark for all sources of the mapping at once. -
In the toolbar at the top, click on Activate all ().
→ All selected sources are activated.
Tip: Correspondingly, you can use Deactivate all () to deactivate several or all sources at the same time. -
Save () the settings.
5.6. Activating/deactivating mappings
New mappings are active automatically when you create them. But you can also deactivate one or more mappings and activate them again later.
Activating/deactivating mappings:
-
Go to Data » Import » [Open import].
-
Switch to the view Mapping.
→ The mappings of the import are shown. -
In the column Inactive/Active, click on the toggle button.
-
toggle_off = The mapping is inactive. During the import, the settings of this mapping are not applied.
-
toggle_on = The mapping is active. During the import, the settings of this mapping are applied.
Important: If more than one mapping is active, the mapping with the lowest position is imported first. All other active mappings are also imported in ascending order based on the position.
-
6. Optional: Filtering import data
You can use filters to limit the data to be imported. To view the filters, open the view Mapping.
Adding a filter:
-
Go to Data » Import » [Open import] » [Open mapping].
-
Click on Filter () in the toolbar.
-
Click on add Filter.
→ A new line is displayed. -
Select the Source from your file that you want to filter.
-
Select which rules are applied.
-
Enter a value.
-
Select an operator. This operator determines how many filters are combined.
Important: If you select the operator And, only those data records are imported that match all filter criteria. -
Add additional filters as necessary.
-
Save (save) the settings.
→ The filters are saved.
→ Only data that meets these filter criteria is exported.
7. Running the import
7.1. Checking imports for errors before the run
You can check imports for errors before the run.
Checking imports for errors before the run:
-
Go to Data » Import » [Open import].
-
In the toolbar, click on Validation ().
→ In a new window, a list of the error messages is shown. -
If errors occur and you need help in the forum:
-
Click on Copy log to clipboard (content_copy).
-
Add the information to your forum post.
-
7.2. Testing the import
The option Test import allows you to check that all import settings are correct before you import large amounts of data.
Important: The first ten lines of the import file are imported during the test.
Testing the import:
-
Go to Data » Import » [Open import].
-
In the toolbar, click on Test import ().
→ The first ten lines of the import file are imported. -
Open the menu that the data was imported to.
-
Check if the data was imported as expected.
-
Modify the import settings as needed.
-
If necessary, delete the data that was imported as part of the test.
7.3. Manually running the import
If you specified an interval in the import settings, the file is regularly imported automatically. However, you can also start an import manually at any time.
There are two ways to import the file:
Import (play_circle_outline) |
The import runs in the background.
|
Live import (play_circle) |
The import starts immediately. The progress is shown in real time.
|
The import runs in the background.
Starting an import:
-
Go to Data » Import » [Open import].
-
In the toolbar, click on Run import (play_circle_outline).
Tip: Even quicker: In the import overview, find the import. On the right, click on Run import ().
→ The data is imported.
Important: The import runs in the background. -
Open the menu that the data was imported to.
-
Check if the data was imported as expected.
The live import allows you to see the import progress in real time in the tab Data import.
Important:
-
When you start the live import, a new browser tab opens. In this browser tab, the PlentyONE tab Data import is shown.
-
The import stops if you close the browser tab or the PlentyONE tab Data import while the import is in progress. Go to Data » Status to resume the import.
-
The import can run into a timeout if you try to import large amounts of data. If that happens, the import is cancelled. In such cases, use the background import instead.
Starting a live import:
-
Go to Data » Import » [Open import].
-
In the toolbar, click on Run live import (play_circle).
Tip: Even quicker: In the import overview, find the import. On the right, click on Run live import (play_circle_outline).
→ a new browser tab opens. PlentyONE and the tab Data import are shown.
No new tab? Then you are probably using a pop-up blocker. Allow pop-ups for your system to continue.
→ The data is imported.
Important: The import stops if you close the browser tab or the PlentyONE tab Data import while the import is in progress. Go to Data » Status to resume the import.
→ The progress is shown in real time. -
Open the menu that the data was imported to.
-
Check if the data was imported as expected.
7.4. Cancelling an import
You can stop an import that you started. This function is only available while the import is being processed.
Important: When you cancel a running import, the records that were already imported are not deleted. If necessary, delete this data yourself.
Stopping an import:
-
Go to Data » Status.
→ The status overview opens. -
At the very right in the line of the import that you want to cancel, click on Cancel import (close).
→ A window opens and you need to confirm your decision. -
Click on Cancel import.
→ The import is cancelled.
→ Only those data records are in the system that were already imported at the time you cancelled the import.
Stopping a live import:
-
In the tab Data import, click on close Cancel import at the top right.
→ The import is stopped.
Important: Any data already imported will not be deleted. If necessary, delete this data manually.
Tip: Go to Data » Status to resume the import. To do so, click on Resume import.
8. Replacing import files of manual imports
You created an import with the source Manual upload. You want this import to manually import a file again and again. This file is always structured in the same way. If the structure of the file’s columns is still the same, you can upload the latest file directly in the import overview.
Replacing import files of manual imports:
-
Save the file on your computer.
-
Go to Data » Import.
→ The import overview opens. -
Navigate to the import.
-
In the File name column, click on the button Upload file (upload).
→ The file directory is shown. -
Click on the file.
→ The file is uploaded.
Important: The mappings are deleted if the column structure of the file has changed after all. So make sure to check that the import settings are still correct.
9. Viewing success and error messages of imports
In the Data » Log menu you can see success and error messages of imports.
Filtering and checking log entries:
-
Go to Data » Log.
-
In the toolbar, click on tune.
-
From the drop-down list Reference type, select the option importId or importName.
-
Optional: Select filters for dates and/or times to only show entries from a specific period.
Tip: For further information about the filters, see the Data log page of the manual. -
Click on Search ().
→ The results are shown. -
Focus on entries for the levels warning and error.
Tip: Click on the entry to see details.
10. Tracking the status of imports
Go to Data » Data import » Status to check the status of your import processes. This shows which imports started and are complete. A progress bar visualises how the import process is going. In addition, you can check if any errors occurred and if all rows of data of the file were imported.
10.1. 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. Each package is a job. 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.
10.2. Viewing the status of imports
Viewing the status of imports:
-
Go to Data » Data import » Status.
→ The status overview opens. -
Optional: Do you need more information about the import? Click on an export to see details.
Column | Explanation |
---|---|
Run ID |
A run ID is created when an import is started. This makes it easier to distinguish the imports. |
Import ID |
The ID of the import |
Name |
The name of the import |
Progress |
The progress of the import process visualised in a bar. When all import processes are complete, the date and time is shown when you point your cursor to the progress bar. |
Error |
Errors that have occurred in the import jobs |
Imported rows |
The number of lines that have been imported from the CSV or TXT files |
Total rows |
The total number of lines in the CSV or TXT file |
Start time |
The start time of the import |
10.3. Filtering the status list
Do you have a lot of imports? Then just filter the list.
Filtering the status list:
-
Go to Data » Data import » Status.
-
In the toolbar, expand the filters (tune).
-
Select the filters you need.
-
Click on Search.
→ The list is filtered.
Tip: The filters that you applied are shown in the toolbar as individual "chips". Delete one or more of these chips to quickly delete filters. Click on Search (search) to update the list.
Filter | Explanation |
---|---|
Import ID |
Reduces the list to imports with this ID. |
Name |
Reduces the list to imports with this name. |
Status |
Reduces the list to imports with this status. You can filter by In progress or by Completed. |
Start date from |
Reduces the list to imports that were started on or after this date. |
Start time from |
Reduces the list to imports that were started on or after this time. |
Start date to |
Reduces the list to imports that were started up to this date. |
Start time to |
Reduces the list to imports that were started up to this time. |
10.4. View import status details
You can view more details about the import.
Viewing import status details:
-
Go to Data » Status.
→ The status overview opens. -
Click on the row of the import.
→ The detail view opens.
→ A list of the errors is shown. Optionally, you can open the view Result. -
Optional: Click on the row of an import.
→ In a new window, the name of the column header, the raw data and the error message are shown.
Information | Explanation |
---|---|
Line |
The line where the error occurred |
Column name |
The name of the column where the error occurred |
Error |
A description of the error |
Raw data |
The raw data of the error |
10.5. Viewing an import log
A log is automatically created for every import process. This log contains information about the import process. The log information helps our supporters to help you analyse the error.
Viewing an import log:
-
Go to Data » Data import » Status.
→ The status overview opens.
Tip: Or open the status menu from the menu Data » Import.
In the toolbar, click on Status (playlist_play). -
Click on the import.
→ The detail view opens. -
At the top left of the toolbar, click on Log (playlist_play).
→ The log is shown in a new window. -
Optional: Click on Copy to clipboard (content_copy). Add the information in the forum when you post a support request.
11. Managing imports
Learn how to manage existing imports.
11.1. Assigning rights for back end users
Users with roles that are not of the type Administrator can only see certain sections and menus in PlentyONE. This means they only have limited access to the system. If employees work with imports and mappings, they need at least the following rights:
-
Data > Sync > Update
-
Data > Sync > Show
-
Data > Sync > Create
-
Data > Sync > Delete
-
Data > Sync > Mapping > Update
-
Data > Sync > Mapping > Show
-
Data > Sync > Mapping > Create
-
Data > Sync > Mapping > Delete
-
Data > Data log
Note that only users with roles of the type Administrator can grant rights.
Assigning rights:
-
Open the menu Setup » Account management » Roles.
→ The roles overview opens. -
Click on New (add).
→ The role creation menu opens. -
Enter a name for the role.
-
Switch to the advanced mode by toggling Advanced (toggle_on) slider.
-
Assign the rights for the respective section by ticking the check boxes indicated above.
Note: You can either grant rights for complete sections or limit the rights you grant the user. To only grant limited rights in a certain section, expand the section. -
Save (save) the settings.
The simple mode and advanced mode are connected. If you check menu visibilities in the simple mode the corresponding permissions in the advanced mode will be checked automatically. The connection only exists in this direction. If you check permissions in the advanced mode no menu or plugin visibilities will be checked automatically. |
11.2. Restoring older/deleted import settings
Did you delete an import by mistake? Or somebody made changes to a well configured import that need to be reverted? You can do both using the backup functionality.
Important:
-
These settings reset the imports to an earlier state. You cannot reset data imported into the system doing this. That’s possible too, but in a different way.
-
Backups are only created once a day during the night. When you import a backup, the data is reset to this state.
-
All imports are reset. As such, you cannot reset only one import.
Example: Somebody changed the settings for an item data import by mistake. However, an import for coupons was also created on the same day. When you run the backup of last night, both imports are reset to the state they were in last night. The import for item data is repaired. However, the import for coupons is deleted because it did not yet exist at the time the backup was created. The solution? Export the import settings of any imports that were created or updated since the last update. After the backup, you can then import these into your system.
Restoring backups of imports:
-
Go to Setup » Settings » Hosting » Backup.
→ The backup overview opens. -
In the line of the backup that you want to restore, click on Restore backup (open_in_browser) on the right.
→ The window Restore backup is shown. -
For the setting Import backup, select the option Partially import data base.
-
Activate the option ElasticSync.
Tip: The import tool used to be called ElasticSync. That is why this option still has this name. -
Click on Restore backup.
→ All imports are reset to the state they were in at the time the backup was created.
→ There is no going back!
11.3. Copying import settings
You can copy one or more imports. That way, you can use well configured imports to quickly create a new import.
Copying import settings:
-
Go to Data » Import.
→ The import overview opens. -
In the column to the very left, check one or more imports.
-
In the toolbar, click on Copy import (content_copy).
→ The import is copied.
→ The name of the copied import isCopy of [name of original import]
.
11.4. Exporting import settings
You can export imports to a JSON file. This allows you to save imports on your computer or share them with other people.
Exporting import settings:
-
Go to Data » Import.
→ The import overview opens. -
Select one or multiple imports.
-
Click on Export format (system_update_alt).
→ The import settings are saved to your computer as a JSON file.
11.5. Exporting import settings
Our support team might provide you with an import template. The manual also offers a few best practice files. Or a nice person published a well-configured import in the forum.
You can import these templates into PlentyONE.
This video shows how to use preconfigured imports in order to safe time when importing data.
Note: The term ElasticSync is outdated and has been replaced by import.
Importing import templates:
-
Save the import template on your computer.
Tip: Import templates are always JSON files. -
Go to Data » Import.
→ The import overview opens. -
Click on Import format (open_in_browser).
→ A list of the files in your webspace is shown. -
Click on Upload file (upload).
-
Click on the import template.
→ The file is uploaded to the webspace. -
In PlentyONE. click on the file.
→ You are asked to confirm: "Do you really want to start the import?" -
Click on Yes to confirm.
→ Because the import template comes from a different client, you are asked to adjust settings. -
Click on OK.
→ The import template is imported to PlentyONE. -
Open the import.
-
Check the import settings.
-
Specify matching fields.
-
Create the mappings.