Setting up a Generic Filesystem (FTP or SFTP) Retailer Integration

Setting up a Generic Filesystem (FTP or SFTP) Retailer Integration


Gateway OMS allows orders to be created by uploading specially formatted CSV files to a FTP (insecure) or ideally an SFTP site. These are referred to within OMS as Generic Filesystem integrations. The standard CSV format is explained below but custom formats can also be used. This article will explain how to configure such integrations.

Any CSV files uploaded to a generic filesystem integration will be fetched for processing by OMS once every 30 minutes, both on the hour and half past the hour. Successfully processed CSV files get renamed with a timestamp and .complete suffix whilst unsuccessfully processed files gain a .error suffix.

CSV Format

The following table describes which columns can be included in your CSV. Some are mandatory and are denoted with an asterisk (*). An example CSV file can be downloaded from the Attachments section in the right hand column.
Column header
Description
order.external_ref*
Your own order reference
order.sale_datetime
The date and time that the order was placed. The date format must be in the form YYYY-MM-DD HH:MM:SS, i.e. "2016-01-23 15:02:00"
order.shipping_company
Company Name if used
order.shipping_address_1
Shipping Address 1
order.shipping_address_2
Shipping Address 2
order.shipping_address_3
Shipping Address 3
order.shipping_address_4
Shipping Address 4
order.shipping_address_5
Shipping Address 5
order.shipping_postcode
Shipping Postcode
order.shipping_country
Shipping Country
order.shipping_country_code
Shipping Country Code ( ISO 3166-1 alpha-2 )
order.shipping_method
Shipping Method i.e Next Day
order.shipping_carrier
Shipping Carrier i.e Royal Mail
order.billing_address_1
Billing Address 1
order.billing_address_2
Billing Address 2
order.billing_address_3
Billing Address 3
order.billing_address_4
Billing Address 4
order.billing_address_5
Billing Address 5
order.billing_postcode
Billing Postcode
order.billing_country
Billing Country
order.customer_name
Customer Name
order.customer_email
Customer Email
item.sku
Your item SKU
item.description
Brief item description
item.colour
Colour (text field - any colour)
item.size
Size (arbitrary type)
item.quantity
Quantity
item.type

Item type

Set to 1 to use item.external_url to define the orders artwork.


Set to 3 to use print on demand references from CPP

Set to 5 for textual items. This is used for items with no custom artwork but instead using the textual customisation fields textual.field_name1, textual.field_value1 etc.

item.print_on_demand_ref
The print on demand reference for the item orders obtained from CPP - Only for item type 3
item.external_url

URL to your artwork. Only for external URL items. Not restricted to any specific file format or file specification. Only used when item.type is set to 1.

item.external_thumbnail_url
URL to a thumbnail of your artwork. Only for external URL items. Not restricted to any specific file format or file specification. Only used when item.type is set to 1.
textual.field_name1
1st personalisation text field name. Only used when item.type is set to 5.
textual.field_value1
1st personalisation text field value. Only used when item.type is set to 5.
textual.field_name2
2nd personalisation text field name. Only used when item.type is set to 5.
textual.field_value2
2nd personalisation text field value. Only used when item.type is set to 5.
textual.field_nameN
nth personalisation text field name. Only used when item.type is set to 5.
textual.field_valueN
nth personalisation text field value. Only used when item.type is set to 5.

Locating the Generic Filesystem integration settings

After logging into OMS, select Companies from the Settings menu:
Generic_Filesystem_Integration-001.png

Search for the company you wish to create an integration for. You can search by the name of the company or the company reference number: 

Generic_Filesystem_Integration-002.png

When you have found the company you wish to create an integration for, hover your mouse over it and click on the details icon to edit that companies details: 

Generic_Filesystem_Integration-003.png

 

Open the integrations tab then select Generic FileSystem from the dropdown menu under Retailers :

Generic_Filesystem_Integration-004.png

Explanation of the Generic Filesystem Integration settings

The screenshot below shows the retailer integration generic filesystem settings when the FS type menu is set to SFTP . Elements marked with an asterisk(*) are not available when using the FTP FS Type mode. The purpose of each element is explained in the table below:
 

Generic_Filesystem_Integration-005.png

Number
Element name
Element description
1
Enabled
This checkbox must be ticked to activate the integration.
2
Email errors To
Email address(es) to send errors to if the integration runs into problems.
3
Skip On Error
Any CSV files containing invalid fields will be skipped if this option is enabled.
4
Convert Textual Items
If the Item Code field in the CSV is valid and this is enabled, auto create a print job from the order.
5
Data Format Strategy
Select a CSV data format. Choose CSV if using the default format.
6
FS Type
Define what type of server is being used, SFTP or FTP .
7
FS Root
Define the root directory (OPTIONAL).
8
Pull Path
Define the path to pull the CSV files from, as a sub folder of FS Root (OPTIONAL).
9
Push Path
Define the path for OMS to upload CSV order status files to (OPTIONAL).
10
Public Key *
When using the SFTP FS Type, this key needs to be copied into the ~/.ssh/authorized_keys file on the server being connected to.
11
Host
The public hostname or IP address of the server to connect to. The hostname or IP must be added to the OMS firewall.
12
Port *
22 is the default port for SFTP. Enter another value here if using a non-standard port.
13
Username
The (S)FTP user name.
14
Password
The FTP password. Not required when using SFTP.
15
Product Supplier
Enter the Product Supplier company reference ID in this column (OPTIONAL).
16
Order Destination
Enter the reference ID of the preferred dropship company in the Order Destination column (OPTIONAL).
17
Add new Supplier Map entry
Click this icon to add a new entry to the Supplier Map (OPTIONAL).

Updated Generic Filesystem Features

At KornitX we have continued to develop updates for variants and this is due to the fact we pride ourselves on constant evolution and the release of new features and enhancements every week. We have detailed each new enhancement below. If you are interested in knowing what features arrive, they will be continually updated within the "Core Platform Feature Updates" Article - CLICK HERE

Updated Support For Generic Filesystem Orders Going Into Networks
This was added on 12-04-2021
The Generic Filesystem was updated to ensure orders that flow through companies with the integration enabled can also send orders through Networks which can be setup for fulfillers who are part of a network. 

    • Related Articles

    • Notification Integration | Generic Filesystem

      Introduction This article has been created to show how to setup the Notification Integration that Kornit X has built to connect to a Generic Filesystem  Setup To setup the Generic Filesystem Notification integration, please head to your company and ...
    • Shipper Integration | Generic Label

      Introduction This article has been created to show how to setup the Shipping Integration that Kornit X has built to connect to a Generic Label. Setup To setup the Generic Label integration, please head to your company and within the advanced settings ...
    • Sales Channel Integration | Walmart Marketplace

      Introduction This article has been created to show how to setup the sales channel retailer integration Kornit X has built to connect to the Walmart Marketplace.  Setup To setup the Walmart Marketplace integration, please head to your retailer company ...
    • Product Integration | Generic API

      Introduction This article has been created to show how to setup the Product integration Kornit X has built to connect to Generic API.  Setup To setup the Generic API integration, please head to your category and within and within the advanced ...
    • Sales Channel Integration | Fruugo

      Introduction This article has been created to show how to setup the Retailer Integration that Kornit X has built to connect to Base JP.  Setup To setup the Fruugo Retailer integration, please head to your company and within the advanced settings head ...