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. Install 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.

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 field 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_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 field title, 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 field item_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';
   }
}

Magento Open Source Connector - User Guide