Magento 2 Extensions:Order Import Module

Overview

Importing orders from CSV/TXT/Tab/Fixed-Length/XML files (and Excel/XLS/XLSX if using Magento 2!) into Magento has never been easier. Using the Order Import Module by XTENTO you will be able to import orders from third party systems into Magento - fully automated! Connect your Magento store to almost any 3rd party system and have orders import into Magento - completely automated.

Interested in this Magento Extension?

Head over to our store to purchase this extension: Order Import Module

Got questions? Feel free to contact us! Contact Form

Setting up the extension

• Please refer to our general Extension Installation and Setup Guide for installation instructions.

After installing the extension as instructed in our general installation guide, please go to System > XTENTO > Sales Import. Please enter your license key there and set Module Enabled to "Yes".

• Please make sure the Magento cronjob has been set up for the Magento installation you're installing the extension in. If the Magento cronjob hasn't been set up, you won't be able to automate imports.
• (Only required if you want to process spreadsheets such as XLS/XLSX/ODS, not required for CSV): NOT required if installing via composer, but required when installing extension via ZIP upload: Connect via SSH, go into the root directory of Magento and install the spreadsheets library by running the command:

cat composer.json | grep -q 'magento/project-community-edition' && (composer require phpoffice/phpspreadsheet "^1.0" ; composer dump-autoload) || echo 'composer.json seems to be broken! cannot install.'

Migrating from Magento 1 to Magento 2

Migrating your settings from Magento 1 to Magento 2 couldn't be easier. Unless you have customized the modules code, usually all your settings can be migrated without any additional work. In your Magento 1 environment, simply go to Sales > Sales Import > Tools and export your profiles and sources. Then, log into Magento 2 and go to Sales > Sales Import > Tools and import them there. That's it! Test everything and make sure it works as expected, but usually all settings are compatible with Magento 2 as well.

Configuring the extension

The following description will cover the modules configuration located at Sales > Sales Import.

Import Profiles

Import profiles can be set up for manual and automatic imports. Every profile contains information about the data to import (e.g. field mapping), when, how, and where to import from, as well as some other settings. The extension supports an unlimited number of different import profiles.

To set up new import profiles or to modify existing import profiles, please go to Sales > Sales Import > Import Profiles.

Setting up a new import profile is easy. Press the "Add New Profile" button. You will then be asked to select the entity (e.g. "Sales") to import, the file format (CSV/XML/TXT/...), as well as to assign a name to the profile which can be used to identify the import profile in import logs. Press the Continue button.

You will then be presented with the profile configuration. The configuration of import profiles is split into several different sections ("tabs") which are explained below.

1) General Settings

General Configuration
Name: Enter the name of the profile. This name will show up in execution logs and will be used to identify the profile when importing.
Enabled: If set to "No", this profile won't show up for manual imports nor will automatic imports be made.
File Processor: This defines the file format which will be imported, e.g. CSV/TXT/XML/... Import Type: Can't be changed after profile creation. Defines which entity (data type) gets imported. Available entities:

2) Settings & Filters

Import Mode: Defines how the import profile should behave and how it should treat new or existing orders. Available modes:

Customer Mode: Defines how customers should be identified/matched. Available modes:

Order Identifier: This is what is called the Order Identifier in the import settings and is what's used to identify the orders in the import file. Almost always you will want to use the Order Increment ID (Example: 100000001). You can also use the internal order entity_id, invoice, shipment or credit memo number here to identify orders to import in the file you're uploading.

Product Identifier: This is what is called the Product Identifier in the import settings and is what's used to identify the product in the import file. Almost always you will want to use the SKU. You can also use the products entity_id or a custom product attribute to identify products to invoice/ship. In your import file mapping, STILL map the field containing the entity_id or custom product attribute value to the "sku" field on sales_order_item level.

Process order only if...: Works for existing orders only (that is, update mode, order exists in Magento already). You can set up various filters that are checked against the order before importing here. If an order does not match the specified filters, it will be skipped and not thus not imported.

3) File Mapping

This section maps your import file format to the fields which will be adjusted/updated in Magento.

The options you see depend on the file processor selected when creating the profile.

Foreword

Before reading the manuals of the file processors (CSV, XML, ...) following below, let's give you a general overview of what is special with regards to order imports and how you should approach the file mapping, i.e. defining which data gets saved where.

Which fields should be mapped?
In general: Map all the fields you have in your import file. The module loves to take as much data as you have and save it against the order. But it's also no problem if you don't have much data in your import file. It is possible to import orders from very, very minimal files, samples follow below.

Which fields are REQUIRED when importing an order?
Not many really:
- Item: You will definitely need to provide product_id or SKU as well as qty for the products you want to add to an order.
- Payment/Shipping: Also, it is recommended to define a the payment:method field as well as the order:shipping_method field, but you can assign default values for those fields in the mapper.
- Customer/Address: Customer-wise, if you import the customer_email or customer_id field, the module will automatically assign the order to the correct customer, or create one in Magento. If the customers don't exist in Magento yet, it is required to map the billing:firstname, billing:lastname, billing:street1, billing:postcode, billing:city, billing:telephone billing:region, billing:country_id (two letter code such as US or DE), but you could also assign default/fallback values for those fields or leave them empty if you don't have them.
- (Unless you have a single-store-setup): It is also recommended to map the store_id to one of your stores, as it avoids problems with customer identification and much more. You need to decide into which store you want to import anyways.

Which fields CAN be set/updated?
Any field in the sales_order* tables. You will have a dropdown and the module dynamically retrieves all fields from the sales_order, sales_order_payment, sales_order_address and sales_order_item tables.

Order # / increment_id
If you don't map the increment_id field, the module will have Magento generate an order# when saving the order, just like if somebody placed an order in the checkout.

Customer # / customer_id / customer_email
You can define the "customer mode" (import as guest, create customer, ..) in the Import Settings tab of your import profile. If you map the customer_id or customer_email, the module will look up the customer and attach the order to his account. Also, the billing/shipping address will be read from the customer (unless you imported values for billing/shipping address - then of course those will be used).

ext_order_id
It is recommended to map the ext_order_id field. This field is the "external order ID" and is used to group items within an order, so multiple items create just one order. Map it to whatever order ID your 3rd party providing the file has defined for the order, this can be the ID of the marketplace you are importing the order from, for example.

CSV/TXT/Tab-delimited

Use this processor if you want to import CSV/TXT/Tab-delimited file formats, so any format where fields are delimited by some character, e.g. , ; | etc.

Configuration
Skip header line: Set this to "Yes" if you want to skip the first line of each imported CSV file as it's the header line containing the column names. You must set this to "Yes" if the first line contains the column names and you want to map fields by column name.

Field Delimiter: REQUIRED: Set the field delimiter (one character only). Example field delimiter: ; (Hint: If you want to use a tab delimited file enter: \t)

Field Enclosure Character: Set the field enclosure character (one character only). Example: "

File Mapping
You can can map the import fields to the actual column names in the CSV/TXT/etc. file here. Make sure to enter the EXACT same column name (case-sensitive).

If there are no column headers in the import file, you can also map by index. The first field in the file would be 0 - the second field in the file would be 1 and so on.

For CSV/XLS/XLSX files it is VERY important to either map the increment_id or ext_order_id field. These fields are used to "group" items within an order, so if you have 5 rows of order/item data, those five items are added into ONE order and not five separate orders. If you map the increment_id field, this will be used as the Magento order number. If you don't want to "set" the Magento order number and want Magento to assign the order number, map the ext_order_id field instead which also groups items within an order, map the ext_order_id field to your Marketplace order number for example, for example if importing orders from Amazon this could be something such as "048-7044123-9742149" in your file.

"Additional Configuration"

The "Configure" button shown right next to each field mapped using the Field Mapper opens a popup where custom XML "code" can be specified. This custom XML can be used to manipulate the data mapped for this field, coming from your import file.

If you open the configuration popup for the first time it will have the following contents: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
</configuration>

This is the default configuration markup. Various actions can be specified there to manipulate field data, for example to map field values (if your mapped field "order status" contains "X", set the value to "processing" for example) or skip import rows, etc.

The following actions can be used:

map: Map values, for example if the data in the file for your mapped field equals "mytracker" (case-sensitive) map that to "tracker1" instead, and if it *matches* the regular expression "[0-9]" (no // delimiters may be used) map that to "tracker2" instead:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <map from="mytracker" to="tracker1"/>
    <map from="[0-9]" to="tracker2" method="preg_match" regex_modifier="i" />
    <map from="^1Z" to="tracker3" method="preg_match" negate="true" regex_modifier="i" /> <!-- Negate option, added in module version 2.2.4 - matches only if the "from" value does NOT match -->
</configuration>

replace: Replace data in field values for your mapped field. For example, if your field contains "order_" and you want to replace that with "" (empty string), or replace using a regular expression, for example remove numbers from the data:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <replace search="order_" replace=""/>
    <replace search="[0-9]" replace="" method="preg_replace" regex_modifier="i"/>
</configuration>

Example to replace everything after the last dot and the dot itself: <replace search="\..*$" replace="" method="preg_replace" regex_modifier="i"/>

Example to replace everything AFTER the first space (so import only the part BEFORE the first space): <replace search="\s.*$" replace="" method="preg_replace" regex_modifier="i"/>

Example to replace everything BEFORE the first space (so import only the part AFTER the first space): <replace search="^.*\s" replace="" method="preg_replace" regex_modifier="U"/>

Example to prepend / prefix text to the current field, for example add "GS" in front of the field value: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
<replace search="^([A-Za-z0-9\.\-\s]+)$" replace="GS\1" method="preg_replace" regex_modifier="i"/>
</configuration>

Example to append text to the current field, for example add "Hello" at the end of the field value: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
<replace search="^([A-Za-z0-9\.\-\s]+)$" replace="\1Hello" method="preg_replace" regex_modifier="i"/>
</configuration>

Example to change the date format, from DD/MM/YYYY to Magento internal YYYY-MM-DD date format: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
<replace search="(\d{1,2})/(\d{1,2})/(\d{4})" replace="\3-\2-\1" method="preg_replace" regex_modifier="i"/>
</configuration>

use: If a field from your import file matches or equals "X", use a different field from the file for this mapped field instead. For example, if the first field in your file (index 0) is X use the third field (index 2) from the file for this field instead, or if it matches the regular expression "[0-9]" use the 8th field (index 7) from the file instead:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <use field="2" if="0" is="X"/>
    <use field="7" if="0" is="[0-9]" method="preg_match" regex_modifier="i"/>
    <use field="7" if="0" is="[0-9]" method="preg_match" negate="true" regex_modifier="i"/> <!-- Negate option, added in module version 2.2.4 - matches only if the "is" value does NOT match -->
</configuration>

skip: If a field in your import file matches or equals "X", the current import line/row will be skipped, so the order won't be updated. For example, if you have a field with the column header "Indicator" that is "X" or matches the regular expression "[0-9]", the row will be skipped:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <skip if="Indicator" is="X"/>
    <skip if="Indicator" is="[0-9]" method="preg_match" regex_modifier="i"/>
    <skip if="Indicator" is="[0-9]" method="preg_match" negate="true" regex_modifier="i"/> <!-- Negate option, added in module version 2.2.4 - matches only if the "is" value does NOT match -->
</configuration>

calculate: New since version 2.0.9, this allows you to do arithmetic operations on imported values. For example, add 20% to the imported price field:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <calculate operation="*" value="1.2"/>
</configuration>

The following operations are allowed: + - * /

Calculations don't work? Make sure the numbers you are trying to calculate with are real numbers ("100" or "1.12") and not numbers in wrong format with comma as decimal separator ("1,23"). In case you use comma as decimal separator, do it like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <replace search="," replace="."/>
  <calculate operation="*" value="1.2"/>
</configuration>

All actions can be combined, for example: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <map from="mytracker" to="tracker1"/>
    <map from="[0-9]" to="tracker2" method="preg_match" regex_modifier="i" />
    <replace search="order_" replace=""/>
</configuration>

XLS/XLSX/ODS/Excel

Only available in the Magento 2 version of the extension: Since version 2.0.0 (released in September 2019) it is possible to import and process XLS/XLSX/ODS/Excel files using the extension. When setting up a new profile, simply select the XLSX file processor. Then, map your profile exactly like described in the CSV section above - it's the same mapping-wise, but in the background magically your XLS/XLSX file will be processed.

XML

Use this processor if you want to import XML file formats.

Configuration
Data XPath: Set the XPath for the node containing the order updates.

Example XML file:
<orders>
<order>
...
</order>
<order>
...
</order>
</orders>

The order updates would be located in each "order" node, which are located in the "orders" node, so the XPath would be: //orders/order

Every "order" node located under the "orders" node would be processed then.

More information about XPath can be found here: http://www.w3schools.com/xpath/

File Mapping
You can map the actual import fields to the fields in the XML file here. Make sure to enter the EXACT same name (case-sensitive).

What you enter into the "Field Name" field is XPath. So for example if you had this XML markup:

<orders>
<order id="100000123">
<customer_email>[email protected]</customer_email>
</order>
</orders>

To fetch the ID you would enter: @id (@ in front because it's an attribute) To fetch the customer email you would enter: customer_email (This is the field name of the field you want to fetch, as it's on order level you don't need a prefix.)

More information about XPath can be found here: http://www.w3schools.com/xpath/

Nested Nodes

If your fields are nested in nodes, you can specify additional XML using the "Configure" button that defines whether a field should be retrieved from a different / looping node below the current XPath. For example, if you want to import this format (item information NESTED under the order information):
<orders><order><id>X</id><items><item><product>test123</product><qty>1</qty></item></items></order></orders>
The nested tracking data node would be //items/item then as the items are child nodes of the data node. The following XML would be specified using the "Configure" button for the "sku" field (for the "File Field Name / Index" you would enter "product" (without the quotes) as that is the name of the field on //items/item level):
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<nested_xpath xpath="//items/item"/>
</configuration>

"Additional Configuration"

Please refer to the Additional Configuration section of the CSV processor. It's the same for XML.

Fixed-Length Formats

It is also possible to import fixed-length formats using the module. Just select the CSV/TXT/Tab processor when creating a profile.

For the Field Delimiter column enter: FLF When mapping a field at "File Mapping", you would enter the starting and ending position of the field into the "Field Name / Index" field.

For example if you want fetch position 5 to 30 you would enter: 5-30

4) Actions

The Import Actions tab defines which actions will be executed for an order found in your import file. The import actions are executed in the sort order set up in the import actions table.

Import Actions

Order Import

Import and/or update order: This is the most important action. It should be added to every import profile, otherwise no import/update will be processed.

Invoice Actions

Create invoice for imported order: If enabled, the module will try to create an invoice for the imported order. Please note no invoices can be created for an order if it has been completely invoiced already or if the order status does not allow invoicing (complete, or canceled, etc.).

Send invoice email to customer: If enabled, and if an invoice was created, the invoice email will be sent to the customer.

Capture payment for invoice: This will try to capture the payment at the payment gateway, i.e. charge the credit card if possible.

Set invoice status to "Paid": Marks the invoice as paid. This happens automatically if the payment is captured using the above action.

Shipment Actions

Create shipment for imported order: If enabled, the module will try to create a shipment for the imported order. Please note no shipments can be created for an order if it has been completely shipped already or if the order status does not allow shipping (complete, or canceled, etc.).

Send shipment email to customer: If enabled, and if a shipment was created, the shipment email will be sent to the customer.

Order Status Actions

No order status actions, just import the sales_order "status" field to whatever status you want to set for an order.

"Additional Configuration"

The "Configure" button shown right next to each import action opens a popup where custom XML "code" can be specified. This custom XML can be used to manipulate action values, for example if a mapped field contains "X" don't run this action.

If you open the configuration popup for the first time it will have the following contents: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
</configuration>

This is the default configuration markup. The following actions can be used:

set: Manipulate the action value. For example if you configure the action "Create invoice for imported order", and want its value to be set to "No" (=don't create an invoice) if the mapped field "Custom Field 1" (mapped in the "File Mapping" tab) equals "X", and want it to be set to "Yes" (=create an invoice) if the "Custom Field 1" value matches the regular expression "[0-9]", you would use:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <set value="false" if="custom1" is="X"/>
    <set value="true" if="custom1" is="[0-9]" method="preg_match" regex_modifier="i" />
    <set value="true" if="custom1" is="^1Z" method="preg_match" negate="true" regex_modifier="i" /> <!-- Negate option, added in module version 2.2.4 - matches only if the "is" value does NOT match -->
</configuration>

5) Import Sources

Select the import sources where files should be downloaded from before importing simply by checking the checkbox right before the Source ID.

Please refer to the Import Sources section below to get an idea how to configure and set up import sources.

6) Automatic Import

It is possible to set up cronjob imports for import profiles, so profiles are executed automatically on a time schedule.

Cronjob Import

If you want to automate imports, you can set up cronjobs for profiles which execute the import for this profile at certain times automatically. First of all, make sure to set up your Magento cronjob as explained here. You can easily check the cronjob status by looking at the "Cronjob Import" section when editing a profiles "Automatic Import" tab. The Cronjob Status field will contain information about the status of the cronjob and whether any action is required or not.

To enable cronjob imports for this profile, simply set Enable Cronjob Import to "Yes". Select the Import Frequency of how often you want the import to run. That's it.

It is also possible to set up multiple, different cronjobs for one profile, for example if you wanted the cronjob to run at certain times during the week and only at 10pm on weekends. To do so, select "Use custom import frequency" from the Import Frequency dropdown, and enter one or more cron expressions separated by a semi-colon (;) in the Custom Import Frequency field. You can enter an unlimited amount of cron expressions there separated by semi-colons, just make sure they are valid cron expressions.

Example custom cron expression calling the cronjob for a profile at 8am, 1pm, 3pm at every full hour from Monday to Friday: 0 8,13,15 * * 1-5

Further examples:

Important: Automated imports will only be made if the profiles status (under General Configuration) is "Enabled".

6) Profile Execution Log

The profile execution log shows any imports made using this profile, be it manual or automatic.

7) Profile Import History

This section shows which objects (orders) were imported by this profile and when. Also, includes debugging information such as the data that was mapped from your import file.

Import Sources

Import sources are the actual "sources" where imported files will be downloaded from. If your only goal is to manually import and upload import files from the Magento backend, you won't need to set up any import sources. If you need to download import files from remote FTP servers or certain local directories on the Magento server, you will have to set up import sources.

The module supports an unlimited amount of different import sources. The following source types are currently supported:

Setting up Import Sources

To set up import sources, go to Sales > Tracking Import > Import Sources. You can modify existing sources there or add new sources.

Setting up a new import source is easy. Press the "Add New Source" button. You will then be asked to select the source type (from which type of "server" the imported files will retrieved from) to create, as well as to assign a name to the source which can be used to identify the source in import profiles and logs. Press the Continue button. You will then be presented with the source configuration.

Source Types

Local Directory

This source type will simply fetch imported files from a local directory on the Magento server.

If you begin the path with a dot in front of it, for example ./var/import/ the path will be relative to the Magento root directory. This means the file would be loaded from the /var/import/ directory located in the root directory of Magento.

Supplying an absolute path is possible by beginning the path with a dash, for example: /var/www/tmp/import/

Please make sure the path you enter is readable by the webserver. It must be possible for the webserver to read the files in that directory, otherwise a warning will be shown/logged.

FTP Server

The FTP source type supports downloading files from FTP servers.

The following configuration must be entered for FTP servers:

Potential issues: Connection/upload fails

• A firewall is probably blocking the ingoing or outgoing FTP connection. Please make sure no firewall is blocking the connection - both on your side as well as on the remote (FTP server) side. You could also try enabling passive mode in the import source.

SFTP Server

The SFTP (Secure File Transfer Protocol) source type is identical with the FTP source type, except that it loads files from a SFTP server. This source type supports SFTPv2 and SFTPv3 servers only, other SFTP server types are not guaranteed to be compatible. To find out which SFTP server version your server is using, connect to it using WinSCP (download here and look at the very bottom status bar. It will show the SFTP server version.

Most of the time port 22 is used for SFTP servers.

Potential issues: Connection/upload fails

• A firewall is probably blocking the ingoing or outgoing SFTP connection. Please make sure no firewall is blocking the connection - both on your side as well as on the remote (SFTP server) side.
• Please make sure the SFTP server is a SFTPv2/SFTPv3 server as explained above.

HTTP Server

To download files from a HTTP server, please follow the following steps:

1. Go into the app/code/Xtento/OrderImport/Model/Source/ directory and rename the file "Http.php.sample" to "Http.php"
2. Enter the function name you want to call in the Http.php class in the field below.
3. Open the Http.php file and add a function that matches the function name you entered. This function will be called by this source upon importing then.

Example: If you enter server1 in the function name field below, a method called server1() must exist in the Http.php file. This way multiple HTTP servers can be added to the HTTP class, and can be called from different import source, separated by the function name that is called. The function you add then gets called whenever this source is executed by an import profile.

Important: Please make sure the function you enter exists like this in the app/code/Xtento/OrderImport/Model/Source/Http.php file: public function yourFunctionName() { ... }

Potential issues: Connection fails

1. Please go through the steps above one or two more times again to make sure you really set it up exactly as explained.
2. Please make sure there is no firewall blocking outgoing HTTP connections. Get in touch with your hoster if in doubt.

HTTP Download

Downloading a file from a static URL and using this to import is very easy using the "HTTP Download" source. Simply enter the URL to download from after creating a new source with this type, and the extension will download the data to import from this URL when this source is enabled for an import profile.

Additional Guides:

• Setting up imports from Dropbox
• Setting up imports from Google Sheets

Potential issues: Connection fails

1. Please make sure there is no firewall blocking outgoing HTTP connections. Get in touch with your hoster if in doubt.

Webservice/API

To import data from a webservice, please follow the following steps:

1. Go into the app/code/Xtento/OrderImport/Model/Source/ directory and rename the file "Webservice.php.sample" to "Webservice.php"
2. Enter the function name you want to call in the Webservice.php class in the field below.
3. Open the Webservice.php file and add a function that matches the function name you entered. This function will be called by this source upon importing then.

Example: If you enter server1 in the function name field below, a method called server1() must exist in the Webservice.php file. This way multiple webservices can be added to the Webservice class, and can be called from different import source, separated by the function name that is called. The function you add then gets called whenever this source is executed by an import profile.

Important: Please make sure the function you enter exists like this in the app/code/Xtento/OrderImport/Model/Source/Webservice.php file:

public function yourFunctionName() { ... }

Potential issues: No connection

1. Please go through the steps above one or two more times again to make sure you really set it up exactly as explained.
2. Please make sure there is no firewall blocking outgoing HTTP connections. Get in touch with your hoster if in doubt.

Sample Code / Sample Implementations

Please refer to this article for sample code & further information on how to connect Magento to custom REST/JSON/SOAP/... APIs.

Custom Code / Custom Class

You can set up an own class in our (or another) module which gets called when importing. The loadFiles() function would be called in your class. If your class was called \Xtento\OrderImport\Model\Source\Myclass then the identifer to enter here would be \Xtento\OrderImport\Model\Source\Myclass

Please make sure the following function exists in your custom class: public function loadFiles() { ...your code here... }

Logging errors in the profile log for custom sources

If you developed a custom class or set up a custom webservice/HTTP connection function, and in case of errors want to log them in the execution log, you can access the log entry like this to add a warning for example:

$logEntry = $this->_registry->registry('orderimport_log');
$logEntry->setResult(\Xtento\OrderImport\Model\Log::RESULT_WARNING);
$logEntry->addResultMessage(__('Source "%1" (ID: %2): %3', $this->getSource()->getName(), $this->getSource()->getId(), 'Something went wrong'));

Enabling Import Sources in Profiles

To associate created import sources to import profiles, open an import profile and go to the Import Sources tab on the left and select the import sources where the file should be retrieved from by selecting the checkbox in front of it. Then save the profile.

You can associate an unlimited number of sources to a profile.

Using the extension

The following functions can found at Sales > Tracking Import.

Manual Import

Importing updates manually is easy. After configuring the extension and creating profiles, just go to Sales > Tracking Import > Manual Import.

First of all, select the profile you want to import. You can then select a file to upload (no files will be loaded from configured sources then) OR if you don't select a file to upload, files will be downloaded from configured sources in the import profile.

There are two more options to enable here. Test Mode and Debug Mode. If test mode is enabled, no real updates will be imported, nothing will be updated. If debug mode is enabled, a detailed log showing information about the last import will be shown. Both can be enabled at the same time. Run your import in test AND debug mode once to see what happens, once you are sure you want to proceed, run it without test mode.

If you're ready to import, just press the Import button. You will be presented with a success message if the import completed successfully. (Or an error message alternatively)

Automatic Import

To set up automatic imports, please have a look at the Automatic Import section configurable for each import profile. You can check/control whether automatic imports were made or not in the Execution Log.

Execution Log

The profile execution log shows any imports made using all profiles, be it manual or automatic.

Import History

This is very helpful as well - it shows when which order was created and by which profile, based on which data. The data column shows the data fetched from your import file, i.e. which fields were found in the import file and which values they had.

Tools

Export Settings

The extension comes with functionality to export certain module configuration. All or certain import profiles as well as import sources can be selected for exporting at Sales > Sales Import, and can be exported by simply pressing the Export Settings button then. The exported file (ending in .json) can then be imported into another Magento installation using the Import Settings functionality, making it very easy to transfer your settings between development/staging/test/live environments or for clients.

Import Settings

The extension comes with functionality to import certain module configuration from other Magento installations. This means if you've previously exported import profiles or import sources using the Export Settings functionality, you can import it here again.

Please note no passwords of import sources will be imported. These will have to be re-entered manually for destinations.

Questions? Concerns?

Got questions? Feel free to contact us! Contact Form

Interested in this Magento Extension?

Head over to our store to purchase this extension: Magento Tracking Number Import Module

Troubleshooting

Or: How to fix the most common issues.

FTP Download does not work

• A firewall is probably blocking the ingoing or outgoing FTP connection. Please make sure no firewall is blocking the connection - both on your side as well as on the remote (FTP server) side. You could also try enabling passive mode in the import source.

Importing parent/child relationships (configurable, simple products)

In order for the extension to detect which products belong together, you need to create a relationship between the products.

In the File Settings tab of your import profile, be sure to map the following fields on sales_order_item level:
- item_id
- parent_item_id

These IDs don't have to exist in the new store, nor do they have to be specific values. It's just important that the value in "parent_item_id" (in the simple product) is the value of the "item_id" field on the parent item (such as configurable product).

Invoicing/shipping does not work

Enabled the invoice and/or ship actions in your import profiles? And the order doesn't get invoiced/shipped after the import? Make sure to run the import at "Manual Import" and enable debug mode. Most likely the order status doesn't allow invoicing/shipping, make sure to set the order status to "pending" for example.

Common Error Messages

...and how to solve them.

Error: "Exception catched while saving order, could not create/update order. Exception: No such entity with cartId = 0"
Solution: The payment method you are trying to specify for the order could be causing this. Use an offline payment method such as "Check / Money" or "Bank Payment".

Error: "Exception catched while saving order, could not create/update order. Exception: No such entity with cartId = 0"
Solution: Are you using the "Amasty_Affiliate" module? As of September 2020, there seems to be a bug in their module where they forgot to add exception handling in an observer and try to load a quote (which doesn't exist for imported orders). Disable the Amasty_Affiliate module and ask them to fix it.

Numbers import without decimals or Error: A non well-formed numeric value ...

Numbers, such as the "price" field in your import file, are probably in the wrong decimal format. They must use the "." (dot) as the decimal separator and your numbers are probably using commas such as 50,1324. To fix this, in the "Additional Configuration" popup of the affected field in the "File Settings" tab, add a configuration like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <replace search="," replace="."/>
</configuration>

Placing a new order leads to error "Unique constraint violation found"

Are you importing orders along with their increment_id? Make sure the increment_ids (order #s) you are importing are unique and don't conflict with the order# pattern in your installation. So it is always recommended to prefix imported orders with a letter or a number or something like this to make sure the increment_ids will never be similar to the ones that Magento generates for orders you/your customers place in your Magento installation.

To fix this specific error, you will need to go into the database, specifically the sales_sequence_* tables, and increase the value so it doesn't conflict anymore. To avoid this, prefix the increment_ids you import as described above.

Order Import: Exception saving customer.

Example message: Exception saving customer. Probably one of the required fields hasn't been populated. Exception: "Zip/Postal Code" is a required value.

You are 100% sure you have mapped all order address fields correctly? Then probably the customer you are trying to import an order for exists in Magento already, and this customer has a broken address record.

Updating existing items of an existing order

Since module version 2.4.2 it is possible to update items of an existing order. Specifically, columns in the sales_order_item table. Reference order items by mapping the "item_id" field on item level, this needs to match the internal item entity_id you see in the sales_order_item table, this is NOT the product SKU. Also, it is required to provide order increment_id or order entity_id as a mapped field.

Import of orders for existing customers fails

Make sure the store_id (the store you are importing the order to) has been mapped.

Error: getItems() must be of the type array

Getting this error?: Uncaught TypeError: Return value of Magento\InventorySourceSelection\Model\Request\InventoryRequest::getItems() must be of the type array, null returned Seems to be an issue with Magento MSI, the fix can be found here: https://github.com/magento/inventory/issues/3172

Forcing tax to be imported as 0

By default the module calculates tax if it's imported as 0. If you import tax_amount as 0.0000000001 it will probably not calculate taxes.