You are on page 1of 14

Hospitality Service Center V2.

6
HSC V2.6
HSC Hostlink protocol specification (TCP/IP)
V 1.3

Any paper copy, or other electronic copy, is not necessarily the current version and is an
uncontrolled copy. It is the user's responsibility to ascertain whether this is a current copy.
Copyright 2014, PSE Group
Copying of this document, or giving it to others, or the use or communication of the contents
thereof, is forbidden without prior written authorization. The copyright notice hereon shall not
constitute or imply publication. All rights are reserved.

Table of Contents:

1
2
3
3.1
3.1.1
3.1.2
3.1.3

Introduction
The HSC Hostlink Interface for PMS via TCP/IP
Record Interface
Structure of Interface Records
General Information for connection via TCP/IP
Overview of all Record Types Supported by HSC
Description of the Record Types Supported by HSC

3
4
5
5
5
6
7

Introduction

What is the HSC Hostlink Protocol ?


This chapter describes the communication interface between the HSC system and a front office system.
This solution is referred to in this document as the server and the front office system as the host.
The HSC Hostlink protocol is based on Caracas Link Version 4.2 but it is not the successor of Caracas
Link.
Preceding Version
This chapter exclusively describes the functionality of the HSC Hostlink protocol. Although the actual
protocol description was not changed, this version offers new functions (described in this chapter) that
are not available for connecting an older version or another TC system and for existing HSC Hostlink
installations.
Downward Compatibility
HSC Hostlink is downward compatible as regards the protocol relationships, so that existing
installations can also be operated with HSC Hostlink, and front office systems dont have to make
protocol changes to connect to the HSC system (provided no new record types are used).
The HSC Hostlink Interface
HSC Hostlink can be used to connect a front office system of your choice via a server to a HiPath 4000
or HiPath 3000 PBX system.
The base for the communication between the systems is provided by the communication record types,
which are always used, irrespective of the connection type selected. HSC prefers a connection via
TCP/IP as Server or Client to the partner system.

The HSC Hostlink Interface for PMS via TCP/IP

This mode is only supported by the following HSC plug-in:


HOSTLINK_flexplugin.hhsc

Port Number
When the front office system is connected via TCP/IP, one port number is configured for the connection
in addition to the IP address of the host PC. As port numbers only values greater than 1024 are valid
because ports below that value are reserved for other tasks. HSC can thus operate both as a server
and as a client in the network connection.

Connection Setup
This setting is important for connection setup and must always be coordinated with the appropriate front
office system. When configured as a client, HSC tries to set up the connection to the host at regular
intervals. When configured as a server, HSC only makes one connection available and waits for the
host to connect.

Data Exchange
Data exchange can start as soon as the connection has been set up. The data record structure
corresponds to the standard data record structure (see chapter on order interfaces), incl. control
characters, but without BCC. Polling, for example, is not performed, i.e. only data records are
transferred. Every data record must be acknowledged by the remote station with ACK. In other words,
HSC only sends one data record at a time and then waits for the acknowledgement with ACK. The data
record is repeated if no acknowledgement is received within a set period of time. Acknowledgement,
e.g. with NAK, or an acknowledgement request with ENQ is not permitted.

Record Interface

Data Exchange via Record Interface


Data is exchanged via a record interface that processes both records from the server to the front office
system and records from the front office system to the server. Each record must be included in the HSC
plug-in file so that it can be sent or received. If a non-configured record is sent, the data is not processed
on the system, and HSC will log it in the logfile. The record is only acknowledged (with ACK) when it is
configured in the HSC plug-in file.

3.1 Structure of Interface Records


3.1.1

General Information for connection via TCP/IP

Data is exchanged between the server and the front office system through records. The records must
have the following structure:

Meaning

Length

STX

1 Byte

record type

2 Byte

Subsystem-Id

1 Byte (always 1)

Extension

6 Byte, left-aligned, filled with blanks

Applicationhandle

10 Byte (always 000000000)

Data

Depends on the record type

ETX

1 Byte

This produces the following structure:


[STX] ss 1 nnnnnn 0000000000 [DATEN] [ETX]

Example:
[STX]0A100000000000000001[ETX]
This example involves record type 0A that can be sent both from the server to the front office system
and from the front office system to the server. The status is transferred as data, i.e.
0 = not ready, 1 = ready.

3.1.2

Overview of all Record Types Supported by HSC

The HSC Hostlink interface supports exclusively the following record types:
Record Description

Communication direction

01

Check In / Check Out

Front-Office

> Server

03

Wake-up Order set/delete

Front-Office

> Server

06

Divert Extension

Front-Office

> Server

07

Set Features

Front-Office

> Server

08

Disconnection

Front-Office

> Server

09

Check-in Advanced

Front-Office

> Server

0A

Bind

Server
Front-Office

> Front-Office
> Server

11

Call Charge

Server

> Front-Office

12

Voice Message

Server

> Front-Office

13

Room Status

Server

> Front-Office

14

Wake-up Order by Phone

Server

> Front-Office

15

Minibar Services

Server

> Front-Office

17

Meldung wakeup attempts

Server

> Front-Office

18

Minibar Advanced

Server

> Front-Office

19

Room Status Advanced

Server

> Front-Office

21

Do not disturb

Front-Office

> Server

22

Do not disturb

Server

> Front-Office

23

Update CheckIn name

Front-Office

> Server

25

Request for a Database Swap

Server

> Front-Office

29

Voice-Message Advanced

Server

> Front-Office

32

Minibar Complete

Server

> Front-Office

3.1.3
Rec. Pos.

Description of the Record Types Supported by HSC


Value

Description

01 Check-in / Check-out

Front-Office > Server

Note:
This record type 01 is only supported because of compatibility purposes. Please use record
type 09 for CheckIn/Out instead.
This functionality performs a CheckIn/Out in HSC. The front office system has to send this
record type only for one of the extensions in the room HSC gets the room information out
of its database and checks in or out the whole room.
CheckIn:
During CheckIn, HSC unlocks all extensions in the room automatically according to the COS
settings given in the received record. In addition, at all extensions in the room the guests
name will be set, the guests mailbox will be created and DND will be set to off at each
extension.
CheckOut:
During CheckOut HSC locks all extensions of the room automatically. In addition, HSC will
set the extensions names to FREE, all wakeups for the room and the guests mailbox will be
deleted. The DND will be set to on at every extension in the room.
Structure: 011nnnnnn0000000000ttsccx(40)
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

tt

HSC-internal phone lock/unlock.


The COS value will be mapped to locked or unlocked in HSC internally.
IMPORTANT: Values from 00 to 09 lead to unlocked, if it is necessary to lock
the system, additional COSTranslations have to be added in the plug-in.

22

Status: 1=CheckIn, 2=CheckOut

23

cc

Country code or language code of the guest. There has to be defined a


mapping between the country codes of the PMS and the country codes of
HSC in the HSC plug-in file (xmlLanguagePairs) and has to be configured
for each customer!

25

x(40)

Guest name. This name will be set at all extensions in the guests room and
at the Call Status Viewer in the HSC GUI automatically. Max. 40 digits (can
be shorter than 40 digits)

03 Wake-up Order Set / Delete

Front-Office > Server

This feature stores and deletes wakeup calls for the guest room main extension.
The wakeup date and time must be set to the future (minimum 10 minutes!).
If a VMS is connected it will be notified about the new wakeup entry. Structure:
031nnnnnn0000000000ddmmyyhhmmsp
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

ddmmyy The date of the wakeup.

26

hhmm The time of the wakeup.

30

Status: 0=delete wakeup, 1=set wakeup, 2=delete all wakeups

31

Mode: 0=one time wakeup request, 1=daily wakeup request

06 Divert Extension

Front-Office > Server

With this record type, the front office can divert an extension to another phone number. It is
possible to divert all guest extensions to other numbers. A diversion is only active for the
extension which is received. HSC doesnt set the diversion for all other guest extensions in
the guests room. HSC stores the forward number and shows it in the HSC Call Status Viewer
GUI. Structure: 061nnnnnn0000000000zzzzzzks
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


zzzzzz Phone number, 6 digits, left-aligned, filled with blanks

26

Type: always 0 in HSC

27

Status: 0=delete diversion, 1=set diversion

07 Set Features

Front-Office > Server

With this record, the front office system can set or delete a DND at the guests extension. The
DND will only be set for the received extension. HSC will not set the DND at all extensions
in the guests room. The DND has to be sent for each extension in the guests room.
Structure: 071nnnnnn0000000000s1
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


s

08 Disconnection

Status: 0=DND off, 1=DND on


Front-Office > Server

With this record, the front office system can disconnect an ongoning call at an extension. This
function can be used to disconnect the call during a checkout of the room to stop ongoing
phone connections and avoid uncalculated and charged calls.
Structure: 081nnnnnn0000000000s
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


s

Status: always 0 in HSC

09 Check-in Advanced

Front-Office > Server

This record has the same functionality as record type 01. In addition it has more fields
especially for VMS and does the same as 01. It is recommended to use this record type for
check in/out.
Structure: 091nnnnnn0000000000ttsccx(40)fr(10)g(10)o(6)vvvy(40)l(10)
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

tt

HSC-internal Class Of Service (locked, unlocked)


The COS values will be mapped to HSC-internal locked or unlocked state.
IMPORTANT: Values from 00 to 09 lead to unlocked, if it is necessary to lock
the system, additional COSTranslations have to be added in the plug-in.

22

Status:
1=Check-in (does the same as record type 01 with status 1) 2=Additional
Check-in (an additional guest is checked in in a room where a guest is
already checked in, )
3=Move to a free room (the old room will be checked out and the new
room will be checked in; wakeups and mailboxes will be lost) 4=Move to
an occupied room (the old and the new room will be checked out and then
the new room will be checked in again) 5=Check Out room is still
occupied (COS settings and name of the extension wont be changed)
NOT SUPPORTED BY HSC! 6=Check Out room free (Only when status
is not 1, 2 or 6 the swap flag must not be 1).

23

cc

Country code or language code of the guest. There has to be defined a


mapping between the country codes of the PMS and the country codes of
HSC in the HSC plug-in file (xmlLanguagePairs) and has to be configured
for each customer!

25

x(40)

65

66

r(10)

Reservation number, 10 digits, left-aligned, filled with blanks

76

g(10)

Group number, 10 digits, left-aligned, filled with blanks

86

o(6)

Old extension, 6 digits, left-aligned, filled with blanks

92

vvv

VIP status, 3 digits, left-aligned, filled with blanks, e.g. VIP

95

y(40)

Group name, 40 digits, left-aligned, filled with blanks

135

l(10)

Limit amount, 10 digits with leading zeroes.


This value is stored in the HSC database.

0A Bind

Guest name, max. 40 digits. This name will be set at all extensions in the
guests room and at the Call Status Viewer in the HSC GUI automatically.
Swap-Flag: 0=new CheckIn, 1=repeated CheckIn, e.g. after record 25 from
the Front-Office System

Front-Office <> Server

This record type is used to notify the communication partner (server or front office) about its
receive state. If one of the communicating programs is not able to receive data, it has to send
this record with status 0. If it is ready to receive data again, it has to send this record with
status 1. Structure: 0A10000000000000000x
20

Status: 0=not ready, 1=ready


9

11 Call Charge

Server > Front-Office

This record is used to transfer the call charges to the front office system. In HSC call can be
calculated internally or externally (external Call Accounting System). When it is calculating
the call costs internally, the charge rate table has to be configured in the Admin GUI. Each
telephone call results in the transfer of at least one call charge record; if the telephone system
is appropriately configured, several records can also be created for a call. The front office
system can then disconnect ongoing calls using record type 08.
Structure: 111nnnnnn0000000000aa10x(68)p(10)b(10)h
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

aa

System ID, always 00 when HSC is used

22

10

ID or Filler, always 10 when HSC is used


Call record:
YYMMDDHHMMSShhmmssudggnnnnnnaaaaeeeeez(16)kgc(12)s
Position Value

24

x(68)
C
A
L
L
R
E
C
O
R
D

Description

24

YYMMDD Date of the call start, 6 digits

30

HHMMSS Time of the call start, 6 digits

36

hhmmss

Time of the call end, 6 digits

42

Satellite system ID, always 0

43

Service ID, always 0

44

gg

Group ID, always 00

46

nnnnnn

52

aaaa

Trunk number/line code/CO access digits, 4


digits, left-aligned, filled with blanks

56

eeeee

Number of charge pulses, 5 digits, left-aligned, filled


with blanks

61

z(16)

Destination number, 16 digits, left-aligned, filled with


blanks

77

Destination number code

78

Call type, always 0

79

c(12)

91

Extension 6 digits, left-aligned, filled with blanks

Code number if used, otherwise always


000000000000
Call setup code , always 0

92

p(10)

Call charges with amount for calculation using unit price from server, 10
digits with leading zeroes.
This value refers to the smallest unit of currency, e.g. 12.34 will be sent as
0000001234.

102

b(10)

Costs with amount for calculation using unit price, charge tables or the Swiss
table if working with CCM, 10 digits with leading zeroes. This value refers to
the smallest unit of currency, e.g. 12.34 will be sent as 0000001234.

112

Code, (national, international, local, mobile)

10

12 Voice Message

Server > Front-Office

This record is used to transfer the voicemail status of the guest telephone from the VMS to
the front office system if its value in the VMS changes. Structure: 121nnnnnn0000000000s
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

Message status: 0=no new messages, 1=at least one new message

13 Room Status

Server > Front-Office

If the room status is changed at the HSC administration GUI or through the telephone via
VMS, this record is sent to the front office system to notify it about the changed status.
Structure: 131nnnnnn0000000000ss
4

nnnnnn

20

ss

Extension, 6 digits, left-aligned, filled with blanks


Status, 2 digits, with leading zeroes if needed
For each internal room status there can be defined an external room status
which is sent to the front office system. This mapping between internal and
external room statuses is done in the HSC Hostlink plug-in file through a
translation (RoomStatusTranslation).

14 Wake-up Order by Phone

Server Front-Office

With this record type HSC can inform the front office system about new wakeup requests.
Wakeups can be set via the HSC GUI or the connected VMS. The wakeup request is executed
via HSC (internal wakeup) or the VMS (external wakeup) features. If the wakeup is executed
HSC sends a record type 17 and informs the front office system about the wakeup result.
Structure: 141nnnnnn0000000000hhmmsp
4

nnnnnn

20

hhmm

24

Status: 0=delete wakeup, 1=set wakeup

25

Mode: 0=one-time wakeup request, 1=daily wakeup request

15 Minibar

Extension, 6 digits, left-aligned, filled with blanks


The time of the wakeup call.

Server > Front-Office

This record is sent to the front office system when minibar items are booked via the VMS and
telephone by staff members. Minibar items can only be booked but not canceled.
It is only possible to send record type 15, 18 or 32. The mixture of these record types is not
possible.
Structure: 151nnnnnn0000000000aaaaaas
4
20
21

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


aaaaaa Article number from the HSC database, 6 digits, left-aligned, completed with
blanks
s

Status: 1=booked, 0=canceled not supported!

11

17 Wakeup Attempt

Server > Front-Office

This record is used to inform the front office system about the execution result of wakeup
attempts.
Structure: 171nnnnnn0000000000ddmmyyhhmms
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

ddmmyy The date of the wakeup request

26

hhmm The time of the wakeup request

30

Status: 0=wakeup unsuccessful, 1=wakeup successful

18 Minibar Advanced

Server > Front-Office

This record is sent to the front office system when minibar items are booked via the VMS and
telephone by staff members. Minibar items can only be booked but not canceled.
It is only possible to send record type 15, 18 or 32. The mixture of these record types is not
possible.
Structure: 181nnnnnn0000000000aaaaaasx(10)
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


aaaaaa Article number from the HSC database, 6 digits, left-aligned, filled with blanks

26

27

x(10)

Status: 1=booked, 0=canceled not supported!


RunnerId from the HSC database. The runnerId is configurable in the
Administration GUI of HSC.
10 digits, left-aligned, filled with blanks

19 Room Status Advanced

Server > Front-Office

If the room status is changed at the HSC administration GUI or through the telephone via
VMS, this record is sent to the front office system to notify it about the changed status.
Structure: 191nnnnnn0000000000ssx(10)
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

ss

Status: 2 digits, with leading zeroes if needed


For each internal room status there can be defined an external room status,
which is sent to the front office system. This mapping between internal and
external room statuses is done in the HSC Hostlink plug-in file through a
translation (RoomStatusTranslation).

22

x(10)

RunnerId from the HSC database. The runnerId is configurable in the


Administration GUI of HSC.
10 digits, left-aligned, filled with blanks

12

21 Do not disturb / Class Of Service


Change

Front-Office > Server

This record can be used to set or delete a DND at an extension in HSC. Alternatively it can
be used to lock or unlock an extension in HSC. The DND or the lock will only be set for the
given extension. Structure: 211nnnnnn0000000000s
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


s

Status: 0=DND off, 1=DND on, 2,3,4=unlocked, 5=locked


The conversion from these status values to internally locked or unlocked is
done through a translation in the HSC Hostlink plug-in file (COSTranslation,
SetCOSTranslation).
incoming Status

HSC-internal Lock

2,3,4

Unlocked

Locked

22 Do not disturb

Server > Front-Office

With this record the server is able to inform the front office system about a set or deleted DND
at an extension. If the DND is set for a room via the HSC GUI, this record will be sent for each
extension in the room. Otherwise if the DND is only set for a specific extension, it will be sent
only once.
This record is only for information purposes. The front office system must not send an
answer using record type 21 because of the risk of loops.
Structure: 221nnnnnn0000000000s
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


s

Status: 0=DND off, 1=DND on

23 Update Check-in Name

Front-Office > Server

This record is used by the front office system to change the name of the guest at the guests
extension. The name is visible on the guest telephone and in the Call Status Viewer at the
HSC GUI. The name is only set at the given extension and not at each extension in the room.
Structure: 231nnnnnn0000000000x(40)
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


x(40)

Guest name, max. 40 digits. This name will be set at all extensions in the
guests room and at the Call Status Viewer on the HSC GUI automatically.

25 Request for a Database Swap

Server > Front-Office

With this record the server can request all host data. The front office has to send the last
checkIn or checkOut record for each room. This command is only sent if the synchronization
button is pressed in the HSC administration GUI.
Structure: 2510000000000000000s
20

Status: always 0 to get all host data

13

29 Voice-Message Advanced

Server > Front-Office

This record is used to transfer the voicemail status of the guest telephone from the VMS to
the front office system if its value in the VMS changes.
Structure:
291nnnnnn0000000000ssnn
4

nnnnnn Extension, 6 digits, left-aligned, filled with blanks

20

ss

Number of unread messages in the VMS mailbox, 2 digits, with leading


zeroes.

22

nn

Number of read messages in the VMS mailbox, 2 digits, with leading zeros.

32 Minibar Complete

Server > Front-Office

This record is sent to the front office system when minibar items are booked via the VMS and
telephone by staff members. Minibar items can only be booked but not canceled.
It is only possible to send record type 15, 18 or 32. The mixture of these record types is not
possible.
Structure: 321nnnnnn0000000000aaaaaax(30)ccp(10)
4
20

nnnnnn Extension, 6 digits, left-aligned, filled with blanks


aaaaaa Article number, 6 digits, left-aligned, filled with blanks

26

x(30)

56

cc

58

p(10)

Article name, 30 digits, left-aligned, filled with blanks


Amount, 2 digits, with leading zeroes if needed
Price of the article, 10 digits with leading zeroes in the smallest unit of
currency, e.g. 12.34 will be sent as 0000001234.

14