1 Overview
2 Use Cases and Examples
3 Requirements
4 Configuration
- 4.1 Working directory
- 4.2 DIY Configuration via backoffice
- 4.3 Default translators
- 4.4 Custom Translators
5 Frequently Asked Questions

Overview

Secure file transfer protocol (SFTP) is a file transfer protocol used to exchange data between networks securely over SSH. Connecting an SFTP server to OneStock streamlines the process of managing and transferring data securely between your e-commerce platform and the OMS.

OneStock provides an easy way to connect for either internal or external SFTP.

Use Cases and Examples

Connecting SFTP to OneStock OMS can greatly enhance various operational processes. OneStock can import and export stock files for other systems, such as ERPs, sales platforms or third-party providers.

For example, if a retailer wanted to keep their stock levels in sync across multiple sales channels, they might export stock update files from their ERP to a designated directory on the SFTP server.

OneStock will check the folder and download the file.

The translator in OneStock processes the files, mapping the data fields to the appropriate inventory fields in the OMS. The inventory levels are now updated across all sales channels.

Or, if the same retailer wanted to forward stock levels from OneStock to different sales platforms they would export the data from OneStock and save that to their SFTP server, allowing the stock level information to be shared [specific command required, get?]

Requirements

You must first ensure that your external SFTP is properly configured and working before connecting it to OneStock.
If you can connect to your server using SSH, you can continue with SFTP configuration for OneStock.

Configuration

To configure an external SFTP, you need to complete the sftp key via our API calls or backoffice screens. Both options are shown below.

The following information is required:

The address of the destination server
The Public key, to access the system
A user name
The path to the working directory

Working directory

During first export. OneStock will automatically create the working directory in the root folder of the SFTP. In the working directory a folder onestock will be created. This folder is required by OneStock to handle exports correctly.

DIY Configuration via backoffice

For SFTP settings navigate to Configuration > Data Exchange. The same configuration as above is shown below in the backoffice screens.

"sftp": {
  "stock_export_sftp":
  {
    "address": "https://sftp-kti.onestock-retail.ovh",
    "public_key": "Z7bMzcsj0QEI6426VtzjNT5FvM8WX9",
    "user": "user_si",
    "working_directory": "/files/working_files/onestock/stock_export/"
  }
}

Backoffice SFTP configuration

Default translators

Our system uses translators to transform the JSON data in our database to CSV data which is ready to use on client systems.

We provide several ready to use translators : default_on_hand_stock_transformer and default_future_stock_transformer

{
            "name": "default_on_hand_stock_transformer",
            "headers": [
                "item_id",
                "endpoint_id",
                "qty"
            ],
            "omit_headers": false,
            "separator": ",",
            "qualifier": "",
            "end_line": "\n",
            "transformators": {
                "endpoint_id": "endpoint_id",
                "item_id": "item_id",
                "quantity": {
                    "type": "to_int",
                    "fields": [
                        "quantity"
                    ]
                }
            }
        }

{
            "name": "default_future_stock_transformer",
            "headers": [
                "item_id",
                "endpoint_id",
                "qty",
                "min_date",
                "max_date"
            ],
            "omit_headers": false,
            "separator": ",",
            "qualifier": "",
            "end_line": "\n",
            "transformators": {
                "endpoint_id": "endpoint_id",
                "eta_end": {
                    "type": "to_int",
                    "fields": [
                        "max_date"
                    ]
                },
                "eta_start": {
                    "type": "to_int",
                    "fields": [
                        "min_date"
                    ]
                },
                "item_id": "item_id",
                "quantity": {
                    "type": "to_int",
                    "fields": [
                        "quantity"
                    ]
                }
            }
        }

CSV given as an input data

item_id	endpoint_id	qty

item_id	endpoint_id	qty
item_01	shop_city_center	2
item_55	black_store	20

Will result in a JSON output :

Custom Translators

If you need the CSV file to be built in a specific structure you will need to create a custom translator.

Custom translators can be called via the route POST /translators where the body of the request matches the required structure of your CSV output.

Here is an example of a custom translator :

In the example above the following the custom translator objects relate to certain properties:

name - a string
separator - a single character CSV separator
qualifier - the character surrounding the fields. If the qualifier is " it should be configured using the \ escape character, so "qualifier": "\""
headers - a list of strings representing the CSV headers
omit_headers - indicates whether the file has headers
transformators - a map of keys where the final fields of the transformation and whose value is the transformation method

A transformator is either a simple string (indicating the field to be used), or an object of the form :

type - method to be used
fields - a list of transformators

If a ‘fields’ is a simple string, we use the string as a key to find a value in the CSV (or JSON). If this key is prefixed by ‘raw:’, we use the key as is.

From version 9.2 onwards, if the CSV has headers, it no longer needs to contain the same number of columns as are written in the translator's headers field. If there are more columns, they will be ignored. If there are fewer columns, there will only be fewer fields in the JSON. In addition, the CSV headers may not be in the same order as the translator headers.

Once the SFTP is configured, and the right translators for your JSON <> CSV files are ready, you can call an API route for import or export of your stock, that will be use the SFTP.

Please follow the documentation available for stock imports and exports.

GET /stock_export

Frequently Asked Questions

If you are experiencing issues with connecting to SFTP:

Ensure that the SFTP name provided in the stock export request exists and is properly configured in OneStock. You can verify this by confirming the presence of an SFTP with the specified name at SFTP configuration in OMC.
In case you opt not to include an SFTP name in the stock export request, the default SFTP will be utilized. Make sure that the default SFTP is set up correctly.
If all configurations appear to be in order but the connection still fails, manually test the connection to the SFTP address with the provided public key. If you are not able to connect, this means that the private key is not configured in the SFTP server. Please reach out your SFTP providor to ask them to validate configurations and confirl that is possible to connect with the public key.
If the issue persists, kindly reach out to OneStock support for further assistance.

A new directory has unexpectedly appeared in your working directory.

This occurrence typically arises due to one of the following reasons:

To enable SFTP exchanges, OneStock generates a "onestock" folder within the designated working directory. If you have pre-created this folder, everything is in order.

If the export request specifies a filename with a folder path, and the folder does not exist, it will be created. For instance:

A filename: "/in/unified_stock/export_123.csv will result in the following configuration from the workingDirectory\:
- Creation of the in directory
- Creation of the unified_stock directory within the in directory
- Creation of the export_123.csv file within the in/unified_stock directory

Documentation

Exchanging through SFTP