Ask the Expert: Sales Interfaces with FnB

Is it possible to tell which version of the sales upload a customer is using – FTP or API?

Live FnB….

• Yes it is possible.
• Customers who submit sales files via the API have the ‘Epos interface’ option available as part of the system administration section within enterprise manager. This is where any configuration for the import of sales data is applied on a site by site basis. To have access to this Epos interface link ‘advanced sales import’ must be enabled in admin.

 

Fig. 1 Shows the Advanced Sales Import Option Selected

 

• Customers that submit sales via FTP have the relevant data load header & upload pathway configured on the site. This can be viewed by selecting ‘edit site’ from the home section of enterprise manager.

 

Fig. 2 Shows the Epos Interface and Upload Areas in Enterprise Manager

 

• For an organisation to submit sales via API the releavnt details need to be created and submitted to an Epos provider. This is created in FnB admin via Admin > FH API > add user.

 

 

• Once add user is selected the releavnt details need to be configured in the mandatory fields:
  • Organisation – select from the drop down list
  • User Name – usually CustomerName_EposProviderName
  • Password – must be globally unique
  • EMS Group ID – Only mandatory for people system customers
• Once created these details can be passed to the Epos provider to submit sales information appropriately.
• If a user only has access to site level it is possible to hover over the sales file and in the bottom left hand corner the file name is displayed, in the below example the sales file name is ‘BARYYYYMMDD.csv’.

FnB R9…. 

• R9 supports both web-service submitted sales and FTP submitted sales files from Epos providers. Both types of sales are loaded into the system through the API.  R9 does not treat sales submitted via the web-service or FTP differently in any way; they are simply methods of transferring sales data.
• There is currently no way to view the sales upload configuration through the application. There is currently no real need to, the set up to receive sales via the web-service is very simple (create an API user and send the details to the customer), and the set up to receive sales via FTP does require back end configuration and assistance from infrastructure currently, but once done it is in place. Application of sales rules will be developed in R9; however this is 6-12 months away. R9 allows the use of both methods for an organisation.

What is the difference between submitting an FTP sales file and submitting a file via the API?

Live FnB….

• Typically Epos providers submit .csv files via an FTP folder this is usually submitted once a day at the end of the day. These files vary in format, although typically 1 sales file is submitted per physical location per day. If a customer has both a kitchen and a bar location it is possible for Fourth to separate the sales file out further into relevant groupings based on the information submitted in the file.
• There are a large number of different data load headers that allow different sales file formats to be uploaded and read into FnB correctly dependant on the Epos provider.
• One of the most common formats is Micros 3700R4 and example of this file can be seen below.

 

Fig. 4 Shows an Example FTP Sales File – Micros 3700 R4

 

• When sales files are submitted via API the sales file will be in XML format, there is only 1 standard format for XML files unlike sales submission via FTP.

 

Fig. 5 Shows an Example FTP Sales File – Micros 3700 R4

 

FnB R9….

• The web-service Sales submission for R9 uses the standard XML format, as shown in Fig. 6 above, however it is possible to submit a sales file via FTP in a csv format, although the only format that is supported is the .csv version of the XML file (the XML file opened within excel).
• The .csv format for the XML file is shown below, this is the only FTP format that is supported in R9.

 

Fig. 6 Shows the CSV File Format for Submission of Sales via the FTP in R9

 

What is the difference between submitting an FTP sales file and submitting a web-service sales file?

• An FTP sales submission typically uses a .csv file that is sent to a folder on a daily basis.
• A web-service API sales submission is in an XML formant and can be more frequent that once a day, although we would not recommend more than once every hour.

Configuring API sales

• To configure API sales files select System admin > Epos Interface > import rules to select the appropriate site to configure the sales rule from the drop down.

 

Fig. 7 Shows the Sales Rules that can be Configured for API Sales Submission in FnB Live

 

• It is possible to configure location, revenue centre and category code rules for a sale file, this is dependent on the information contained with the sales file from the Epos vendor. Typical values for each configuration type are:
  • Location = Physical location ID i.e. Glasgow = 54
  • Revenue Centre = Till ID or Cost center i.e.  Bar/Kitchen, Food/Beverage
  • Category Code = Starters, Mains, Wine etc.
• Ensure that the ‘rules enabled’ check box is selected (top right hand corner) to ensure that these rules are activated.

Configuring FTP sales

• To configure FTP sales files select home > unit > site > edit site to access the Epos section as shown below.

 

Fig. 8 Shows the FTP Sales Configuration Pathways in FnB Live

 

• The relevant data-load header needs to be selected from the drop down; this is dependent on the sales file format that is submitted from the Epos provider.
• The PLU upload code shows the sales naming convention to ensure that the correct sales file is uploaded, typically this is SITENAME_YYYYMMDD.csv.
• The PLU upload pathway shows the folder that the sales file is contained within this is typically V:\localuser\customer name\site name.

It is possible to enable rules for wastage (and other transfers) from Epos into FnB? How is this set up?

Live FnB….

• Yes this is possible; the configuration is applied via sales type conversion rules. Initially this must be enabled in admin.

 

Fig. 9 Shows the Sales Type Conversion Option Selected in FnB Admin

 

• Once applied the sales type conversion tab will become visible when selecting System admin > Epos Interface > import rules. The appropriate site can be selected from the drop down.

 

 

• To add a new rule the required sales type must be entered and the appropriate action selected from the drop down box.

 

Fig. 11 Shows the Sales Type Conversion Options that can be Configured

 

• Once the appropriate action is select any additional configuration to be applied, such as the wastage account to send the transfer to, can be selected.

 

Fig. 12 Shows the Detail of Sales Type Conversions that can be Configured

 

• Once configured when this information is sent by the Epos provider these transfers will automatically be recorded in FnB.
• They are approved into stock automatically and can be identified as they have been created by ‘automatic import’ rather than a designated user.

 

Fig. 13 Shows an Automatically Created Transfer in FnB

 

FnB R9….

• Wastage, and other, conversion rules can be applied in R9 easily, simply through entering the code that corresponds to the Sales Type sent by the EPOS against the account you wish the data to be loaded to. However there is no front end interface to configure this; it must be completed via the database.
• In R9 the transfers are automatically pending and they will need to be approved by the user. If the Epos provider sets a transfer to ‘overwrite’ and they re-send the data there is the potential that a user will need to approve a transfer multiple times as it will re-set to pending when the new data is submitted.

Where can I find API sales files?

• To find a customers API files you will need to login to FnB admin and find the GUID for that customer. Select Admin > FH API > find the customer from the list.

 

Fig. 14 Shows the GUID Information in FnB Admin

 

• The GUID is shown in the 4th column, and this is the folder reference for viewing any API sales files can be accessed via the WSsalesmonitor FTP folder. This contains a back-up of the sales file that was submitted by the Epos provider.
• To access these files select WSsalesmonitor > GUID reference > Year > month > files are shown.

2-Way Interfaces

Live FnB….

• 2-way interfaces are possible with Epos providers where Fourth can distribute information on menu items within the system in order for these to be created as reference items for customer to create these menu items as buttons on the till. It is possible for an Epos provider to call our web service and gather the below information:
  • Sites – stock location and lowest level of the organisation hierarchy
  • Units – collective name for a group of sites
  • Stock Period Dates
  • Menu Groups – lowest level of the menu item hierarchy assigned to an individual menu item
  • Menu Items – the menu items themselves in a standard output
  • Custom Menu Item Exports – includes additional menu item attributes as required
• This does not create the button on the till as additional options would usually be configured on the Epos software, such as the colour and placement of the button. This interface simply creates the name & PLU reference of the menu item within the Epos system, so that this does not need to be re-keyed. It also provides assurance that if a button can only be created once a menu item is created in FnB, that there will be no sales discrepancies.
• The Epos provider determines how often they call our API to gather this information.

FnB R9…

• The above interface is also possible within R9; however an additional ‘stocking policy’ interface can be applied. To establish the stocking policy of a site or unit based on the menu items that the site or unit’s EPOS system has been configured to sell. From the EPOS interface FnB requires the site or unit unique identifier, the PLU number (unique identifier) of each menu Item that may be sold, and the menu Items selling price. Taking the menu items that may be sold at the site or unit, FnB will identify all products used to create the menu Items and will configure each product to be available at that site or unit.
• This removes the requirement to assign products or recipes to site as the stocking policy is automated based on the recipe explosion of the buttons on the till. An example of the sales file format:

 

Fig. 15 Shows the Format of the Stocking Policy File

 

Checking, combining and uploading API sales files…

• To check if a sales file has been submitted by a customer’s Epos provider you will need to login to FnB admin and find the GUID for that customer. Select Admin > FH API > find the customer from the list.
• The GUID is shown in the 4th column, and this is the folder reference for viewing any API sales files can be accessed via the WSsalesmonitor FTP folder. This contains a back-up of the sales file that was submitted by the Epos provider.
• To access these files select WSsalesmonitor > GUID reference > Year > month > files are shown.
• To view a sales file select ‘edit’ and the file will be shown in notepad as per the screen shot below.

 

Fig. 16 Shows an XML File Opened in Notepad by Selecting the Edit Option

 

• If there was an error with a sales file, or the information needs to be re-set and the sales files re-uploaded API sales do not automatically re-upload.
• FTP sales files will re-upload if they are re-set, however a user must manually re-submit API files. This can be completed by using the consumer.exe tool. The user name and password for the customer; this can be found in FnB admin as per the section above, must be entered to any action to become accessible.

 

Fig. 17 Shows the 'consume.exe' Tool

 

• It is then possible to upload single or multiple sales files for submission via the web-service.

 

Fig. 18 Shows the Sales Upload Options within the 'consumer.exe' Tool

 

How can you find out if a file is API or FTP easily?

• If a user only has access to site level it is possible to hover over the sales file and in the bottom left hand corner the file name is displayed, in the below example the sales file name is ‘BARYYYYMMDD.csv’.

 

 

Can you submit wastage on a sales file via the FTP?

• Yes, although only in 1 sales file format.  If a sales file is submitted in an API compatible csv format this can be submitted via the web-service and wastage rules can be taken into account. Standard FnB Live data-load headers cannot accommodate the wastage information via an FTP submission; therefore this is currently only available in R9.

 

Fig 20 Sample File