Overview

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/"
  }
}

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"
                    ]
                }
            }
        }

{
  "item_id": "item_01",
  "endpoint_id": "shop_city_center",
  "type": "on_hand",
  "quantity":2
},
{
  "item_id": "item_55",
  "endpoint_id": "black_store",
  "type": "on_hand",
  "quantity":20
}

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 :

{
  "site_id": "MySiteID",
  "translator":
  {
    "name": "Custom_translator_name",
    "end_line": "\n",
    "headers": [
      "Data_name_1",
      "Data_name_2",
      "Data_name_3"
    ],
    "omit_headers": false,
    "separator": ",",
    "transformators": 
    {
      "out_data_name_1": "Data_name_1",
      "out_data_name_2":
      {
        "fields": ["Data_name_2", "Data_name_3"],
        "type": "sub_int"
      }
    }
  }
}

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.

{
    "site_id": "MySiteId",
    "user_id": "MyUserID",
    "request_name": "detailed",
    "ftp": {
        "filename": "my_export.csv",
        "sftp_name": "my_custom_sftp",
        "translator_id": "default_on_hand_stock_transformer"
    },
    "aggregates": {
        "*": {
            "item_filter": {
                "ids": [
                    "item_01",
                    "item_55"
                ]
            }
        }
    },
    "unification": {
        "by_endpoint": true,
        "by_stock_type": false
    }
}

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 the issue persists, kindly reach out to OneStock support for further assistance.