1. Introduction
The OneStock magento connector is an open source connector. It has been developped in partnership with Smile.
Smile is the European leader of Open Source and also a four-times Europe Partner of the the Year (2010-2014), two-times Spirit of Excellence (2015-2016), Global Elite Partner (2017-now), and Regional Commercial Partner (2018) awarded by Magento.
2. Installation
2.1. With composer
The connector is available on packagist : https://packagist.org/packages/onestock/onestock-magento-connector
Installation is done with composer.
composer require onestock/onestock-magento-connector
2.2. Enable cron (must be done for async operations)
Edit your app/etc/env.php
file to add the cron_consumers_runner
vim app/etc/env.php
<?php return [ 'cron_consumers_runner' => [ 'cron_run' => true ], ...
3. Configuration
The configuration page is available on the Magento admin backoffice on Stores > Configuration
then ONESTOCK > Configuration
3.1. General
Site ID : your OneStock site ID, as provided by your OneStock contact
Sales Channel : The sales channel that will be used to create your orders in OneStock. The list of available sales channel is available in your OMC configuration page
Configuration > Sales Channels
Orchestration mapping : map all shipping methods that you will use in Magento to a ruleset chaining id in OneStock. This allows a different orchestration in OneStock depending on the shipping method selected by your clients.
3.2. API
Host API : should be either
production : https://api.onestock-retail.com
qualification : https://api-qualif.onestock-retail.com
training : https://api-training.onestock-retail.com
other : if your OneStock instance is hosted elsewhere, your project manager will inform you of the value to be used.
API User ID / API Password : your api user credentials that have been created for the project
Retry count per order : number of retries if a call to OneStock API fails (use default)
Timeout : timeout for the calls to OneStock API (use default)
API token lifetime : duration of the token lifetime (use default).
Debug mode : if true, the connector will add logs in your var/logs folder.
Order export mode : decide if you should wait for an invoice created in magento before creating an order in OneStock or if the order should be created immediately when the order is placed. If created when placed, the connector doesn’t create the order
3.3. FTP
SFTP configuration is done to manage stock imports from OneStock to Magento.
The connector has an internal CRON that will look for available stock files either locally or on a remote SFTP. It doesn’t trigger the stock export.
The FTP User must have the permissions to create files, to move files and to create folders on the ftp. The connector will create this folder if it doesn’t exist, then move the processed stock files on it. If the user doesn’t have the correct permissions, the files will not be consumed.
Import/export folder path : the root directory where the stock files are saved on your magento server.
Unified Stock : file pattern for FULL : file patterns to import for your unified full stock file. You can use an asterix for files exported from OneStock with a date.
Unified Stock : file pattern for DIFF : file patterns to import for your unified delta stock file. You can use an asterix for files exported from OneStock with a date.
Fetch file on remote FTP : if yes, it will retrieve the stock file from the remote FTP configured bellow
Remote FTP Username
Remote FTP Password
Remote FTP Hostname or IP-Address
Remote FTP Custom Path : root folder under which the stocks files will be stored on the FTP
Remote cleanup file after import :
Do nothing : will do nothing
Remove : will remove the file from the SFTP
Archive : will move the file to an archive folder on the same directory as the custom path.
3.4. Stock Import
Use inventory management tables : if true, it will use the new API for inventory management. Learn more.
3.5. Delivery Promise
Enabled : if true, it will display the delivery promise on top of the magento delivery blocs
Guest postcode : default postcode to use to display the delivery promise
Guest country : default country to use to display the delivery promise
Greenest option : display a leaf icon for the greenest delivery option
4. How to ?
Even though the module onestock/onestock-magento-connector is designed to be plug and play, here is some common customisation.
4.1. Introduction
You will need to create a new module https://experienceleague.adobe.com/en/docs/commerce-learn/tutorials/backend-development/create-module since it is not recommended to modify the source code of onestock/onestock-magento-connector directly. Make sure your module depends on the Onestock module.
4.2. Add a static field during order export
The module onestock/onestock-magento-connector introduce three new fieldset that are available for you to extend. Create a new file etc/fieldset.xml in your modules and specify which field should be copied into which.
For example, to export the magento order field
increment_id
as the onestock order fieldid
, the following xml is used<?xml version="1.0"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:DataObject/etc/fieldset.xsd"> <scope id="global"> <fieldset id="onestock_order_mapping"> <field name="increment_id"> <aspect name="to_onestock_order" targetField="id"/> </field> </scope> </config>
For example, to export the magento shipping address field
prefix
as the onestock destination fieldtitle
, the following xml is used<?xml version="1.0"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:DataObject/etc/fieldset.xsd"> <scope id="global"> <fieldset id="onestock_address_mapping"> <field name="prefix"> <aspect name="to_onestock_contact" targetField="title"/> </field> </fieldset> </scope> </config>
For example, to export the magento order item field
sku
as the onestock order fielditem_id
, the following xml is used<?xml version="1.0"?> <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:DataObject/etc/fieldset.xsd"> <scope id="global"> <fieldset id="onestock_item_mapping"> <field name="sku"> <aspect name="to_onestock_item" targetField="item_id"/> </field> </fieldset> </scope> </config>
4.3. Add a computed field during order export
You can use an observer to modify what is exported. The events core_copy_fieldset_onestock_order_mapping_to_onestock_order
has been introduced for that purpose. A “source
” stand for the magento order and a “target
” that stand for the order data that will be exported to onestock, they are available when the observer is executed.
Create a new file etc/events.xml in your modules to specify a new observer class.
For example, to export a new value as the onestock order field
sign_on_collect
, the following php source code can be used<?php class SignOnCollect implements ObserverInterface { public function execute(Observer $observer): void { $order = $observer->getSource(); $target = $observer->getTarget(); $target['sign_on_collect'] = true; } }
Half a dozen observers in the module onestock/onestock-magento-connector can also be used as an example and overridden to match your specific requirement.
To export a new value as the onestock order field
delivery.endpoint_id
, the following php source code can be used<?php class ClickAndCollect implements ObserverInterface { public function execute(Observer $observer): void { $order = $observer->getSource(); $target = $observer->getTarget(); $target['delivery']['endpoint_id'] = 'TOULOUSE'; } }
4.4. Trigger a stock import (full or delta)
Using n98-magerun you can trigger the jobs with the following commands:
$di->create('Smile\Onestock\Cron\StockFull')->start(); $di->create('Smile\Onestock\Cron\StockDiff')->start();