Important
You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Data Import Concept Guide¶
One of the most time-consuming aspects of setting up a new store is getting all your data into the system. Whether OroCommerce is the first e-commerce application for you as a new store owner or you are an existing store owner who is transitioning from a different application, working with a freshly installed clean application can seem daunting, and you may not know where to start. One of the first things you will need to do is move all your data into the Oro application. Manual import can be tedious when dealing with large amounts of data, that is why Oro applications are equipped with a powerful import engine that makes sure that all of your data is uploaded correctly and swiftly in a .csv format.
Pre-Import Guidelines¶
Data import is available for a number of different entities, including, but not limited to, products, master catalog categories, customers, accounts, and many more. You may be tempted to migrate your data in random order, but there are a few rules of thumb to follow before you start any import operation.
Oro applications have built-in import templates available for every importable entity. You need to download them before you initiate any import operation and make sure your data fits the template format. The templates are ready for you to export from the import dialogs of every importable entity; this way, they are never lost and are always on hand and ready for you. Each of these templates is different, depending on what entity you need to import.
That is why it is essential to:
Ensure that your .csv file is saved in the Unicode (UTF-8) encoding. Otherwise, the content of the file can be rendered improperly
Ensure that the syntax and punctuation of your .csv file is the same as in the Oro template
Examine all the fields required for the import from left to right, and make sure that the .csv file you will be importing has all the required information for the entity you are importing
Validate your file to make sure it is error-free. You are emailed validation results. If there are any entries with errors, fix them in your .csv file before initiating import
Perform import in the correct logical sequence, otherwise you will experience content management issues. For example, if you try to import products before product attributes, or customer users before customers, your import will fail. Start import only after you have double-checked that the import sequence makes sense
Ensure that all the necessary features are configured in the application, such as a suitable default currency or product unit
Logical Import Sequence¶
Out-of-the-box, the import is enabled for the following types of data:
|
Products, Product Attributes, Product Images, Price Attributes Data, Price Lists, Inventory Levels, Customers, Customer Users, Master Catalog, Tax Rules, Tax Rates. |
|
Leads, Opportunities, Accounts, Contacts, Business Customers |
You should not experience any import issues if you follow the steps outlined in the section above and make sure that the content you are uploading follows the import guidelines. We are going to provide several examples of logical data import sequence that you can follow when working with your Oro application.
Product Data Import¶
Whether you are creating a product manually from scratch or uploading a large .csv file with hundreds or thousands of products, you need to make sure that the order in which you are adding product-related entities into the application makes sense.
There are seven mandatory steps in the product data upload sequence and some optional steps (marked below) that do not compromise the success of the import operation.
Create and define Product Families with product attributes
Import Tax Rules and Tax Rates (optional)
Import Related Products (optional)
Import Price Attribute Data (optional)
The following screenshot illustrates a .csv file filled in according to the downloaded product import template:
Hint
Check out Products user documentation on creating different types of products manually.
Customer Data Import¶
Customer users are linked to their customers, which is why importing customers and their roles into the application should go before importing customer users:
Create and define Customer User Roles
Hint
For more information on customers, see Customer Permissions and Customer Management concept guides, and Managing Customer Entities in the Back-Office user guide.
Inventory Levels and Statuses Import¶
You can import inventory information once the application has all the products to link inventory levels and statuses to:
Create a warehouse
Import Products (see the Product Data Import section above).
You can either upload inventory statuses only or detailed inventory levels based on the inventory templates that you can download from the import dialog.
Hint
Check out more information on inventory and warehouses in the Inventory Management concept guide and Manage Inventory in the Back-Office user guide.
As you can see, the data that needs to be prepared before every import is available in every import template. Once the data is ready and validated, you can launch import and select the import strategy (if strategy selection is available for your entity). Interactive status messages display the import progress, and once the import is complete, the changes are reflected in the list after a refresh. You will also get an email with the import status.
Import Strategies¶
When importing some particular entities, such as business customers, price attributes, contacts, price lists, and languages, you have three import strategies to select from:
|
Add and Replace strategy overrides the existing values with the ones mentioned in the file for the corresponding importable entity. Also, it adds new values to items with empty fields. |
|
Reset and Add strategy removes all the current values from the entity and adds only the ones listed in the .csv file. |
|
Add strategy adds new values listed in the .csv file to the ones that already exist for a particular importable entity |
Images or Files Import¶
Hint
This feature is available since OroCommerce v4.1.7. To check which application version you are running, see the system information.
Each importable entity has entity fields of different data types. When you need to upload any attachment to the entity record, be it image or file, you need to make sure that you have input all the required information for the import to process successfully. All attachment fields can be either of a file, image, multiple files, or multiple images data type.
Note
Check out the Create Entity Fields topic for more info on how to create and manage entity fields and the entity field properties.
Such field types have two image- or file-related columns that need to be considered when exporting or importing the .csv file.
Let’s illustrate the example using the Contact entity.
Your contacts have various information that is required to be filled in before importing, e.g., name, gender, job, phone, address, Twitter, and picture. Pictures are usually used as avatars to represent a person. The picture entity field is of the image type, therefore, the .csv template will have two related columns — Picture URI and Picture UUID. The names of the columns can differ per entity depending on the field name. The typical names can be the following — YourFieldName.URI, YourFieldName.UUID. For the fields of a multiple files/multiple images type, the names can be YourMultipleFieldName4.URI and YourMultipleFieldName4.UUID, where 4 is the index of the item in collection.
ID |
Name prefix |
First name |
Middle name |
Last name |
Name suffix |
Gender |
Description |
Job Title |
Fax |
Skype |
Birthday |
Source Name |
Contact Method Name |
Emails 1 Email |
Phones 1 Phone |
Accounts 1 Account name |
Accounts Default Contact 1 Account name |
Addresses 1 Label |
Addresses 1 Organization |
Addresses 1 Name prefix |
Addresses 1 First name |
Addresses 1 Middle name |
Addresses 1 Last name |
Addresses 1 Name suffix |
Addresses 1 Street |
Addresses 1 Street 2 |
Addresses 1 Zip/Postal Code |
Addresses 1 City |
Addresses 1 State |
Addresses 1 State Combined code |
Addresses 1 Country ISO2 code |
Organization Name |
Picture URI |
Picture UUID |
Tags |
||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
111 |
Mr. |
Jerry |
Roy |
Greenwell |
male |
03-07-1973 |
website |
765-538-2134 |
Big D Supermarkets |
Big D Supermarkets |
Primary Address |
Jerry |
Greenwell |
2413 Capitol Avenue |
47981 |
Romney |
US-IN |
US |
ORO |
/var/www/my-project/var/import_export/files/testimage.jpg |
38a198a5-e73b-4bfb-a9f4-f590af8b813e |
Picture URI — a path to the image or file location on the server. It can be either a 1) URL, 2) an absolute path, or 3) a relative path (in this case, the files are searched in the {PROJECT}/app/import_export/files/ directory). The URL specified in the import file must be publicly accessible for the application to properly access it during import.
Picture UUID — a unique identifier that is generated by system automatically. When you import a new image or file, leave this field empty, as the system should generate the identifier by itself. This way, all images and files are assigned unique codes that are used to track the attachments within the system. You can reuse the UUID in other templates if you need to import the same attachment for another entity. For this, you need to export the file with images, find the required image from the list, copy it’s UUID, and paste it to your new template. In this case, the provided UUID serves as a reference to the image or file location. Once the image or file is imported, a new UUID is generated to avoid duplication.
If the DAM functionality is enabled for the entity field, then, the files uploaded to this field will be also created as digital assets and can be further re-used in any other DAM supported entity field.
Keep in mind that if values are provided in both columns, the value of the UUID column is always prioritized first, regardless of what is mentioned in the URI column.
Note
Pay attention that URLs to files or images exported from the ACL protected fields are not publicly accessible and cannot be used for import as is.
Related Topics