1 1. Introduction
2 2. Installation
- 2.1 2.1. With composer
- 2.2 2.2. Enable cron (must be done for async operations)
3 3. Configuration
- 3.1 3.1. General
- 3.2 3.2. API
- 3.3 3.3. FTP
- 3.4 3.4. Stock Import
- 3.5 3.5. Delivery Promise
4 4. How to extend the connector
5 5. Troubleshoot

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 : onestock/onestock-magento-connector - Packagist

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.

You can also change the folder with an absolute path in Store Configuration. It is required if magento runs in folders managed by symlinks toward release.

/var/www/vhosts/www/.../curent/var/importexport/onestock/...

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 extend the connector

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 Create a module | Adobe Commerce 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

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

4.4. Trigger a stock import (full or delta)

Using n98-magerun you can trigger the jobs with the following commands:

5. Troubleshoot

5.1. OneStock does not receive any order from magento

The module uses the "message queue framework" an high level interface of message queue which does not require RabbitMQ.

In app/etc/env.php the instruction bloc cron_consumers_runner is not exclusive to Adobe Commerce Cloud. If configured, cron:run will launch automatically the command queue:consumers:start without the need to launch it manually. Most magento instance rely on cron:run (in particular Adobe Commerce Cloud launch it by defaut) so cron_consumers_runner is the easy option. Nevertheless, if you manage cron in an other manner, you must launch the queue:consumers:start demon yourself in order to consume magento messages.

If rabbitmq is not configured, messages will be stored in mysql and will be visible in a table queue_message. Their status will be stored in queue_message_status. A figure stands for the status (MESSAGE_STATUS_NEW = 2, MESSAGE_STATUS_IN_PROGRESS = 3, MESSAGE_STATUS_COMPLETE= 4). If you are rabbitmq instead, you can monitor if the messages are being created and consumed in the RabbitMQ management plugin.

When an order is invoiced (placed depending on your configuration), a message_queue async.smile.onestock.api.orderexportinterface.export.post will be created. Messages are also added to a specific log file var/log/onestock.log to understand what is going on.

5.2. Magento does not create a shipment even if OneStock calls the webhook. We cannot create an empty shipment

If enabled, a specific log file var/log/onestock.log to understand what is going on will log the onestock order. The onestock order must reference a parcel (and parcel_id), each element of the line_item_groups must be in the state fulfilled or claimed.

5.3. Magento does not import the unified stock

Unified stock file must be a CSV with the first line dedicated to CSV title item_id and quantity. This CSV must be coma separated. Item_id column is the equivalent of sku in magento.

By default this csv file must be stored in magento filesystem in the relative var folder with a valid filename pattern, for example var/importexport/onestock/in/unified_stock/stock_unified_sc0_full_202309111111.csv

Full stock import file and differencial stock import file are to be stored in the same folder, only file pattern changes.