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
- 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.
- In the Sevice > Interfaces menu, link this XML interface to the logical interface
- Restart the cash server
- 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
- Create a folder for file exchange, for example, d:\UCS\EDI\Exchange\
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 3.4. 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
- Run the ExternalDeliveryInterface.exe file.
Important!
Run the file as an administrator!
Licensing
- In "License Request" section press "Generate request" and copy the license request code (see Fig. 1).
- at license server site l.ucs.ru, create new SW request for your object, select "R-Keeper module Interface to delivery system SW" module (see Fig. 2).
- upon request confirmation, generate licnese
Note
License code is not transferred - unique EDI instance key is stored at the license server.
The program will operate if connection with UCS licensing server is established, i. e., 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 (e. g. problems with internet) - it is enough to connect any temporary communication channel (USB modem), and press "update license".
To test the functionality, create file in accordance with the template (see Annex 1), and place it to folder from p. 3 of Setup section. The process will be further delegated to exteranl Delivery software.
Depending on folder timeout (p. 3 of Settings section), response file will appear. (see Annex 2).
Functional operations with data exchange
Menu download
Download is performed automatically into file by pointing the ExternalDeliveryInterface.exe application with a mouse in tray and pressing "Save menu". Then, select folder to save the file in, and specify file name, e. g., menu.csv. Saving is only possible is license is in place.
If references need to be downloaded for external delivery software without interrupting EDI service, act as follows:
Important!
Important: supported starting from version 1.0.0.63.
- Fill 3 parameters in Settings.ini:
- RefsDefaultPath=D:\UCS\EDI\Refs\ ;; Full path to existing folder for saving references
- RefServerPort=7251 ;; Free port for http server (specify in server properties)
- RefServerAP={A11858BB-8C51-475A-A000-3E82AA1A56C8} ;; functionality entry points (arbitrary value), e. g., unique GUID
- 0.0.1:7251/{A11858BB-8C51-475A-A000-3E82AA1A56C8};
- Observe successful saving message or error message.
New order download
Delivery orders are generated by users in external delivery system.
External delivery system client shall compose Order_New<Table_code>.csv file, where <Table_code> is some 4-symbol unique integer identifier generated by external delivery (e. g., Order_New9032.csv and OrderParts_New9032.csv). The files contain values of order fields and order lines, respectively. Suffix New is the marker of initial order download to R-Keeper 7. See file format in Annex 1.
The file is downloaded to the folder specified in 3.3. Software application (ExternalDeliveryInterface.exe) that implements data exchange between external delivery system and R-Keeper 7 performs automatic periodic resource (folder created in 3.3) scanning for Order import files. If downloaded Order files are found, data import to R-Keeper 7 is performed. Upon import completion, processed files are deleted from address folder, and response file is created.
When data is imported to R-Keeper 7, a table is created. Therewith:
- table code shall correspond to <Table_code> parameter specified in name and content of appropriate import file;
- Table opening date and time correspond to Order date and time specified in delivery system DB;
- number of guests shall correspond to number of guests in R-Keeper 7 and delivery system DB;
- waiter code is employee code from R-Keeper 7;
- magnetic card tyep is magnetic card type in discount properties in R-keeper 7 that needs to be applied to the order.
The order is saved in R-Keeper 7 as open (not paid) table with simultaneous automatic bills transfer to printers with distribution across production facilities (service print) by means of R-Keeper 7 (same as "save order" function in R-Keeper).
Warning: R-Keeper 7 reference shall have as many tables with codes, as many tables are used in the external delivery, since, if non-existing table number is specified in the file, import will not be performed. Therefore, number of guests in the file shall not exceed the number of guests in table properties in manager RK7. You also cannot assign another order to the open table.
One new order has one .csv file with specific table number.
After specific time period, delivery system client searches for State_New<Table_code>.csv file in 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 as a part of corresponding Order_New<Table_table>.csv Order export file. This file can contain one of three response options from R_Keeper 7:
1 - order successfully downloaded to the table <table_number>;
0 – specified table <Table_number> is already open, order not downloaded;
2 - order not downloaded <error text>,
where <error text> is text of an error generated by R-Keeper application server (the reason why the Order was not downloaded).
See example of response file in Annex 2.
Note
Result of Order import-export to R-Keeper system is marked in the special info field of Order template of delivery system.
- If the file ith Order import notification is missing, "Order ont 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. 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 separate task.
If repeated download of modified order, i. e., export-import of earlier downloaded Order, is performed from delivery system to R-Keeper 7, the modified order is only downloaded from delivery system in the modified part of number of guests and new added Order positions (including increase of earlier downloaded positions), in Order_Edit<Table_code>.csv format.
Note
In case of increase of earlier downloaded positions in the Order content, modifications export file will have difference between old and new values of ordered position amount in "Quantity" column.
Position deletion from the Order content, as well as reducing the amount of earlier downloaded positions, are not downloaded from delivery system, and not processed by R-Keeper-7 system. Therewith, software interface of data exchange and R-Keeper 7 system shall 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 corresponding open table in R-Keeper 7 DB;
- add positions (or increase the number of earlier downloaded positions) from Order content to corresponding open table in R-Keeper DB.
As a result of Order modifications import, software interface of data exchange and R-Keeper 7 returns State_Edit<Table_code>.csv file. This file can contain one of three R_Keeper response options:
1 – order modifications downloaded successfully into <Table_number> table;
0 – specified <Table_number> table is closed, table modifications not downloaded;
2 – table modifications not loaded <error text>.
Formats of Order modifications export-import files, as well as response results of the modifications downloading, are listed in Annexes 3 and 4. Rules of modification export-import files routing and placement are the same as the rules of initial Orders downloading described above.
Order closing in delivery system and table closing in R-Keeper 7 is performed by standard systems functionality and does not require data exchange.
Card association with order
Important!
Important: patch implemented starting from version 1.0.0.40
To specify card, add card number as 6-th parameter to line format (CSV). In this case, cash register will operate the same way as if the card was physically read by the cash register.
In Settings.ini, fill the following parameters:
[RK]
; identifier of logical interface (Service - Interfaces reference in 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).
1-st 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 , =0 for Meal, =1 for Modifier)
File example:
9032 ; 06.03.2008 10:38:08 ; 2 ; 465 ; 44
45 ; 10,5 ; 7 ; 0
46 ; 25,1 ; 4 ; 0
Example file is in Order_New9032.csv
Starting from version 1.0.0.41, the first field will have order number in brackets added after table number, e. g.:
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 - combo menu item.
3 - combo item.
4 - menu item associated with combo item
5 - modifier for menu item.
Example of creating combo lunch containing:
Caesar salad
- with salmon (modifier)
-cappuccino
1;01.09.2015 17:49;5;5
13;0;1;2 - combo menu item (Lunch)
5;0;1;3 - combo item (Caesar)
6277;0;1;4 - Caesar meal associated with combo item
1;0;1;5 - modifier (with salmon)
7;0;1;3 - combo item (cappuccino)
3029;0;1;4 - cappuccino meal
Important!
Important: item codes are always used.
Example 2
Annex 2
New order import-export results file format. (WIN encoding).
1 - order downloaded successfully to table 9032
Example file is in State_New9032.csv
Annex 3
Existing Order modifications 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
Example file is in Order_Edit9032.csv
Annex 4
Existing Order modifications import-export results file format. (WIN encoding).
0 - specified table 9032 closed, order modifications not downloaded
Example file is in State_Edit9032.csv
Attachment | Size |
order_new9032.txt | 100 bytes |
Setup of connection to card server Setup of connection to Cash Management