Magento 2 Extensions:Magento Order Export Module

Overview

Sales Export functionality for Magento 2, integrated into the Magento Backend, including an export manager and a highly flexible output creation technique. Connect your Magento store to almost any ERP, CRM, warehouse, dropshipping or shipping system. Export orders, invoices, shipments, credit memos in an unlimited amount of profiles to an unlimited amount of remote/local destinations, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Interested in this Magento Extension?

Head over to our store to purchase this extension: Magento Order Export 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 > Order Export Module. 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 exports.

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 Export > Tools and export your profiles and destinations. Then, log into Magento 2 and go to Sales > Sales Export > Tools and import them there. That's it! Test everything and make sure it works as expected, but usually templates and settings are compatible with Magento 2 as well.

Configuring the extension

Before proceeding with the configuration, please make sure you're using the latest version of the extension. You can check the installed version at System > XTENTO.

Export Profiles

Export Profiles

Editing an export profiles

Export profiles can be set up for manual and automatic exports. Every profile contains information about the data to export (i.e. orders/invoices/shipments/credit memos), the output format, when, how, and where to export to, as well as some other settings. The extension supports an unlimited amount of different profiles.

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

Setting up a new export profile is easy. Press the "Add New Profile" button. You will then be asked to select the entity (date type, i.e. orders/invoices/shipments/credit memos) to export, as well as to assign a name to the profile which can be used to identify the export profile in export logs. Press the Continue button.

You will then be presented with the profile configuration. The configuration of export 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 exporting manually.
Enabled: If set to "No", this profile won't show up for manual exports nor will automatic exports be made.
Export Type: Can't be changed after profile creation. Defines which entity (data type) gets exported. Available entities:

Export Settings
Save local copies of exports: If set to yes, a copy of every export made will be saved in the ./var/export_bkp/ directory. This is especially useful if you're exporting to FTP destinations, because only then if this is set to "Yes" a local copy of the exported file will be kept so you can download it in Magento from the execution log or directly from the Magento server for whatever reason. Default value is "Yes".

2) Export Destinations

Select the export destinations where exported files should be saved/sent to after exporting simply by checking the checkbox right before the Destination ID.

Please refer to the Export Destinations section below to get an idea how to configure and set up destinations.

3) Output Format

This section defines the output format the profile will create. The extension uses so called XSL Templates to create output formats.

XSL Template

>>> Don't want to create the XSL Template yourself? Have us create the XSL Template for you - we will take care of the output format creation for you. Check out our XSL Template Creation Service. Please contact us before you purchase the XSL Template Creation Service. <<<

When exporting, internally a XML document is created by the module that contains ALL information about the exported objects: billing data, shipping data, payment data, item data and so on. A so called XSL Template then gets applied to this XML document, transforming the XML data into (almost) any other output format. The XSL Template basically "translates" the XML document into whatever output format you require. It is possible to create CSV, XML, ASCII, TXT, ... formats - just any format that is based on text.

The fields available for export (and thus the names used to access them in XSL Templates) can be found by clicking the Show fields available for export button in the Output Format section. A new window will open where the fields and the level they are on (object level, item level, billing level, ...) can be seen. At the very top of the window that was opened, a link called "Show raw XML" can be found which shows the internal XML we talked above. This is the XML document that gets "transformed" by the XSL Template.

A basic XSL introduction can be found here: http://www.w3schools.com/xsl/

Template Structure

We have modified the concept of XSL Templates slightly. In order to be able to create multiple output files with one profile, we have added <file> nodes to the XSL Template structure. Each XSL Template is contained in a <file> node, and multiple <file> nodes under the <files> node will create multiple output formats. Your XSL Templates structure should look like this:

<?xml version="1.0"?>
<files>
<file filename="export-%exportid%.csv">
...XSL Template here...
</file>
</files>

This would create one output file named export-%exportid%.csv where %exportid% is a variable and would get replaced with the export ID. If you wanted to create multiple output files, you would simply add another <file> node so it would look like this:

<?xml version="1.0"?>
<files>
<file filename="export-%exportid%.csv">
...1st XSL Template here...
</file>
<file filename="export2-another-file.csv">
...2nd XSL Template here...
</file>
</files>

Variables in the <file> node

There are several parameters (attributes) for <file> nodes:

• filename: This parameter is required for every file node. It defines the filename of the output file created. Several variables can be used in the filename:

Read more if you need to create custom variables to add to the filename.

• addUtf8Bom: This parameter is optional and allows you to add the UTF8-BOM (byte order mark, basically helps applications to recognize the exported data is encoded in UTF-8) to your exported file. To enable it, add addUtf8Bom="1" to the file tag or your XSL Template.
• encoding: This parameter is optional and would define the encoding of the output format. The value set for encoding, for example encoding="ISO-8859-15//IGNORE//TRANSLIT" or encoding="ISO-8859-15//IGNORE" is passed to the iconv function as the "$out_charset" parameter. You can find more information about iconv and parameters to pass here: http://php.net/manual/en/function.iconv.php
• locale: This parameter is optional and would define the locale used for iconv() translations done using the above "encoding". The value set for locale, for example locale="en_US.UTF8" is passed to the setlocale function for LC_CTYPE (used "for character classification and conversion") and is reverted after the translation. This is important to transliterate characters from other charsets properly. You can find more information about iconv and parameters to pass here: http://php.net/manual/en/function.setlocale.php
• search and replace: Using these parameters you can search/replace certain characters in customer-entered fields. For example if you wanted to replace every comma with a semicolon in fields entered by customers, you would add this:

search="," replace=";"

• quotes: Using the "quotes" parameter, you can configure what should happen to quotes (") in field values. Possible values are "remove" (remove quotes from field values) or "double" (replace a single quote with double quotes). Example:

<file filename="MyFileName.csv" quotes="remove">

This would remove all quotes from field values.

XSL Template Structure

As explained above, XSL Templates are contained in <file> nodes. The XSL Template will create the actual output file created for the <file> node. Let's have a look at every line of a sample XSL Template in detail, explanations after every line. A (simple) CSV export template for the extension could look like this:

<?xml version="1.0"?> <!-- XML Declaration, leave as is -->
<files> <!-- Files node, can contain multiple <file> nodes, each defining one output format -->
<file filename="orders_%d%_%m%_%Y%.csv"> <!-- File node, contains the actual XSL Template, with parameters filename and encoding (optional) -->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:php="http://php.net/xsl"> <!-- The XSL Template begins here. Namespaces get defined. Leave as is. -->
<xsl:output method="text" encoding="UTF-8"/> <!-- The xsl:output directive defines settings that apply to the whole XSL Template. Method can be set to xml for example, encoding will be output for XML files into the XML declaration of the file. More parameters can be found here: http://www.w3schools.com/xsl/el_output.asp -->

<xsl:variable name="sepstart" select="'&#34;'"/> <!-- A variable that can be accessed using $sepstart in the XSL Template. It contains &#34; which is the representation of the " character. -->
<xsl:variable name="sepend" select="'&#34;,'"/> <!-- Again, a variable. This time with the " character as well as a comma. Whenever it is called, it will output: ", -->

<xsl:template match="/">

<xsl:text>"Order Number","Billing Firstname","SKU","Quantity"&#xD;&#xA;</xsl:text> <!-- This is the header line of the CSV file. It gets output once only, the &#xD;&#xA; characters represent a line break that gets output after the header line. -->

<xsl:for-each select="objects/object"> <!-- for-each means that the template will loop through the objects/object nodes in the XML processed. So for every object (order, invoice, ...) the code below will be applied. -->
<xsl:for-each select="items/item"> <!-- Loop through items ordered -->
<!-- This means, loop through all items of an object and output the following: -->

<xsl:value-of select="$sepstart" /><xsl:value-of select="../../increment_id"/><xsl:value-of select="$sepend" /> <!-- The $sepstart variable outputs " to start a new field in the CSV file. Then using xsl:value-of select="../../increment_id" the "increment_id" field is pulled from the object level. ../../ means to get data from the "parent" level (we are looping through items and not through objects (orders). The $sepend variable then outputs ", to denote the end of the field in the CSV file. -->
<xsl:value-of select="$sepstart" /><xsl:value-of select="../../billing/firstname"/><xsl:value-of select="$sepend" /> <!-- Using xsl:value-of select="../../billing/firstname" the "firstname" field is pulled from the object level. ../../ means to get data from the "parent" level. Then we go to the billing/ level (See "Fields available for export" popup) to get the firstname field. -->
<xsl:value-of select="$sepstart" /><xsl:value-of select="sku"/><xsl:value-of select="$sepend" /> <!-- Get the "sku" field on item level -->
<xsl:value-of select="$sepstart" /><xsl:value-of select="round(qty)"/> <!-- Get the "qty_ordered" field on item level and apply the round() function to it. --><xsl:value-of select="$sepend" />

<xsl:text>&#xD;&#xA;</xsl:text> <!-- Output a line break. -->
</xsl:for-each> <!-- End item foreach -->
</xsl:for-each> <!-- End object foreach -->

</xsl:template>
</xsl:stylesheet>
</file>
</files>


This template would create one output file, called orders_day_month_year.csv. It would contain one header row (defining the fields, it's optional, just so you can view column names in Excel for example), and would then loop through each <object>s <item> in the XML processed, creating one line in the CSV file for each item ordered.

XSLT Functions
An introduction on XSL as well as functions, variables, etc. can be found here: https://www.w3schools.com/xml/xsl_intro.asp

Custom XSLT Functions
You can either create a custom PHP XSL Helper (see below in PHP section) or you can define "templates" that can be called with parameters: https://www.w3schools.com/xml/ref_xsl_el_with-param.asp

XSLT 1.0 / XSLT 2.0
The extension uses XSLT 1.0. The XSLT 2.0 standard as well as its more advanced functions are not supported by PHP out of the box unfortunately.

Sample XSL Templates

Sample XSL Templates can be downloaded here: Sample Templates

Use them as references to learn XSL and to build your own XSL Template.

Calling PHP functions in XSL Templates

ATTENTION: When using module version 2.4.4 or newer: The ability to execute PHP functions via XSL has been restricted. PHP functions must be whitelisted now, and only certain functions are allowed out of the box. If you want to whitelist your own functions, you can do so via the etc/xtento/orderexport_settings.xml file - create a setting entry with the name "custom_allowed_php_functions" (IMPORTANT, note the custom_ prefix) and add your custom PHP functions comma-separated there; either directly in our module folder or create your own etc/xtento/orderexport_settings.xml file in a custom module. If you don't do this, php:functionString will simply return an empty string for not-whitelisted functions.

A sample XSL helper module to get you kickstarted can be downloaded here.

It is possible to call PHP functions in XSL Templates.

Important: In order to be able to call PHP functions in the XSL Template, please make sure your <xsl:stylesheet> tag in the XSL Template looks like this: <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:php="http://php.net/xsl">

You can now call PHP functions in your XSL Template.

Sample call for PHP function "FUNCTIONNAME" with two parameters:

<xsl:value-of select="php:functionString('FUNCTIONNAME', 'parameter1', 'parameter2')"/>

Examples:

<xsl:value-of select="php:functionString('number_format', price, 2, '.', '')"/> <!-- This would call the PHP number_format function on the price field --> <xsl:value-of select="php:functionString('substr', billing/firstname, -10)"/> <!-- This would call the PHP substr function on the billing/firstname field -->

An often used function is date, to format the date the order was placed for example (and in the correct store time zone).

<xsl:value-of select="php:functionString('date', 'dmY H:i:s', created_at_timestamp)"/>

Example to get the last sub-category assigned to a product (item) that is exported: <xsl:value-of select="php:functionString('str_replace','|',' ',php:functionString('substr',product_attributes/category_names,php:functionString('strrpos',product_attributes/category_names,'|', (php:functionString('strrpos',product_attributes/category_names,'|') - string-length(product_attributes/category_names) - 1)),string-length(product_attributes/category_names)-1))" />

Setting up your own PHP functions and calling them from XSL is possible as well. You will need to put your PHP function into a static class, as a static function (see our sample). You can find a sample class and XSL sample code how to call it here: app\code\Xtento\OrderExport\Helper\Xsl.php

In that class, there is also an example how to pull from the store configuration:

<xsl:value-of select="php:functionString('Xtento\OrderExport\Helper\Xsl::getStoreConfig', 'path/to/whatever', 'scopeType(for example: stores)', 'scopeCode/storeId')"/>

(This calls the helper function in the Xsl class, which in turn retrieves the store config value)

As you cannot use Dependency Injection in static functions, use this to get an instance of the object manager and get whatever classes you need:

$objectManager = \Magento\Framework\App\ObjectManager::getInstance();
$product = $objectManager->create('Magento\Catalog\Model\Product')->load($id);

Static values

It is possible to output text (for example static values) like this in the XSL Template:

<xsl:text>Whatever you want to output goes here.</xsl:text>

This will be output as-is in the output file.

Mapping fields (if then, if then, ... else)

It is also possible to map fields and output other values based on the results of the "if" conditions.

A sample mapping would look like this: <xsl:choose>
<xsl:when test="shipping_method='abc'"><xsl:text>output this text</xsl:text></xsl:when>
<xsl:when test="shipping_method='xyz'"><xsl:text>output something else</xsl:text></xsl:when>
<xsl:otherwise><xsl:text>nothing matches, output this</xsl:text></xsl:otherwise>
</xsl:choose>

This evaluates the value of the shipping_method field. If it's abc or xyz, it matches one of the xsl:when lines. If it doesn't match any condition, the xsl:otherwise value is output.

Conditional statements (if then ...)

For "if then, if then, ... else" conditions have a look at "Mapping fields" above.

A simple if then condition can be set up like this: <xsl:if test="shipping_method='abc'"><xsl:text>output this text if shipping_method is exactly abc</xsl:text></xsl:if>

A condition to output a value if the shipping cost is greater or equals 10 and lower or equals 20: <xsl:if test="shipping_amount &gt;= 10 and shipping_amount &lt;= 20"><xsl:text>the shipping cost is between 10 and 20</xsl:text></xsl:if>

Sample for a negotiated condition: <xsl:if test="not(shipping_method='abc')"><xsl:text>output this text if shipping_method is NOT abc</xsl:text></xsl:if>

Arithmetic operations / Calculations

It is possible to calculate values based on fields in the XSL Template. The following arithmetic operations can be used:

Two line items get output for one item ordered

This is not a bug. Magento saves both the configurable as well as the simple product in the database, so both get output. The "configured" price gets saved with the configurable product only, so the simple product line will say "price 0".

First of all you would set up a product filter which does not show configurable products. To do so, go to the "Filters / Actions" tab and hide configurable products there using the "Hidden Product Types" option. (Item filter feature)

To grab the right price (or any other field from the parent product, the configurable product), instead of your value-of select="price" field:

<xsl:value-of select="$sepstart" /><xsl:value-of select="price"/><xsl:value-of select="$sepend" />

Use this:

<xsl:choose>
<xsl:when test="string-length(parent_item_id/text())!=0">
<xsl:value-of select="$sepstart" /><xsl:value-of select="parent_item/price"/><xsl:value-of select="$sepend" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$sepstart" /><xsl:value-of select="price"/><xsl:value-of select="$sepend" />
</xsl:otherwise>
</xsl:choose>

This works for any field, you can retrieve any field from the parent item using the parent_item node.

Using the parameter "indent" to not to get the XML output format exported on one line

Simply add the "indent="yes" to the <xsl:output> tag like this: <xsl:output method="xml" encoding="utf-8" indent="yes"/>

Sorting the elements in the output

Using xsl:sort you can sort the elements in the output. This sample code would sort the order items by price, from the highest price to the lowest price using the parameter order="descending".

<xsl:for-each select="objects/object">
<xsl:for-each select="items/item">
<xsl:sort select="price" order="descending"/>
<xsl:value-of select="$sepstart" /><xsl:value-of select="price" /><xsl:value-of select="$sepend" />
</xsl:for-each>
</xsl:for-each>


Replacing characters in all fields

You can define certain characters that get replaced in ANY field. This can be important for example if you want to set up a CSV format, where no comma or semi-colon may show up in field values.

Setting this up is easy. In your XSL Template, modify your <file> node like this: <file filename="file_name.csv" search=",;" replace="--">

This would replace both commas as well as semi-colons with dashes. The first parameter search defines which characters you want to replace. The second parameter replace defines with which character these characters get replaced.

Outputting custom date/time formats

If you want to output the order date in a custom date format, do it like this:

<xsl:value-of select="php:functionString('date', 'Y-m-d', created_at_timestamp)"/>

You can pass any parameters of the date variable there.

Exporting custom options

You can access each custom option separately using the name of the custom option:

<xsl:value-of select="custom_options/custom_option[name='Exact name of the custom option goes here']/value"/>

Concatenating two or more fields

Need to combine two fields such as the first and lastname into one field? That's possible as well:

<xsl:value-of select="concat(field1, ' ', field2)"/>

This would combine field1 and field2 separated by a space.

Example for shipping first/lastname (when exporting one row per item ordered):

<xsl:value-of select="concat(../../shipping/firstname, ' ', ../../shipping/lastname)"/>

Example for shipping first/lastname (when exporting one row per *order*, and not per item):

<xsl:value-of select="concat(shipping/firstname, ' ', shipping/lastname)"/>

Date calculations

It is also possible to add 1 day to the order date for example.

<xsl:value-of select="php:functionString('date', 'Y-m-d', php:functionString('strtotime', concat(php:functionString('date', 'Y-m-d', created_at_timestamp), ' +1 day')))"/>

Creating CSV formats using XSL

Please refer to the sample XSL Templates.

Creating TAB delimited formats using XSL

Use a CSV XSL Template to start. You only have to replace the delimiter in the header line and adjust the sepstart and sepend variables.

The sepstart and sepend variables located at the top of the template need be set like this: (&#09; is the tab character)

<xsl:variable name="sepstart" select="''"/>
<xsl:variable name="sepend" select="'&#09;'"/>

Also if this was your header line: <xsl:text>Date,Order #,Purchased From (Store),Billing First Name</xsl:text><xsl:text>&#xD;&#xA;</xsl:text>

You would simply replace all the commas with &#09; as well so it would look like this:

<xsl:text>Date&#09;Order #&#09;Purchased From (Store)&#09;Billing First Name</xsl:text><xsl:text>&#xD;&#xA;</xsl:text>

Creating XML formats using XSL

Please refer to the sample XSL Templates for some examples on how to create XML formats.

More Details:
Outputting data into the "attribute" of a XML node is possible too. If you need this:

<product sku="test123"><name>TEST</name></product>

You'd write it like this in XSL:

<product>
<xsl:attribute name="sku">
<xsl:value-of select="sku" />
</xsl:attribute>
<xsl:value-of select="name" />
</product>

Creating ASCII formats using XSL

Creating fixed-length formats is possible as well using XSL.

Using the PHP sprintf function which can be called from the XSL Template, fixed length fields can be set up. Example:

<xsl:value-of select="php:functionString('sprintf', '%-10.10s', 'ABC')"/> <xsl:value-of select="php:functionString('sprintf', '%-7.7s', ../../increment_id)"/>

This would output two fields, the first being 10 characters long (and cut off if longer than 10 chars) and expanded with spaces, and the second being 7 characters long containing the increment_id cut off after 7 characters, and if shorter, expanded with spaces.

If you need to export multibyte characters (Umlauts like ä/ö/etc.) and want to use sprintf, you will need to use the custom mb_sprintf function to format fields:

<xsl:value-of select="php:functionString('Xtento\OrderExport\Helper\Xsl::mb_sprintf', '%-7.7s', billing/firstname)"/>

Exporting the invoice/packingslip PDF

It is possible to export the invoice/packingslip PDF using the extension. Please note you can only export the invoice PDF if the invoice has been created for the order, and the packingslip PDF only if the shipment has been created for the order.

In your XSL Template, you would add:

<file filename="invoices_%realorderid%.pdf" type="invoice_pdf"></file>

Before the last line of the XSL Template: </files>

Possible values for "type" are "invoice_pdf" and "packingslip_pdf".

When using our PDF Customizer extension, use the following "type" values: xtento_order, xtento_invoice, xtento_shipment, xtento_creditmemo. To specify a certain template ID, append it like this: xtento_order_2

Exporting files uploaded by customers using the XTENTO Custom Attributes extension

(Introduced in Xtento_OrderExport version 2.10.8)

If you are using our "Order & Customer Attributes" extension to add new fields to the order entity, and have your customers upload files in the checkout (for example) for orders, you can export these files using the order export extension to your destinations such as email recipients or FTP servers.

To do so, in your XSL Template, simply add this before the closing </files> tag:

<file filename="from_file" type="xtentocustomattribute_order_ATTRIBUTECODE"></file>

The only part you need to adjust is the ATTRIBUTECODE, which is the attribute code you set up for your file attribute. If your file upload attribute has the attribute code "testfile", you'd use: xtentocustomattribute_order_testfile

Recursive template with dynamic columns

A recursive template sample file where the columns are added dynamically, a column per ordered item, can be downloaded here: Recursive Template

Adding an attribute to an XML output format

<Item>
<xsl:attribute name="ItemSKU">
<xsl:value-of select="sku" />
</xsl:attribute>
<Name>
<xsl:value-of select="name" />
</Name>
</Item>


The output would be something like:

<Item ItemSKU="skuABC">
<Name>itemName123</Name>
</Item>

Testing your template

When editing your profile and working on your XSL Template, you can easily test the template you created by going to Output Format > XSL Template . Just paste your XSL Template and press the Test XSL Template button. Errors will be displayed, if the template is well-formed, the output file(s) created will be displayed. You can also use the editor there to develop your XSL template.

Don't want to create the XSL Template yourself? Have us create the XSL Template for you - we will take care of the output format creation for you. Check out our XSL Template Creation Service.

Adding own export classes / Rewriting existing export classes

You can create own export classes and register them in the export module. Or, rewrite existing export classes of our module.

In a custom module, create the following file:

etc\xtento\orderexport_data.xml

(See \app\code\Xtento\OrderExport\etc\xtento\orderexport_data.xml for format)

Then, for example, override our "items" export class:

<export id="items" class="\Xtento\OrderExport\Model\Export\Data\Shared\Items"/>

Just specify it in your orderexport_data.xml file like this:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Xtento_OrderExport:etc/xtento/export_data.xsd">
<data>
<export id="items" class="\My\Module\Model\Whatever\Items"/>
</data>
</config>

Then copy the class \Xtento\OrderExport\Model\Export\Data\Shared\Items into your custom class or extend it and add the custom fields you require using Magento models / database queries.

You can now customize the Items.php output in your own, copied class and still have the extension upgradeable.

The same concept works to add NEW data to the export - just choose an unique value for the "id" attribute and add your own class to the export.

Special situation: The "Items" class
For the items class unfortunately no "extending" is possible, unless you create a plugin for the Items class and simply do an around plugin which manipulates $this->writeArray (but may need Reflection to do so)

So you can either override the Items class, or use an around plugin. A third alternative would be to just create a new export class, output data into "items2/item" in the XML structure, and then in the XSL Template, when outputting items, doing something like this:

<xsl:for-each select="items/item"> <!-- this is standard -->
  <xsl:value-of select="sku"/> <!-- some field from normal Items class -->
  <xsl:variable name="entity_id"><xsl:value-of select="item_id"/></xsl:variable> <!-- This is required to match items, so in your items2/item node output the item_id as a field too -->
  <xsl:value-of select="../../items2/item[item_id=$entity_id]/someField"/><!-- Get a field from your items2/item node -->
</xsl:for-each>

4) Filters / Actions

Filters

Filters set up will be applied to both manual as well as automatic exports.

Order/Invoice/Shipment/Credit Memo filters

• Export only new objects: If set to "Yes", only new objects will be exported. This means that if for example order# 123 has been exported already exported by this profile, it won't ever be exported again by this profile.
  
• Store Views: Only selected store views will be exported.
  
• Date From: Set the earliest date the export should export from. Date set includes the day X (set).
  
• Date To: Set the latest date the export should export to. Date set includes day X (set).
  
• Created during the last X days: Export only objects created during the last X days (including day X). Only enter numbers here, nothing else. Leave empty if no "created during the last X days" filter should be applied.
  
• Status: Only exports objects where (for example order) status is X.
  

Item filters

Hidden Product Types: The selected product types won't be exported and won't show up in the output format for this profile. You can still fetch information from the parent product in XSL using the parent_item/ node.

"Export only if the following conditions are met" filter

It is possible to set up almost any filter in addition to the above filter using the "Export only if the following conditions are met" section. You can set up complex filters there, for example only export if an item was found where the price is greater than 0 and if the billing country is US.

Please note this filters only the objects to export. If you have a filter that matches "if an item is found where manufacturer = X", and an order is exported where two items are contained, one where manufacturer = X and one where manufacturer = Y, still the whole order and both items will export. If you want to avoid this, you have to set up a filter both at "Filters / Actions" as well as in the XSL Template using an xsl:if condition like this:

<xsl:if test="product_attributes/manufacturer='X'">...whole value-of select fields go here...</xsl:if> <!-- This will only output items where the product attribute manufacturer is "X". -->

Actions

There are certain actions that can be applied to orders after exporting:

• Change order status after export: If enabled, the selected order status will be set for all exported orders.
• Add comment: Add comment to order status history after exporting.
• Invoice order after exporting: After exporting, the order would be invoiced and the payment would be captured.
• Notify customer about invoice: If "Invoice order after exporting" is enabled, the customer would receive an email after the invoice has been created.
• Ship order after exporting: After exporting, the order would be shipped.
• Notify customer about shipment: If "Ship order after exporting" is enabled, the customer would receive an email after the shipment has been created.
• Cancel order: Cancel order after exporting.

5) Manual Export

These settings only apply to manual exports.

Manual export enabled: Can this profile be used for manual exports from grid/Manual Export screen? Save files on destinations for manual exports: Do you want to save exported files on the configured export destinations when exporting manually? Or do you just want them to be saved on the configured export destinations for automatic exports? This is especially useful if you want to use the manual export without sending export files to the configured FTP/HTTP/whatever destinations.

6) Automatic Export

Any filters set in the "Filters / Actions" section will be applied when exporting automatically. It is possible to set up cronjob exports as well as event-based exports for one profile.

Cronjob Export

If you want to automate exports, you can set up cronjobs for profiles which execute the export for this profile at certain times automatically. First of all, make sure to set up your Magento cronjob as explained here. You can easily control the cronjob status right from the export module, by going to "Cronjob Export" when editing a profile. The Cronjob Status field will contain information about the status of the cronjob and whether any action is required or not.

To enable cronjob exports for this profile, simply set Enable Cronjob Export to "Yes". Select the Export Frequency of how often you want the export 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 export frequency" from the Export Frequency dropdown, and enter one or more cron expressions separated by a semi-colon (;) in the Custom Export 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 exports will only be made if the profiles status (under General Configuration) is "Enabled".

Event-based Export

Magento dispatches events to Magento modules when certain things happen. For example, Magento would dispatch an event after the order has been saved, or placed, or after the invoice has been created. The export module is able to "listen" and wait for these events, and once they've been called, to export data.

In the Automatic Export tab of a profile you can select the events the profile should be exporting upon. Simply select the checkboxes of events you want to export upon and save the profile. Whenever one of these events get called, the profile will export just this one object that the event refers to: For example the invoice that was created, or the order that has been created. In addition, any filters set up at Filters / Actions in the profile will be taken into account.

The following events are available for exporting out of the box:

Important: Automated exports will only be made if the profiles status (under General Configuration) is "Enabled". If possible, please use the cronjob exports as sometimes the Magento event triggers too fast, even before all the data has been properly saved in the database. This can lead to missing fields in the exports.

7) Profile Execution Log

The profile execution log shows any exports made using this profile, be it manual or automatic. It is also possible to download the exported files, however, only if Save local copies of exports is set to "Yes" under General Configuration.

8) Profile Export History

This section shows which objects (orders, invoices, shipments, credit memos) were exported by this profile and when. If the Export only new objects filter is set to "Yes", you should only see every object once there. If you want to re-export an object that has been already exported and is not exported because Export only new objects is set to "Yes", you can remove the entry from the export history grid by selecting Delete Entry.

Export Destinations

Export Destinations

Editing an export destination

Export destinations are the actual "destinations" where exported files will be sent to/saved on. If your only goal is to manually export and download orders from the Magento backend, you won't need to set up any export destinations. If you have to send exported files to remote FTP servers or certain local directories on the Magento servers, you will have to set up export destinations.

The module supports an unlimited amount of different export destinations. The following destination types are supported:

Setting up Export Destinations

To set up export destinations, go to Sales > Sales Export > Export Destinations. You can modify existing destinations there or add new destinations.

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

Destination Types

Local Directory

This destination type will simply save the exported file in a local directory on the Magento server.

If you begin the path with a dot in front of it, for example ./var/export/ the path will be relative to the Magento root directory. This means the file would be saved in the /var/export/ 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/export/

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

FTP Server

The FTP destination type supports uploading files to 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 export destination.

SFTP Server

The SFTP (Secure File Transfer Protocol) destination type is identical with the FTP destination type, except that it sends files to a SFTP server. This destination 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 export data to a HTTP server, please follow the following steps:

1. Go into the app/code/Xtento/OrderExport/Model/Destination/ 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 destination upon exporting then.

Example: If you enter server1 in the function name field below, a method called server1($fileArray) 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 export destination, separated by the function name that is called. The function you add then gets called whenever this destination is executed by an export profile.

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

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.

E-Mail Recipient(s)

This destination type simply sends an email to the configured recipients, with the exported files attached.

The following configuration must be entered for this destination type:

Potential issues: No emails are sent

1. Please make sure whether normal Magento emails are sent or not. If you don't receive an order confirmation from Magento either, the email function is probably broken and this is a problem not related to the extension
2. Please try to send the export emails to your email address instead to test if you receive them or if it's a problem with the intended recipient of the email.

Specifying "from" name

Out of the box, simply the email address you enter in the "E-Mail From Address" field will be set as the "from" "email" AND "name".

If you want to specify a "real" email sender name ("Some Store" <[email protected]>") you would need to customize the extension. In the class Xtento\OrderExport\Model\Destination\Email, there are two parameters in the "setFrom" call where you can specify this.

HTML in email body

If you want to use HTML in the email body, you can do so, but please remove any line breaks (\n) from your email body, as that can otherwise can cause issues with the HTML. Email bodies are normally in text plain so our extension converts new lines to BR tags, so please remove all new lines if using HTML in the email body.

Webservice/API

To export data to a webservice, please follow the following steps:

1. Go into the app/code/Xtento/OrderExport/Model/Destination/ 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 destination upon exporting then.

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

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

public function yourFunctionName($fileArray) { ... }

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 exporting. The saveFiles($fileArray) function would be called in your class. If your class was called \Xtento\OrderExport\Model\Destination\Myclass then the identifer to enter here would be \Xtento\OrderExport\Model\Destination\Myclass

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

In case you used composer to install the extension, there is no app/code/... folder to place your file. Instead, use composer autoloading feature to add your custom class: https://alanstorm.com/replicating-code-pool-overrides-in-magento-2/

Logging errors in the profile log for custom destinations

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('orderexport_log');
$logEntry->setResult(\Xtento\OrderExport\Model\Log::RESULT_WARNING);
$logEntry->addResultMessage(__('Destination "%1" (ID: %2): %3', $this->getDestination()->getName(), $this->getDestination()->getId(), 'Something went wrong'));

Enabling Export Destinations in Profiles

To associate created export destinations to export profiles, open an export profile and go to the Export Destinations tab and select the export destinations where the file should be sent to by selecting the checkbox in front of it. Then save the profile.

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

Using the extension

The following functions can found at Sales > Sales Export.

Manual Export

Manual Export Screen

Exporting objects manually is easy. After configuring the extension and creating profiles, just go to Sales > Sales Export > Manual Export.

First of all, select the profile you want to export. You can select from order export profiles, invoice export profiles, shipment export profiles and credit memo export profiles, depending on which profiles you set up.

There are several different filters available now to narrow down the exported objects.

Please keep in mind that any filters you set up in the profile will also be taken into account when exporting manually.

If you're ready to export, just press the Export button. You will be presented with a file download dialogue and a success message if the export completed successfully.

Automatic Export

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

Execution Log

Execution Log

The profile execution log shows any exports made using all profiles, be it manual or automatic. It is also possible to download any exported files, however, only if Save local copies of exports is set to "Yes" under General Configuration of the profile the export was made with.

Export History

Export History

This section shows which objects (orders, invoices, shipments, credit memos) were exported by which profile and when. If the Export only new objects profile filter is set to "Yes", you should only see every object once there for each profile. If you want to re-export an object that has been already exported and is not exported because Export only new objects is set to "Yes", you can remove the entry from the export history grid by selecting Delete Entry.

Tools

Import/Export Screen

Export Settings

The extension comes with functionality to export certain module configuration. All or certain export profiles as well as export destinations can be selected for exporting at Sales > Sales Export > Tools, 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 you 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 export profiles or export destinations using the Export Settings functionality, you can import it here again.

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

Example Setups - What's possible with this extension?

What kind of exports can be set up using this extension? The possibilities are almost endless.

The extension supports an unlimited number of export profiles, which means an unlimited number of different, completely customizable, output formats can be set up. The export profiles can be exported at different times using cron jobs automatically or after certain events have happened in Magento. The exported files can be sent to an unlimited number of remote/local destinations, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

There is no export extension that's more flexible.

ERP/CRM Export

Export orders, invoice and credit memos after they have been created automatically, manually, or on a cron schedule. Any output format based on text, i.e. CSV/XML/ASCII/..., can be created using a custom XSL Template. Send them to almost any destination type, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Warehouse Export

Export your orders after they have been placed or paid to your warehouse. Any output format based on text, i.e. CSV/XML/ASCII/..., can be created using a custom XSL Template. Send them to almost any destination type, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Shipping Data Export

Make your orders available for a shipping software. Any output format based on text, i.e. CSV/XML/ASCII/..., can be created using a custom XSL Template. Send them to almost any destination type, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Reporting Export

Export orders, invoice, shipments and credit memos after they have been created automatically, manually, or on a cron schedule. Any output format based on text, i.e. CSV/XML/ASCII/..., can be created using a custom XSL Template. Send them to almost any destination type, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Accounting Export

Export orders, invoice, shipments and credit memos after they have been created automatically, manually, or on a cron schedule. Any output format based on text, i.e. CSV/XML/ASCII/..., can be created using a custom XSL Template. Send them to almost any destination type, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Dropshipping

Export your orders after they have been placed or paid to your dropshippers. Any output format based on text, i.e. CSV/XML/ASCII/..., can be created using a custom XSL Template. Send them to almost any destination type, including FTP Servers, SFTP Servers, E-Mail Recipients, HTTP Servers and Webservices/APIs.

Also, each profile can be set up to include items where the "vendor" is "X". You would set up one export profile for each vendor so they only get the orders/items they should get.

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 Order Export Module

Troubleshooting

Or: How to fix the most common issues.

FTP Upload 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 export destination.

New orders don't export while "Export only new orders" is enabled

The module internally keeps track of exported items (orders/invoices/shipments/credit memos) by saving them in the so called Export History. You can view it at Sales > Sales Export > Export History. It remembers all the entity_ids (internal, ever incrementing-ids of orders/invoices/...) exported in this table, and whenever you run a new export, if the "Export only new ..." function is enabled, it checks if the entity_id you're trying to export has been exported already. If it hasn't been exported yet, it exports the order and writes the entity_id into the Export History. If it has been exported before it won't export it again.

Now what often happens is that test orders are deleted in Magento once you go live, and the entity_id is reset to 1 again, which makes sense. But if you remember, you also exported (some) test orders using our module, for example the entity_ids 101, 102, and 103. So now when the entity_id on your live site reaches 101, our module thinks these orders *have* been exported already, and that is why they don't want to export again now, now that you're live.

To fix this, go to Sales > Sales Export > Export History and remove the entries of old/historic exports, so these orders can export again.

Remember: Whenever you delete orders/invoices/shipments/credit memos, and the entity_id is reset (often when deleting test orders for example), be sure to wipe out the modules export history at Sales > Sales Export > Export History as well.

Cannot save profile / XSL Template / Test XSL Template

If you get a "Forbidden" page when trying to save the export profile, or if the "Test XSL Template" function fails with an "AJAX request failed" message, some "server security module" is blocking the execution as it suspects the XSL template to be a "virus" or bad code. That's not the case of course.

We are aware of a couple known possible reasons for this:

• The following extension is installed: MageFirewall Security - Remove it or make sure it doesn't interfere with our extension
• A firewall/IDS (Intrusion Detection System) is installed on your server (by your hoster) that blocks the request. Contact your hoster/server admin and ask them.
• On your server, a "security module" like modsecurity blocks the execution. Contact your hoster/server admin and ask them.
• On your server, the "Atomic ModSecurity" intrusion detection system is installed. The following rules may be blocking: 360147, 340159, 360148 Contact your hoster/server admin and ask them to allow them.
• Using Cloudflare? Add a firewall rule in Cloudflare that allows template testing: URI Path contains /profile/validateXslTemplate

Error "Unable to unserialize value." when using module or opening profile

You are using an outdated module version and upgraded to Magento 2.2 or newer. A change in Magento 2.2 requires an update of our module, please update this module to the latest version.

Fatal error: Uncaught Error: Call to undefined method Magento\Email\Model\Transport\Interceptor::send()

Please install the latest module version.

Line 123 (Error Code: 23): EntityRef: expecting ';'

If you have search=";" in the <file> tag of your XSL Template, remove that and instead run the str_replace PHP function on each of the fields that could contain a semicolon. Only required for semicolon-separated formats. This will fix the above error.

M2 EE/Cloud - Split databases

We did investigate this topic a while back and came to the conclusion that the "Export only new orders" feature we have in our extension won't work with split DBs, as it uses a table called xtento_orderexport_profile_history to join already exported orders and that won't work with split DBs as orders are in a different DB, so no join is possible. However, we didn't see any other issues, so it should work with split DBs (except as said "Export only new..."). You can use the order status or similar fields to realize filters to mimic the "Export only new" feature and make sure an order is only exported once.

Excel / CSV File / UTF-8 / Charset not recognized

Magento stores all data encoded in the UTF-8 charset. The default charset when exporting your data using this extension is UTF-8 thus. Now, if you want to open the exported CSV file in Excel, Excel won't recognize that charset by default, as Excel expects your local charset. To force excel into recognizing UTF-8, be sure to add addUtf8Bom="1" to the <file tag of your XSL Template. Check out the "Variables in the <file> node" section above for more details.

No Destination selected (error in the "Profile Execution Log") tab

This error shows up when you do not assign an export destination to your export profile. To do so, please go to "Sales > Sales Export > Export Destination" and create a destination. Back in the export profile, in the "Export Destinations" tab you can assign the destination to the profile by clicking the checkbox on the left side of the destination. Then save the profile afterwards and run the export again.

Error: Warning: Illegal offset type in isset or empty in [...]/Model/StoreRepository.php on line 65

Seeing this error when running exports? As of October 2019, there seems to be a bug in the Mageworx Custom Options extension which causes this. They are aware of this problem, please update your extension.

Error message: Warning: number_format() expects parameter 1 to be float, string given

This can also happen for other functions. With a recent update, XSL errors are now shown, to avoid unexpected behavior later on due to bad code in XSL.

If you have a call to php:functionString in your XSL Template, and the field you are trying to pass to the function as a parameter does not exist, such as special_price, PHP will throw a warning, like the one above.

Let's say you have this code:

<xsl:value-of select="php:functionString('number_format', special_price, 2, '.', '')"/>

You could add a xsl:if condition and check if the field exists, but this bloats up the XSL Template. An easier solution is to simply force the field to be a float value using the sum() function:

<xsl:value-of select="php:functionString('number_format', sum(special_price), 2, '.', '')"/>

The files in the emails are attached as "noname" when using an email export destination

This is most likely an issue with your SMTP / email setup. The mail server is dropping the file names for some reason. This needs to be fixed with your mail server admins or with the developer of your SMTP module.

Blank page with just "failed" after running manual export

Run the export again but do NOT check the "Serve files to browser" checkbox. Then you should see the actual error message.

Email destinations: Line breaks in HTML or random exclamation marks (!) appearing

1) Make sure you are running the latest module version.
2) The problem with rando exclamation marks (!) appearing in emails sent using our module happens when you have your whole HTML email in the "Body" field in one line, without any line breaks. Make sure not to have more than 1000 characters or so per line in HTML emails. In your email destination, format your HTML simply using a tool like this https://htmlformatter.com/ so it's evenly distributed. Otherwise mail servers will break lines after 1000 characters roughly.

stripos(): Passing null to parameter ... in .../module-price-permissions/Observer/AdminhtmlBlockHtmlBeforeObserver.php

This is actually a Magento core bug, see here: https://github.com/magento/magento2/issues/35542

To fix this, patch the AdminhtmlBlockHtmlBeforeObserver class as recommended in above link.

The strftime() PHP Function has been deprecated in PHP 8.1

Please use the date() function instead. For example: <xsl:value-of select="php:functionString('date','d.m.Y H:i:s',created_at_timestamp)" /> The function parameters can be found here: https://www.php.net/manual/en/function.date.php