Tradesimple: FTP Guide

Overview

This article describes the process of sending/receiving files to/from Purchase to Pay (formerly known as Trade Simple) via FTP.

FTP is the preferred method of communicating with Purchase to Pay. The communication can be carried out using the exchange either as an FTP Client or an FTP Server.

Processing Prefixes

It is important that Purchase to Pay does not attempt to access files which are currently being processed by client software, and it is as important that clients do not attempt to access files that are still being processed by the system.

To ensure that only complete files are processed, a file prefix / renaming strategy is used. Whenever
the system is processing a file, it will give the file a prefix, usually ‘UPL’. If the client software finds any files with this prefix, then they should be ignored. The client software should also use the same strategy to ensure that the system does not access files before it has finished with them.

Please Note: The processing prefix will always be a 3-character string.

An example of this file prefix use is when files are being pushed to the FTP server. The original file should be renamed to have the prefix. This file is then uploaded and, once the upload is complete, the prefix is removed. This will ensure that the system never attempts to process a partially uploaded file.

For a list of document type prefixes please see: Tradesimple: Document Prefix List

Purchase to Pay as an FTP Server

Purchase to Pay usually acts as an FTP server, as it can passively receive and store files from clients, or the system itself until another process acts upon them. For example, a Purchase to Pay Listener for  incoming messages to the exchange - (delivery), or a client accessing the server for download of outgoing messages - (pickup).

The FTP server will provide all of the standard responses, security, and error handling inherent in this protocol.
The customer should create their own functionality for connection and interaction with the server in the standard
way. Customers are responsible for removing files published by the system to their account (pickup folder) on the
Purchase to Pay FTP server once they have downloaded them successfully. Fourth will provide domain names and
logon details for test and live accounts as necessary.

Directory Structure

The standard Purchase to Pay FTP directory structure is as follows:

More detail on each of these folders is displayed in the relevant sections below.

These folders will be created by Purchase to Pay as part of the initial set-up procedure. The folders will be protected with a username and password.

The user’s virtual root will be set to the <Member folder> above, so when the user logs on, they will be redirected to the appropriate folder.

Messages from clients should be placed into the Deliveries folder for the system to collect and process. Purchase to Pay will create a receipt file for each message collected from the deliveries folder. 

The system will place messages for download by the client in the Pickup folder.

Please Note: Once the files have been successfully downloaded from the Pickup folder, these download files must be deleted from the Pickup folder on the Purchase to Pay FTP server.

A Client Receipts folder is provided in the FTP account on Purchase to Pay. It may be preferably to create a receipt file in this folder for each file downloaded from the Pickup folder. The format and naming of this receipt file is up to personal preference.

ClientErrors

This folder is used to store client files that cannot be processed by the system due to a fatal error with the file. If files are written to this folder, then an unsuccessful receipt will also be written to the receipts folder.

Reasons for files being written to this folder are:

• Invalid file names - Files must be named with the correct prefix and therefore must be at least three
  characters in length
• Empty files - All files must contain text. Empty files cannot be processed by the system

If the file is in error for other reasons, then initial processing will be carried out, and notification will be sent to the user of the error via the chosen outbound protocol, or by the Fourth Support team.

Deliveries

The following procedure should be observed when writing files to the Purchase to Pay Deliveries folder:

• Upload each file with a name prefixed with the specified processing prefix, e.g. UPLINV00099.fil
• When the upload is complete, rename the file to its correct name, e.g. INV00099.fil

Pickup

The following procedure should be observed when reading files from the Purchase to Pay Pickup
directory:

• Do not read files that have the processing file prefix, e.g. UPLINV00099. The system will be in the process of
  writing these files to the FTP directory
• It may be preferable to read only those files that have the expected prefix, e.g. INV for Invoices

Receipt Files

Purchase to Pay will write a file to the FTP Receipts folder whenever it attempts to collect a file from the Deliveries folder. This will occur in the FTP server scenario after a member has deposited a file for collection by the system

These files will be named by the system based on the original file name and a date time stamp:

Examples

The receipt filename for the message INV00099:

The receipt filename for the message woackp02:

The file will contain brief information about the message retrieved and the success or failure of the read. The content will be dependent upon whether the file has been read successfully. A successful receipt will be in the following format:

An unsuccessful receipt can take one of two forms. The first is when the file has not been processed, and the error will need to be looked at by the Fourth Technical Support team. This file will take the following form:

The second format is written when the file has not been processed due to the uploaded file being invalid in such a
way that no further processing could be carried out. Currently, unsuccessful receipts will be written when files
are empty or have invalid names:

Purchase to Pay as an FTP Client

Purchase to Pay can act as an FTP client for the purposes of sending files to your FTP server.

FTP Push Facility

Purchase to Pay can write files automatically to a remote FTP server. This is known as an FTP push.

A typical use of this functionality might be for Purchase to Pay to push orders, as they are created, onto a Supplier’s back office system.

The following procedure should be observed when reading files from the FTP directory:

• Do not read files that have the processing file prefix, e.g. UPLINV00099. The system will be in the process of writing these files to the FTP directory
• It may be preferable to read only those files that have the expected prefix, e.g. INV for Invoices.
• The following configuration details are required by Purchase to Pay during the set-up of this functionality: