Connection to External Delivery via ExternalDeliveryInterface (EDI)

Introduction

ExternalDeliveryInterface module — hereinafter EDI — allows exchanging information between external third-party delivery system and r_keeper 7 cash system.

Interaction between systems is performed by .CSV files exchange. Pre-processed files are placed at a special network resource at the server in the company head office, and on network resources of servers installed in departments — restaurants — of the Company. These network resources should be availble for clients and servers of delivery systems and r_keeper 7 via LAN (head office) and VPN channels (departments), including while connecting to the specified servers in terminal mode — disks connection setup.

Distribution Kit

Module includes three files:

• ExternalDeliveryInterface.exe
• Settings.ini
• RK7XML.dll

The distribution package is available at FTP ftp://ftp.ucs.ru/rk7/other/ExternalDeliveryInterface

Setup

1. In the manager station, go to Service > Stations and Devices, select a required cash server and add XML interface for Windows on the Drivers tab. In the Options section of the driver properties, specify the Port, f.ex., 14441.
2. In the Sevice > Interfaces menu, link this XML interface to the logical interface
3. Restart the cash server
4. In Options > Tables and Plans > Hall Plans and Tables, create a new table or tables, or use existing one, to which orders from external delivery will be placed. Remember the table code
5. Create a folder for file exchange, for example, d:\UCS\EDI\Exchange\

6. Edit the Settings.ini file

   [Main]
   Frequency=15 ; Frequency of working folder scanning, in seconds
   WorkPath=C:\UCS\Aventa\v.1.0.0.41\ ; Working folder as per item 5
   LogLevel=2 ; logging level (maximum is 4)
   
   [RK]
   Server=127.0.0.1 ; IP address of r_keeper_7 POS server
   Port=14441 ; Port for XML interface
   PriceIdent=3 ; price type identifier in РК7 (Menu -> Price types reference)
   StationIdent=15015 ; station identifier
   GuestType=1  ; guest type identifier, optional
   UseXML=1
   UsePrice=0
   PayIdent=1043924 ; order prepayment currency identifier
   PrepayReasonIdent=1043926 ; prepayment deposit reason identifier
   PayInterfaceIdent=1 ; identifier of logical interface for connection to loyalty system (PDS or SRM). Required to link card to order
   StationIdent=1 ; cash register station identifier
   OneTableMode = 1; mode of creating orders at one table (creating tables with "point") — mode on (1) or off (0), starting from version 1.0.0.47
                   ; if off (0), interface will only create one order if different orders with the same table number are created
   OneTableIdent = 12345; table identifier for orders creation in OneTableMode = 1 mode, starting from version 1.0.0.47
   
   [License]
   Server=l.ucs.ru ; IP address of license server, do not modify
   Port=60606 ; Port for license server, do not modify
   
   ; Optional parameters
    
   [Main]
   DebugMode=1 ; debug mode
   
   ; Enable interface with statistics
   [Main]
   RefServerPort=7251 ; servers port

   Usage:

   • http://127.0.0.1:7251/stat — shows current session statistics
   • http://127.0.0.1:7251/stat?days=3 — shows stats for the last 3 days
7. Run the ExternalDeliveryInterface.exe file.

Licensing

• In the application License Request window (Запрос лицензии), click Generate request (Сгенерировать запрос) and copy the license request code
• At the license server site, create a new SW order request for your object, select Interface to the Delivery System 
• After request confirmation, generate a license.

The program will operate if connection with UCS licensing server is established, i. e., the internet connection is mandatory at the moment of license verification.
Time of next license verification is specified in Next verification field (Следующая проверка). If the restaurant has no connection, f.ex. due to the internet problems, it is enough to connect any temporary communication channel — USB modem — and click Update license.

To test the functionality, create file in accordance with the template — see Annex 1 — and place it to the folder from item 5 of the Setup section. The process will be further delegated to external Delivery software.

Depending on the folder timeout, response file will appear — see Annex 2.

Functional Operations with Data Exchange

Menu Download

To download the menu automatically to the file, find the ExternalDeliveryInterface.exe application in tray, right-click on it and select Save menu (Сохранить меню or Сохранить справочники — depending on the version). Then, select the folder to save the file in, and specify the file name, f.ex., menu.csv. Saving is only possible if the application is licensed. 
If references need to be downloaded for external delivery software without interrupting EDI service, do the following:

1. Fill in 3 parameters in Settings.ini:
   • RefsDefaultPath=D:\UCS\EDI\Refs\ ;; A full path to the existing folder for saving references
   • RefServerPort=7251 ;; A free port for the http server — specify in server properties
   • RefServerAP={A11858BB-8C51-475A-A000-3E82AA1A56C8} ;; A functionality access point — an arbitrary value, f.ex., a unique GUID

2. Open the following page in the browser: 0.0.1:7251/{A11858BB-8C51-475A-A000-3E82AA1A56C8}

3. See a successful saving message or an error message.

   Important!

   The option is supported since version 1.0.0.63.

New Order Download

Delivery orders are generated by users in external delivery system. 

External delivery system client should create the Order_New<Table_code>.csv file, where <Table_code> is some 4-symbol unique integer identifier generated by external delivery, f.ex., Order_New9032.csv and OrderParts_New9032.csv. These files contain values of order fields and order lines, respectively. Suffix New is the marker of the initial order download to r_keeper 7. See the file format in Annex 1.

The file is downloaded to the folder specified in item 5. Software application ExternalDeliveryInterface.exe that implements data exchange between external delivery system and r_keeper 7 performs automatic periodic resource — folder created in item 5 — scanning for order import files. If downloaded order files are found, data import to r_keeper 7 is performed. After import is complete, processed files are deleted from the address folder, and a response file is created.

When data is imported to r_keeper 7, a table is created. The following conditions should be met:

• The table code shall correspond to the <Table_code> parameter specified in the name and content of the corresponding import file
• The table opening date and time correspond to the Order date and time specified in the delivery system DB
• The number of guests shall correspond to the number of guests in r_keeper 7 and the delivery system DB
•  waiter code is an employee code from r_keeper 7
• The magnetic card type is the magnetic card type specified in discount properties in r_keeper 7 that needs to be applied to the order.

The order is saved in r_keeper 7 as an open, i.e. not paid table with simultaneous automatic receipts transfer to printers with distribution betweeb production facilities — service print — by means of r_keeper 7. This function is equivalent to the Save order function in r_keeper.

After a specified time period, a delivery system client searches for the State_New<Table_code>.csv file in the address network data exchange resource folder at the server in a department (restaurant) of the Company where <Table_code> is some 4-symbol unique integer order identifier that was earlier transferred to r_keeper in the name and as a part of the corresponding Order_New<Table_table>.csv order export file. This file can contain one of three response options from r_keeper 7:
1 — the order is successfully downloaded to the table <table_number>
0 — the specified table <Table_number> is already open, order is not downloaded
2 — the order not downloaded <error text>,
where <error text> is the text of an error generated by r_keeper application server; the reason why the order was not downloaded.
See an example of the response file in Annex 2.

• If the file with the order import notification is missing, Order is not received in r_keeper is marked
• If 0 flag is set — Order was received but not imported to r_keeper
• If 1 flag is set — Order was received and imported to r_keeper
• If 2 flag is set — Order was received but not imported to r_keeper. The specified table is open.

Order Changes Download

Further order processing technology in delivery system DB, depending on results of download to r_keeper 7, will be performed within a separate task.
If repeated download of the edited order, f.ex., export/import of the preciously downloaded order, is performed from the delivery system to r_keeper 7, the edited order is only downloaded from the delivery system in the edited part of number of guests and new added order positions, including increase of previously downloaded positions, in the Order_Edit<Table_code>.csv format.

Position deletion from the order content, as well as reducing the amount of earlier downloaded positions, are not downloaded from delivery system, and are not processed by r_keeper 7 system. Therewith, the software interface of r_keeper 7 data exchange system should classify and process this order as already downloaded earlier, to prevent duplication of orders in r_keeper 7 DB, namely: 

• Modify number of guests for the corresponding open table in r_keeper 7 DB
• Add positions or increase the number of earlier downloaded positions from the order content to the corresponding open table in r_keeper DB.

As a result of order changes import, software interface of r_keeper 7 data exchange returns the State_Edit<Table_code>.csv file. This file can contain one of three r_keeper response options:
1 — order changes are downloaded successfully into <Table_number> table
0 — specified <Table_number> table is closed, table changes are not downloaded
2 — table changes are not downloaded <error text>.

Find the formats of order changes export/import files and response results of the changes downloading in Annexes 3 and 4. Rules of changes export/import files routing and placement are the same as the rules of the initial orders downloading described above.

Order closing in the delivery system and table closing in R-Keeper 7 is performed by standard systems functionality and does not require data exchange.

Linking Card to Order

To specify the card, add the card number as the 6-th parameter to line format (CSV). In this case, the cash register will operate the same way as if the card was physically read.

In Settings.ini, fill in the following parameters:

[RK]
; identifier of logical interface (Service>Interfaces reference in the manager station) used for connection to loyalty system (PDS or r_keeper CRM).
PayInterfaceIdent=1
; identifier of cash register station where orders from EDI are processed
StationIdent=1

Format of exchange files

Annex 1 — New Order File

New order import/export file format, WIN encoding.

1st line \\ TABLE NUMBER;DATE;NO OF GUESTS;WAITER CODE;MAGNETIC CARD TYPE(=magnetic card type in discount properties);LOYALTY CARD; BOOKING NUMBER; POINTS; SERVING TIME; PRINTING TIME; COMMENT

Lines 2..N \\ EXTERNAL PRODUCT CODE;PRICE;AMOUNT;PRODUCT TYPE(MEAL or MODIFIER , for Dish=0, for Modifier=1)

File example:

9032;06.03.2008 10:38:08;2;465;44
45;10,5;7;0
46;25,1;4;0

The example file is located in Order_New9032.csv 
Since version 1.0.0.41, the first field will have the order number in brackets added after table number, f.ex.:

9945(273716537165);01.10.2014 19:28:02;1;275
191;355,5;1;0

Work with Combo

New line types are added to csv:

2 — a combo menu item
3 — a combo item
4 — a menu item associated with a combo item
5 — a modifier for the menu item

An example of creating a combo lunch containing:

• Caesar salad
  
  • with salmon — a modifier
• Cappuccino

1;01.09.2015 17:49;5;5
13;0;1;2 — a combo menu item — Lunch
5;0;1;3 — a combo item — Caesar
6277;0;1;4 — Caesar dish linked with a combo item
1;0;1;5 — a modifier — with salmon
7;0;1;3 — a combo item — Cappuccino
3029;0;1;4 — Cappuccino dish

Annex 2

New order import/export results file format, WIN encoding.
1 — the order is downloaded successfully to table 9032
An example file is located in State_New9032.csv

Annex 3

An existing order changes import/export file format, WIN encoding.

TABLE CODE;DATE;NO OF GUESTS 
9032;06.03.2008 10:38;2
EXTERNAL PRODUCT CODE;PRICE;AMOUNT 
45;10,5;3
46;25,1;4
An example file is placed in Order_Edit9032.csv

Annex 4

An existing order changes import/export results file format, WIN encoding.
0 — specified table 9032 is closed, order changes are not downloaded.
An example file is placed in State_Edit9032.csv