WorkMan HVS - IP Protocol

About

This protocol is our own protocol and can be used if no other protocol is in place.

The protocol works over TCP/IP and is linebased with CR+LF (#13#10) as a end of command terminator. WorkMan HVS can work both as a client and as a server so it's up to the hotelsystem to decide which way they prefer.

HS = Hotel System (bookingsystem)
HVS = Our system (Hotel Växel System)

Commands

The first parameter is always the name of the command and the response to it always follows the form OK;<name of command> where OK is considered the command. The server/client should only send one command at a time and then wait for a response. If an answer hasn't been received within 10 seconds the connection should be considered down and a reconnect should be made.

Example:

HVS sends a welcome to a HS client that is connecting

 WELCOME;1

The HS-client responds

 OK;WELCOME

Common variables

<protocolversion> means what version of the protocol that support this. The current version is 1 only.

<roomid> the actual roomid that exists in the HS. Roomid of R1234 might have a extension 1234 in the PBX but might also be completely different. This is the roomid of th HS!

List over commands

Welcome

Command	WELCOME
Protocolversion	1
Direction	Server to client
Mandatory	Yes
Structure	WELCOME;<protocolversion>
Response	OK;WELCOME
Example sender	WELCOME;1
Example response	OK;WELCOME
About	Sends a welcome from the server to connecting client.

Keep-alive

Command	ALIVE
Protocolversion	1
Direction	HVS to HS
Mandatory	No, only HVS in clientmode sends this.
Structure	ALIVE
Response	OK;ALIVE
Example sender	ALIVE
Example response	OK;ALIVE
About	Sends an ALIVE-signal to the server to see that connection is up.

Wakeup

Command	WAKEUP
Protocolversion	1
Direction	HS to HVS
Mandatory	No.
Structure	WAKEUP;<roomid>;<wakeuptime>
Response	OK;WAKEUP
Example sender	WAKEUP;123;0645 Schedules a wakeupcall at 6:45 AM WAKEUP;123; Clears a scheduled wakeup
Example response	OK;WAKEUP
About	Creates or clears a wakeupcall in HVS.

<wakeuptime> can be either a time in 24hour format (hhmm) or blank to clear.

Note that only one wakeupcall can be registered.

Wakeup Sent

Command	WAKEUPSTATUS
Protocolversion	1
Direction	HVS to HS
Mandatory	No.
Structure	WAKEUPSTATUS;<roomid>;<wakeuptime>;<wakeupstatuscode>
Response	OK;WAKEUPSTATUS
Example sender	WAKEUPSTATUS;123;0645;ANSWERED
Example response	OK;WAKEUPSTATUS
About	Send info to HS about a wakeupcall.

This is sent to HS when a wakeup is sent and considered finished and no retries will be made.

<wakeupstatuscode> can have the following values:

ANSWERED = wakeupcall was answered.
BUSY = busytone was detected and no more retries will be made.
TIMEOUT = No answer was made after x retries.

Check In

Command	CHECKIN
Protocolversion	1
Direction	HS to HVS
Mandatory	No, but then all room must be manually checked in.
Structure	CHECKIN;<roomid>;<name of guest>;<languagecode>
Response	OK;CHECKIN
Example sender	CHECKIN;123
Example response	OK;CHECKIN
About

<name of guest> is the name of the guest.
<languagecode> is the language that will be used. Currently EA and EN sets it to english and SE and SW to Swedish. DL or blank can be used for Default language. This can be configured in HVS so more languages can be supported.

Note that this message opens the phone for outgoing calls (if that feature has been enabled in HVS).

Check out

Command	CHECKOUT
Protocolversion	1
Direction	HS to HVS
Mandatory	No, but then all room must be manually checked out.
Structure	CHECKOUT;<roomid>
Response	OK;CHECKOUT
Example sender	CHECKOUT;123
Example response	OK;CHECKOUT
About	Checks the customer out of HVS.

Note that this message closes the phone for outgoing calls (if that feature has been enabled in HVS).

Extension lock/unlock

TBA

Room status

Command	ROOMSTATUS
Protocolversion	1
Direction	HVS to HS
Mandatory	Yes, HS should be able to handle the message and send OK back.
Structure	ROOMSTATUS;<roomid>;<roomstatuscode>
Response	OK;ROOMSTATUS
Example sender	ROOMSTATUS;123;1
Example response	OK;ROOMSTATUS
About	Sends information about what condition the room is in.

<roomstatuscode> is a value between 0 - 9 that the maid registered. The meaning of this is dependant on the HS-system but here is a typical lineup.

1. Dirty/Vacant (DIV)
2. Dirty/Occupied (DIO)
3. Clean/Vacant (CLV)
4. Clean/Occupied (CLO)
5. Inspected/Vacant (ISV)
6. Inspected/Occupied (ISO)
7.  ?
8.  ?
9.  ?

Call charge

Command	CALLCHARGE
Protocolversion	1
Direction	HVS to HS
Mandatory	Yes, HS should be able to handle this.
Structure	CALL;<roomid>;<called date and time>;<callednumber>;<talked time in seconds>;<amount>
Response	OK;CALLCHARGE
Example sender	CALLCHARGE;123;20120831172853;0046708656820;35;0
Example response	OK;CALLCHARGE
About	Sends a callcharge to HS. Note that amount is included in the protocol but the current version of HVS (as of 31st of august 2012) doesn't send an actual amount but only sends 0 as amount. Note that the amount is also in a 100th fraction of the currency e.g. 1100 in amount is 11 SEK (or EUR or whatever currency that the system uses).

<called date and time> is a timestamp in 24 hour format with the following layout yyyymmddhhnnss (mm = month with starting 0 and nn is minute with starting 0).