Introduction

The interface is designed for sending the information on cash station events through the HTTP protocol to the address indicated in the driver parameter.
The main task is to transfer data on order changes, but other cash station events are also supported.

There are two variants to set up notifications:

  • Using the mailing mechanism for version 7.6.5.440 and later
  • Via HTTP Order Notify interface for versions earlier than 7.6.5.440

Procedure

Once started, the driver waits either for the cash station events or for the cash server to shut down.

Events are sent by the driver strictly in FIFO order. At the moment, the maximum number of events in the queue is 256. Once it is reached, newer events are not accepted until there is space for them. This mechanism is intended to prevent memory overflow and a cash server crash in case it is impossible to send messages, for example, if the event reception server does not respond.

For each address, there is a separate mailing list, as well as a separate log file. After the cash server is stopped, pending events will not be sent.

There is no waiting interval (timeout) for data delivery as the driver tries to send data immediately upon their arrival.

The driver is loaded once the cash server is started. Regardless of the cash station availability, the message on the cash server start with the Situation = 1 is put on a queue. This event is similar to the ordinary cash start but with a limited number of nodes.

An example message appearing after cash server loading and initializing:

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2020-01-14T15:38:23" Situation="1" seqnumber="1" guid="{9ECCB1B5-97EE-4B88-9840-8568F05586D0}" name="Started" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Server id="15002"/>
<Item/>
</a>

In this event, only the cash server identifier is specified. If the address is specified in the cash server properties, the server notifies the driver about its availability. After that, the event occurs.

When the cash station is started, a similar message is queued, but it has an extended set of nodes:

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2019-12-18T17:17:58" Situation="1" seqnumber="1" guid="{9ECCB1B5-97EE-4B88-9840-8568F05586D0}" name="Started" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Station id="15003" code="1" name="MM_CASH" NetName="MM_CASH_169058"/>
<Server id="15002" code="15002" name="MM_MID" NetName="MM_MID"/>
<Item/>
</a>

It has both extended information on the cash server and data on the cash station. This mechanism allows separating the events of the cash server loading and cash station loading for their separate processing.

The GUID shown in the example is not a constant and can be changed.

Supported commands sent by the driver in the Situation attribute:

Situation

Event

1

Cash server or cash station start

3

Order changing

4

Order calculation

5

Receipt closing

9

Closing the order

10

Cash station locking (logoff)

11

Creation of a new order

12

Opening an existing order

13

Order saving

14

Receipt deleting

18

Cash station closing

21

Cash station sign in

24

Switching to the receipt print mode

HTTP Order Notify Licensing

If you need more than one connection, the HttpOrderNotify interface must be licensed.
The license must be activated starting from version 7.6.5.459. The license in the licensing system is called R-Keeper module Order notification interface 12 months software.

HTTP Order Notify Interface

HTTP Order Notify works on the side of the cash server to which the cash station is connected. The driver is added to the cash server.
For the correct loading of the driver, it is necessary to bind the interface for the cash server to it. Find more information below.

For r_keeper versions earlier than 7.6.5

Add HTTP Order Notify to the cash server:

Parameters:

Name
Description and Possible Values
Log FileThe path to the file, that will serve as a driver operation log. It may be absent, but in this case, it would be difficult to define the operation problems.

LogLevel

Logging level. There are three possible values:

  • 0 - errors only — In this mode, the log contains only the most important messages, f.ex. information on the interface loading, or the error messages: exceeding the limit of events in the list, an error when sending the data to the HTTP server, etc.
  • 1 - input xmls and errors — This mode is similar to the previous one, but also includes some important messages, f.ex. about the start of sending XML to the HTTP server address.
  • 2 - max log — The most complete logging level, containing all the details of the driver operation, including incoming and outgoing XML, the current status of the mailing list. etc.
DestURLs

HTTP address where the data will be sent to. Has the commonly used form of URL addresses.
Can contain only one address. If you need to send data to several HTTP servers, you should add a separate HTTP Order Notify driver for each of them.

For the cash server to download the driver, bind it to the interface:

  1. In the manager station, go to Service > Interfaces

  2. Create a new interface with the following properties:

    Name
    Description and Value
    [Cash server name]select the driver added to the cash server
    Common DLL Namespecify the driver file name, always httpnotf.dll

  3. Restart the cash server.

For r_keeper version 7.6.5 and later

Driver parameters are specified in the HTTP Order Notify properties of the cash server.

Parameters:

Name
Description and Possible Values
DestURLsHTTP addresses where the data will be sent to. Have the commonly used form of URL addresses. Can contain several addresses, separated by semicolons. There are certain license restrictions when several addresses are specified.
Log File NameThe path to the file, that will serve as a driver operation log. It may be absent, but in this case, it would be difficult to define the operation problems. The address' number from the addresses list is added to the log file name, starting from zero. Thus, if a log file name is httpnotf.stk, the file name will be httpnotf0.stk for the first address, httpnotf1.stk — for the second one, and so on.

Log Level

Logging level. There are three possible values:

  • 0 - errors only — In this mode, the log contains only the most important messages, f.ex. information on the interface loading, or the error messages: exceeding the limit of events in the list, an error when sending the data to the HTTP server, etc.
  • 1 - input xmls and errors — This mode is similar to the previous one, but also includes some important messages, f.ex. about the start of sending XML to the HTTP server address.
  • 2 - max log — The most complete logging level, containing all the details of the driver operation, including incoming and outgoing XML, the current status of the mailing list. etc.

The value of the DestURLs parameter is used only when starting the cash server. After changing this setting, restart the cash server to change the address list. To change the address list while the server is running, use the subscription mechanism.

For r_keeper 7.6.5 and later

  1. In the DestURLs parameter, specify the connection string in the following form:
    https://user_name:user_password@KDS_PRO_server_address:KDS_PRO_server_port/orderTaker
  2. Save the changes
  3. Restart the cash server

For r_keeper versions earlier than 7.6.5

If your r_keeper version is earlier than 7.6.5, you should add the HTTP Order Interface to the cash station manually. To do this:

  1. KDS PRO works only with driver version 18 and later. If you have an earlier version, before adding the interface download a later one from FTP: ftp://ftp.ucs.ru/rk7/other/KDS_PRO/Extra_Files/httpnotf.udb
  2. Copy and replace the httpnotf.udb in the reference server folder
  3. Restart the cash server
  4. Add HTTP Order Notify driver to the cash server:
  5. Configure the driver for all the cash servers if needed
  6. https://user_name:user_password@KDS_PRO_server_address:KDS_PRO_server_port/orderTaker
  7. The user name and password are optional. Specify them only if they are set in your account. Find the server port in the kds_pro.config file.
  8. Go to Service > Interfaces and create a new interface
  9. In the DLL Library Files section, select a required restaurant and specify the HTTP Order Notify driver

  10. Change the status to Active. Save the changes.

In versions later than r_keeper 7.6.5, the HTTP Order Notify driver works only through the subscription mechanism, using the interface is not supported.

Subscription Mechanism

To make the cash server send the notifications about changes, send the following POST request to it:

https://127.0.0.1:8001/rk7api/v1/subscribe.xml?service=httpnotf&url=https://HTTP_KDS2:1@172.18.2.2:1234/orderTaker

where:

Parameter
Meaning
serviceThe service name, should be httpnotf
urlURL to send notifications to

The address specified in the URL parameter will be added to the list of existing mailing addresses. An event with name=Started will be immediately sent to it.

If the number of addresses exceeds the available, then r_keeper will issue an error: HttpOrderNotify: address URL is disabled, license check failed.

XML Examples

Cash Station Authorization

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2019-12-18T17:18:00" Situation="21" seqnumber="3" guid="{81A89081-D394-4070-BD37-A8E54CCA7B56}" name="Login" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Station id="15003" code="1" name="MM_CASH" NetName="MM_CASH_169058"/>
<Server id="15002" code="15002" name="MM_MID" NetName="MM_MID"/>
<Waiter id="1" code="7" name="Administrator">
<Role id="100007" code="7" name="Administrators"/>
</Waiter>
<Item/>
</a>

Creating New Order

<?xml version="1.0" encoding="utf-8"?>
<a RestCode="199990093" DateTime="2019-12-18T17:18:33" Situation="11" seqnumber="13" guid="{833F0492-E8ED-4F34-81BC-8A9F4D73A995}" name="New Order" ShiftNum="1" ShiftDate="2019-11-18T00:00:00">
<Station id="15003" code="1" name="MM_CASH" NetName="MM_CASH_169058"/>
<Server id="15002" code="15002" name="MM_MID" NetName="MM_MID"/>
<Waiter id="1" code="7" name="Administrator">
<Role id="100007" code="7" name="Administrators"/>
</Waiter>
<Order visit="477823977" orderIdent="256" guid="{763C7F09-875A-438A-B6CB-25F7D3F74741}" url="http://code.ucs.ru/qr?id=209A9A2B872A4728BEC8F0B09C667E6A763C7F09875A438AB6CB25F7D3F74741B6995A91" orderName="8888888888" locked="1" version="0"crc32="0" orderSum="0" unpaidSum="0" discountSum="0" totalPieces="0" seqNumber="1" paid="1" finished="0" persistentComment=""nonPersistentComment="" openTime="2019-12-18T17:18:32">
<Creator id="1" code="7" name="Administrator">
<Role id="100007" code="7" name="Administrators"/>
</Creator>
<Waiter id="1" code="7" name="Administrator">
<Role id="100007" code="7" name="Administrators"/>
</Waiter>
<OrderCategory id="10033" code="1" name="Main"/>
<OrderType id="10069" code="9001" name="not selected"/>
<Table id="1000259" code="93" name="8888888888"/>
<Station id="15003" code="1" name="MM_CASH"/>
<Guests count="1">
<Guest guestLabel="1"/>
</Guests>
</Order>
<Session uni="2" line_guid="{39271E37-867D-41FF-99B8-59CB182323E9}" state="1" sessionID="2" isDraft="0" remindTime="2019-12-18T17:18:00" startService="2019-12-18T17:18:33" printed="0" cookMins="0">
<Station id="15003" code="1" name="MM_CASH"/>
<Author id="1" code="7" name="Administrator">
<Role id="100007" code="7" name="Administrators"/>
</Author>
<Creator id="1" code="7" name="Administrator">
<Role id="100007" code="7" name="Administrators"/>
</Creator>
<Course id="1" code="1" name="Cook later"/>
<PriceScale id="3" code="1" name="Main"/>
<TradeGroup id="7" code="1" name="By default"/>
</Session>
<Item ClassName="TOrder"/>
</a>


Troubleshooting

When functioning, the driver adds information on its work to the log to facilitate troubleshooting.
A regular problem is that data does not arrive to the receiving HTTP server. In this case, check if the address in the DestURLs parameter of the driver is correct and the HTTP server is available. If it is impossible to send data, the log will have messages containing the HTTP: Post error substring, for example:

18.12.2019 16:25:32:343 HTTP: Post error: Socket Error # 10061

Frequent error codes:

HTTP Code

Description

10061

'Connection refused' means that it is impossible to connect to the server

10054

'Connection reset by peer' means that the connection is closed by the server

In this case, check the HTTP server settings.

Messages of the type

SEND_THREAD: Signal [Send] ENTER, items in queue: 19

contain the current number of objects in the queue. Once the maximum number is reached, the log will display the following message:

XML: Can't add command. Max queue size: 256


  • No labels