OmniPCX Office OHL API Developer Guide Ed2.1 PDF

OmniPCX Office Hospitality Link
API Developers Guide
Platform Alcatel-Lucent OmniPCX Office
Interface OHL
Version R2.3.8
Revision Edition 2.1 – November 2013
Abstract This specification describes the OmniPCX Office Hospitality Link

(OHL) dialog between the OmniPCX Office Hotel driver and a
hospitality/hotel application, in order to interface the Alcatel-
Lucent OmniPCX Office to the application
Alcatel-Lucent Application Partner Program

TABLE OF CONTENTS
1 ABOUT THIS GUIDE .............................................................................................................................. 6

1.1 WHO SHOULD READ THIS GUIDE ........................................................................................................ 6
1.2 WHAT THIS GUIDE TELLS YOU ........................................................................................................... 6
1.3 TERMINOLOGY – DEFINITIONS ................................................................................................... 6
2 INTRODUCTION .................................................................................................................................... 7
3 PHYSICAL LINK AND PROTOCOL ................................................................................................... 8
3.1 ACKNOWLEDGEMENT ON TCP/IP ........................................................................................................ 8
3.2 TCP/IP CONNECTION MESSAGE ........................................................................................................... 8
3.2.1 Message format ........................................................................................................................... 8
3.3 TCP/IP KEEP ALIVE MESSAGES ............................................................................................................ 8
3.3.1 Message format ........................................................................................................................... 8
3.4 TCP/IP LINK BUFFER .......................................................................................................................... 9
3.5 START AND END CHARACTERS ........................................................................................................... 9
3.6 LONGITUDINAL CONTROL CHARACTERS ............................................................................................. 9
3.7 FIELD JUSTIFICATION ........................................................................................................................... 9
3.8 MANAGEMENT ..................................................................................................................................... 9
4 SUPPORT FOR SIX DIGIT PASSWORD........................................................................................... 10
5 MESSAGES FROM HOTEL DRIVER TO HOTEL APPLICATION ............................................. 11
5.1 SMDR OR TELEPHONE CALL TICKET.................................................................................................. 11
5.1.1 Message format ......................................................................................................................... 11
5.1.2 Notes ......................................................................................................................................... 11
5.2 CHECK-IN .......................................................................................................................................... 13
5.2.1 Message format ......................................................................................................................... 13
5.3 PHONE ALLOCATION .......................................................................................................................... 13
5.3.1 Message format ......................................................................................................................... 13
5.4 VOICE MAIL FACILITIES ATTRIBUTION ............................................................................................... 14
5.5 MODIFICATION .................................................................................................................................. 14
5.5.1 Message format ......................................................................................................................... 14
5.6 CHECK-OUT ....................................................................................................................................... 15
5.6.1 Message format ......................................................................................................................... 15
5.7 ROOM STATUS CHANGE ..................................................................................................................... 15
5.7.1 Message format ......................................................................................................................... 15
5.8 GUEST TELEPHONE ACCOUNT ............................................................................................................ 15
5.8.1 Message format ......................................................................................................................... 15
5.8.2 Notes ......................................................................................................................................... 16
5.9 DATA TRANSFER ................................................................................................................................ 16
5.10 INTERACTIVE DATA TRANSFER .......................................................................................................... 16
5.11 SPECIFIC DATA TRANSFER.................................................................................................................. 16
5.12 WAKE-UP EVENTS .............................................................................................................................. 16
5.12.1 Message format ......................................................................................................................... 16
5.13 VOICE-MAIL EVENTS .......................................................................................................................... 16
5.14 GUEST DATA RE-INITIALIZATION ....................................................................................................... 17
5.14.1 Full re-initialization message format ........................................................................................ 17
5.14.2 Partial re-initialization message format ................................................................................... 18
5.15 DYNAMIC SUITE ................................................................................................................................. 18
5.16 EXTENDED SMDR ............................................................................................................................. 18
5.17 REPLY ................................................................................................................................................ 18
5.17.1 Message format ......................................................................................................................... 19
5.18 MESSAGE ACKNOWLEDGEMENT ........................................................................................................ 20
5.19 CONTROL CHARACTERS ..................................................................................................................... 20
6 MESSAGES FROM HOTEL APPLICATION TO HOTEL DRIVER ............................................. 21
AAPP – OHL API Developers Guide Edition 2.1 – Page 2

Copyright © 2012 Alcatel-Lucent, All rights reserved
6.1 CHECK-IN .......................................................................................................................................... 21
6.1.1 Message format ......................................................................................................................... 21
6.2 PHONE ALLOCATION .......................................................................................................................... 22
6.2.1 Message format ......................................................................................................................... 22
6.3 VOICE MAIL FACILITY ATTRIBUTION .................................................................................................. 22
6.4 MODIFICATION .................................................................................................................................. 23
6.4.1 Message format ......................................................................................................................... 23
6.5 CHECK-OUT ....................................................................................................................................... 24
6.5.1 Message format ......................................................................................................................... 24
6.6 INTERROGATION ................................................................................................................................ 24
6.6.1 Message format ......................................................................................................................... 24
6.7 DATA TRANSFER ................................................................................................................................ 24
6.8 NIGHT AUDIT REQUEST ...................................................................................................................... 24
6.9 RE-INITIALIZATION REQUEST ............................................................................................................. 25
6.9.1 Message format ......................................................................................................................... 25
6.10 DYNAMIC SUITE ................................................................................................................................. 25
6.11 MESSAGE ACKNOWLEDGEMENT ........................................................................................................ 25
6.12 CONTROL CHARACTERS ..................................................................................................................... 25
7 NEW MESSAGES FOR SUPPORT OF 6 DIGITS PASSWORD ..................................................... 26
7.1 MESSAGES SENT FROM HOTEL DRIVER TO HOTEL APPLICATION ....................................................... 26
7.1.1 Check-in message format with six bytes password length ........................................................ 26
7.1.2 Modification message format with six bytes password length .................................................. 27
7.1.3 Full re-initialization message format with six bytes password length ...................................... 28
7.1.4 Partial re-initialization message format with six bytes password length .................................. 29
7.1.5 Reply Message format with six bytes password length ............................................................. 30
7.2 MESSAGES SENT FROM HOTEL APPLICATION TO HOTEL DRIVER ....................................................... 31
7.2.1 Check-in message format with six bytes password length ........................................................ 31
7.2.2 Modification message format with six bytes password length .................................................. 32
8 APPENDIX A: EXAMPLE OF CRC CALCULATION ..................................................................... 33
9 APPENDIX B: ISO 8859-1 (OR ISO LATIN-1) CHARACTER SET ............................................... 34

History of the document
Edition 1 - June 04 Creation of the document
Edition 1.1 - September 04 Update regarding R1.6.0
Edition 1.2 - April 05 Update regarding R1.7.0

Add Trunk number information under SMDR frames
Allow subscriber number greater than 4 digits under SMDR frames
Edition 1.3 - June 05 Update regarding R1.8.0

Add clarification for cost field under SMDR frames (§4.1.1, §4.1.2)
Add clarification about TCP/IP keep alive message (§3.1, §3.3.1)
Edition 1.4 - August 09 New logos.
Edition 2.0 - December 12 Adding the support for 6 digits password from OmniPCX Office
R8.2
Edition 2.1 -November 13 Corrections (OLDriver 2.3.8)
References
 [1] OHL Driver Installation & Configuration
OmniPCX Office OHL

Driver InstallationConfiguration
 [2] Technical Communication TC0091: OLD Driver
Copyright ® 2012 by Alcatel-Lucent.

Product specifications contained in this document are subject to change without notice. This
document may not be reproduced in whole or in part without the express written permission of
Alcatel-Lucent.
Alcatel-Lucent® and the Alcatel-Lucent logo are registered trademarks of Alcatel-Lucent. All other
trademarks are the property of their respective owners.

1 ABOUT THIS GUIDE
1.1 Who Should Read This Guide
This guide is for developers willing to learn how to write Hotel or Hospitality applications
communicating to Alcatel-Lucent OmniPCX Office platforms
1.2 What This Guide Tells You

This guide provides the complete and detailed description of the OHL interface.
1.3 TERMINOLOGY – DEFINITIONS

 ACK ACKnowledgement message
 AAPP Alcatel-Lucent Application Partners Program
 AHL Alcatel-Lucent Hospitality Link
 API Application Programming Interface
 CRC Cyclic Redundancy Code
 ETX End Transmission
 IP Internet Protocol
 NACK Non-ACKnowledgement message
 OXO OmniPCX Office
 STX Start Transmission
 SMDR Station Message Detail Recording
 TCP Transmission Control Protocol
 GUI Graphical User Interface
 PCMAN OmniPCX Office internal management IP interface
 OHL OmniPCX Office Hospitality Link
 PM5 OmniPCX configuration management application
 MMC Man Machine Configuration

2 INTRODUCTION
This specification describes the OmniPCX Office Hospitality Link (OHL) dialog between the OmniPCX
Office Hotel driver and a Hotel application, in order to interface the Alcatel-Lucent OmniPCX Office
to this application.
Both the Hotel application and the OmniPCX Office can perform some identical functions. The hotel
application has to manage the consistency of this data. This is out of the scope of this
specification. The OmniPCX Office Hospitality Link allows the synchronization between the
operations made on both application and OmniPCX Office sides.
OmniPCX Office Hospitality Link location

OmniPCX Office
Call Server
CTI Server
V-Mail Server, …
Hotel Configuration links

( Metering thru V24 & PCMan overIP )
PCMan Metering
(overIP)
overIP) (thruV24) OmniPCX Office Hotel driver
• Input : Configuration
• Output : OHL
OmniPCX Office Hospitality Link
Alcatel Application Partner Application :

• Hotel management
PC Windows

3 Physical Link And Protocol
The connection must be initialized by the hotel application, using the OmniPCX Office service port
that is reserved for the hotel interface (port number 2561).
3.1 Acknowledgement on TCP/IP

Any received message must be verified (parity, CRC, length) and a ACK or a NACK must be sent
back immediately (within 25 seconds max.) except for keep alive message.
If the answer is NACK or no answer is received within 25 seconds, the message is destroyed and an
error incident is generated in the OmniPCX Office Hotel Driver “ Global_log_file “.
3.2 TCP/IP connection message

This message is sent by the Hotel Application to initialize the connection.
If the link is disconnected, the Hotel Application must send again a connection message to re-connect
3.2.1 Message format

Length
Field Value Comments
(bytes)
1 STX 1 '0x02' start of text
2 type 1 @ TCP/IP link connection (message type)
3 node id. 4 FFFF message sent by the Hotel Application.
(FFFF character : coded in ASCII)
node number, message sent by the Hotel Driver.
(hexadecimal value, coded in ASCII)
4 ETX 1 '0x03' end of text
Total length msg 7
Note: This message frame contains no CRC field by default. However, to allow compatibility
with some applications the CRC field is an option : with or without CRC field (without is the
implicit as shown).If CRC is enabled, a two character field preceding the "ETX" field is created
and reserved for "CRC".
3.3 TCP/IP keep alive messages

These messages are sent every 30 seconds by both sides.
If the OmniPCX Office Hotel Driver does not receive any “keep alive” message within 60 seconds, the
connection is closed and the hotel application message queued buffer is emptied

Length
(bytes)
2 type 1 $ keep alive (message type)
3 node id. 4 FFFF message sent by the Hotel Application.
(FFFF character : coded in ASCII)
node number, message sent by the Hotel Driver.
(hexadecimal value, coded in ASCII)
Total length msg 7
Note: This message frame contains no CRC field by default. However, to allow compatibility
with some applications the CRC field is an option : with or without CRC field (without is the
implicit as shown).If CRC is enabled, a two character field preceding the "ETX" field is created
and reserved for "CRC".
The keep alive messages are not acknowledged with ACK or NACK messages.

3.4 TCP/IP Link Buffer
An OHL messages buffer is available on the Hotel Driver. The size of this buffer is: 2000 messages.
When this communication buffer is 80 % full, an alarm is automatically generated and a warning
alarm message is reported in the OHL Driver “Global_Log_file”. When this communication buffer
becomes 95 % full, any new incoming message will automatically cause an alarm to be generated
and the deletion of the oldest message in memory.
3.5 Start And End Characters

Any message, except ACK, NACK, XON and XOFF, begins with an "STX" character (value: 0x02) and
ends with an "ETX" character (value: 0x03).
3.6 Longitudinal Control Characters

The last two characters preceding the "ETX" are reserved for the "CRC". It is calculated by making an
"exclusive or" on each character from the STX (excluded) to the "CRC". The result is split into 2 ASCII
characters corresponding to the translation in ASCII of its hexadecimal value.
For example, the one character result corresponding to binary "0001 0011" is split into the 2 ASCII
characters "1" and "3". (See page 21 - 6.1. )
3.7 Field Justification

Except if otherwise specified, every field not completed is right justified and filled up with blank
(ASCII space: value 0x20) character(s), noted in the document: b
3.8 Management
A guest is identified through his "ROOM" (extension) number.
Using this extension number does accounting and management.
If guests want to receive directly their incoming calls, a "DDI” number (direct dial inward) can be
associated to that extension on the OmniPCX Office system.

4 Support for six digit password
From release R820, OXO supports both four (4) and six (6) digits password length for room sets.
To support the new password length (6 digits), new OHL message types are introduced with
password field length as six.
The new message types are used for either four or six digits password.
The new message types are described under section 7.
The old (current) message types are not modified to support existing hotel application.
Hotel application can use the existing message format with four digits password without any
modification.
From the hotel application, for four digits password either new or existing message types can be
used.
For six digits password, new message types has to be used. OLD Driver selects the message type
(new or old message) to be sent to application based on the password length configured in OXO.
If OXO has software version 8.1 or earlier then only “4 digit password” can be used.
If OXO has software version 8.2 and above then 2 possibilities:
 Configuration done in OXO and Partner Application software with “4 digit password” ->
OLD version should be 2.3.5 or higher, and we use the currents frames (A, M, …).
 Configuration done in OXO and Partner Application software with “6 digit password” ->
OLD version should be at least 2.3.6, and we use the new frames (B, N, …).
8.1 or earlier 8.2 and above 8.2 and above

4 digit (4 digit (6 digit
OXO password password) password)
Hotel
Application OLD Driver
8.1 old message* old message* Not possible
8.2 old message* old message* Not possible
8.2 new message# new message# new message#
Note: to use the new message with 4/ 6 digit password, necessary adaptation has to be done
in the existing hotel application(s).

5 Messages from Hotel Driver to Hotel
Application
If the OmniPCX Office does not handle information included in a message, this information is
replaced by the right number of blank character(s).
5.1 SMDR or telephone call ticket

SMDR tickets (written proof metering tickets) are sent at the end of call. Administrative SMDR, can be
differentiated from guest SMDR through "cost center" field (0=administrative sets, 1=room sets, 2
=phone booth).

Length
(bytes)
2 type 1 J SMDR identification (message type)
3 room extension 8 bbbbbbb0 to 99999999 charged extension (room, administration set, …)
4 cost center 4 bbb0 0=administrative set
bbb1 1=room set
bbb2 2=phone booth
bbbb information not available
5 call type 1 0 to Z call type
6 acting ext. 8 bbbbbbb0 to 99999999 acting extension
bbbbbbbb information not available
7 date-time 11 00 00 00 00 00 b to date and time of the beginning of the communication day,
31 12 99 23 59 b month, year, hour minute (no AM/PM management)
8 duration 5 000 00 to 999 59 duration of call in minutes (3 char.) and seconds (2 char.)
and 999 99 999 99 means overflow
9 cost 8 0bbbbbbb or 0.0bbbbb to cost (7 char. + 1 floating point, left justified, number of
99 999 999 digits after floating point described in PM5) or number of
meter pulses. 99 999 999 means overflow
10 trunk group 4 bbbb or XXXX if available provide a trunk number either on 4 characters
number
11 called number 20 0bb...bb to 99.....99
bb...bb information not available in case of assignment charge
12 CRC 2 XOR fields 2 to 11 control characters
Total length msg 74
5.1.2 Notes
 Field 3: “room extension” is right justified. The room extension may include “*”and
“#”characters. By default the system will give the last 4 digits of calling or called
subscriber, In case of numbering plan base on more than 4 digits, please select “User8”
under PM5 metering fields parameter. In case of unanswered incoming calls it is possible
to have a hunt group number instead of a room extension number.
 Field 5: the "call type" has the following values if available (other values may be added
later):
 0 for public network "outgoing call"
 1 for "transfer" of public network outgoing call followed by the transferring extension
number in the acting extension field if available
 3 reserved
 4 for public network "incoming call"
 5 for MTR charge assignment call arising from Booth phone call ; initiator extension
no. is in the acting extension field ( see Note1 )

 5 for booth call; followed by blank (space) characters in the acting extension field
 5 for "other"; the acting extension field contain blank (space) characters
 6 for "transit"
 A for "transfer" of public network incoming call followed by the transferring extension
number in the acting extension
 E for "SO data outgoing call"
 F for "SO data incoming call"
 Field 6: the "acting extension" (if available) is the extension from where the call is placed. It
can be different from the "charged extension" in field 3 (e.g. in case of substitution). The
acting extension may include “*”and “#”characters. By default the system will give the last
4 digits of calling or called subscriber, In case of numbering plan base on more than 4
digits, please select “User8” under PM5 metering fields parameter. In case of unanswered
incoming calls it is possible to have a hunt group number instead of a room extension
number.
 Field 9: VAT not included. Number of digits after floating point depends on system
metering configuration (programmed in PM5 metering screen). The field is left justified
and full with blank if necessary. So if no digit after floating point is configured, the floating
point will not be printed (e.g. for a cost of 45 units : 45bbbbbb if no digit after floating
point and 45.0bbbb if one digit after floating point).
 Field 10: Trunk Number, allows metering ticket correlation (i.e. correlation between booth
phone SMDR and assignment charge SMDR) - available values:
 Lxxx analog trunk (000-xxx) to public network (PSTN)
 Nxxx ISDN basic rate access (000-xxx) to public network (PSTN) or private network
 Pxxx Public or private primary rate access (000-xxx)
 Vxxx IP trunk (000-xxx)
By default metering tickets from the OmniPCX office system provides trunk numbers from
000 to 099, trunk numbers above 099 will appear as “***” (i.e. “N***”, “P***”). Therefore, in
order to get the correct line identification the system installator must select “trunk4”
under PM5 metering fields parameter.
 Field 11: "number called" is left justified. The called number may include "*" and "#"
characters. If the number is over 20 digits the first 20 digits are used.
Note 1: If the PBX hotel feature 'Charge Assignment' is used which results from a Booth phone MTR
call( meter total recall ), then two SMDR frames are generated. One SMDR for the Booth phone call
and the second for the room which has been assigned the charge. To associate these two SMDR’s, it
is necessary to use the date / time and duration fields of the two SMDR frames, as the dialled number
field of the 'Charge assignment' SMDR is empty. The Acting extension field is only completed on the
'Charge Assignment' SMDR and contains the extension no. of the initiator of the MTR call ( i.e.:-
initiator is the extension which allocates the trunk using the MTR feature:
- normally the operator).

5.2 Check-in
The Hotel Driver sends this message to the Hotel Application when a check-in is done by the
integrated application (e.g. From Reception set).

Length
Field Value Com m ents
(bytes)
2 type 1 A guest Arrival (Check-In) message
3 room extension 8 bbbbbbb0 to 99999999 room set extension
4 unused 1 b for compatibility reason.
5 guest name 10 NNNNNNNNNN N = ISO latin character see Annex.
6 unused 8 bbbbbbbb for compatibility reason.
7 unused 2 bb for compatibility reason.
8 set language 1 1 to 4 room set language (one of the 4 languages of the
OmniPCX Office)
9 unused 4 bbbb for compatibility reason.
10 passw ord 4 0000 to 9999 room set password (bbbb = no password proposed)
11 barring 2 00 no outgoing calls authorized
category 01 only local calls authorized
02 only local and national calls authorized
03 all outgoing calls authorized
12 deposit 9 0.0000000 to 99999999. deposit value: 8 characters plus one floating point.
bbbbbbbbb no pre-payment
13 message 1 b no change
w aiting 1 message(s) waiting at the front desk
0 no message waiting at the front desk
14 w ake-up time 4 00 00 to 23 59 wake-up time hour (2 char.) and minutes(2 char.)
bbbb no wake-up programmed
15 w ake-up action 1 b not used
16 do not disturb 1 0 clear DND and forwarding
2 set room extension in DND
1 forward room extension to voice mail
Total length msg 61
5.3 Phone allocation

This message is sent to the Hotel Application after a DDI number is allocated to the guest room, or
DDI number information is requested.

Length
(bytes)
2 type 1 H phone allocation message
4 sub-type 1 D DDI number programmed
5 DDI number 8 bbbbbbbb to 99999999 DDI number (bbbbbbbb = no DDI number)
Total length msg 22

A phone allocation message request is sent by the application to the driver to request a DDI
allocation (4.2.1). This phone allocation message (3.3.1) is the answer (and the acknowledgement):
it gives the DDI number; the sub-type is here always and only “D”.
5.4 Voice mail facilities attribution

Not supported in OmniPCX Office (a mailbox is systematically opened at the check-in phase and
closed at check-out: in fact they are reset at check-in, to permit a consultation from receptionist set in
case of problem).
5.5 Modification
The Hotel Driver sends this message when a modification is done by the integrated application. (E.g.:
Reception set)

Length
(bytes)
2 type 1 M Modification message
000000000 'no change'
bbbbbbbbbb 'clear' the name : return to 'RoomNumber'
OmniPCX Office)
0 'no change'
bbbb 'no change'
11 barring 2 00 to 03 new choice
category bb 'no change'
12 deposit 9 0.0000000 to 99999999. remaining deposit (balance)
13 message 1 b 'no change'
bbbb 'no change'
15 w ake-up action 1 b program wake-up or 'no change'
0 cancel wake-up
b 'no change'
Total length msg 61
The deposit field corresponds to the remaining deposit (balance).

5.6 Check-out
The Hotel Driver sends this message when a checkout is done by the integrated application. (e.g.
Reception set).

Length
(bytes)
2 type 1 D guest Departure (check-out) message
Total length msg 13
5.7 Room status change

Length
(bytes)
2 type 1 C room status Change message
4 status 1 1 or 2 1 the room has been cleaned and is ready
2 the room must be cleaned
5 problem code 3 000 to 999 The problem code of the room : the PBX transmits the
digits dialed by the maid without any interpretation.
(000 means no problem).
Total length msg 17
5.8 Guest telephone account

Length
(bytes)
2 type 1 T guest Telephone account message
4 communications 4 0000 to 9999 Communications: number of effective (charged) outside
number calls
5 cost 9 0.0000000 to 99999999. Cost: total expense (8 characters plus one floating point).
6 total deposit 9 0.0000000 to 99999999. Total of "deposits": (8 characters plus one floating point)
corresponding to the original (or reset) amount plus the
added values.
7 unused 9 bbbbbbbbb compatibility reason
Total length msg 44

5.8.2 Notes
 Field 5: VAT not included.
5.9 Data transfer

Not supported in OmniPCX Office.
5.10 Interactive data transfer

Not supported in OmniPCX Office
5.11 Specific data transfer

5.12 Wake-up events

If a wake-up problem occurs or for any observed wake-up event, the PABX can inform the Hotel
Application.

Length
(bytes)
2 type 1 P PBX data transfer
4 sub-type 1 W Wake-Up (message sub-type)
5 unused 2 bb unused (presence for compatibility)
6 cause 1 A Acknowledge
N Not acknowledge : Free
B Not acknowledge : Busy
O Set Inaccessible (OUT OF ORDER)
P Programmed (wake-up)
M Not available (modification=programmed)
C Cancelled (wake-up)
R Not available (programming rejected)
7 unused 1 b unused (presence for compatibility)
8 event date 6 00 00 00 to 31 12 99 even date (e.g. wake-up cancellation date)
9 event time 4 00 00 to 23 59 even time
10 originator 5 bbbbb programmed from extension or information not available
Obbbb programmed from operator/receptionist (not available)
Rbbbb programmed from room service (not available)
11 wake-up time 4 00 00 to 23 59 wake-up time hour (2 char.) and minutes(2 char.)
bbbb 'no change'
12 unused 1 b unused (presence for compatibility)
Total length msg 49
5.13 Voice-mail events


5.14 Guest data re-initialization
This message is the positive answer to a re-initialization request.
5.14.1 Full re-initialization message format

Length
(bytes)
2 type 1 U re-initialization answer message
4 sub-type 1 F Full re-initialization on going
E End of re-initialization (last message, or only message)
7 guest name 10 NNNNNNNNNN programmed name.
OmniPCX Office)
12 password 4 0000 to 9999 room set password
13 barring category 2 00 to 03 barring value
15 message 1 0 no message waiting at the front desk
waiting 1 message(s) waiting at the front desk
17 wake-up action 1 b unused
18 do not disturb 1 0 no DND and forwarding programmed
20 unused 5 bbbbb for compatibility reason.
22 problem code 3 000 to 999 The problem code of the room : the PBX transmits the
digits dialed by the maid without any interpretation.
23 unused 11 bbbbbbbbbbb for compatibility reason.
Total length msg 96
If there is are no guests checked-in, the room number is set to blanks and the sub-type to ‘E’.
Sub- type E:
 If you have 3 guests checked-in: you will received 2 messages with sub-type “F” and the last
message with sub-type “E”;
 If you have only one guest checked-in: you will received only message with sub-type “E”;
 If you have no guest checked-in: you will received only message with sub-type “E”;
Between the message “re-init request” and the last message “guest data-base reinit” (sub-type “E”)
the application has to wait: no other message can be sent.

5.14.2 Partial re-initialization message format
There is no difference between full and partial re-initialization except the volume of data transferred.
Length
(bytes)
2 type 1 U re-initialization answer message
4 sub-type 1 P Partial re-initialization on going
O End of re-initialization (last message, or only message)
Total length msg 26
If there are no guests checked-in, the room number is set to blanks and the sub-type to ‘O’.
sub-type ‘O’:
 If you have 3 guests checked-in: you will received 2 messages with sub-type “P” and the last
message with sub-type “O”;
 If you have only one guest checked-in: you will received only message with sub-type “O”;
 If you have no guest checked-in: you will received only message with sub-type “O”;
Between the message “re-init request” and the last message “guest data-base reinit” (sub-type “O”)
5.15 Dynamic suite

5.16 Extended SMDR

5.17 Reply
This message is sent from the Hotel Driver to the Hotel Application as a layer 3 acknowledge:
 To accept a command with a restrictive warning
 To refuse a command with the reason
If a previous computer command was handled correctly, and if information or warnings are not
necessary, the Hotel Driver does not send any "reply".

Length
(bytes)
2 type 1 R Reply (message type)
5 action 1 I Check In accepted
J Check In refused
O Check Out accepted (not used)
P Check Out refused
M Modification accepted
N Modification refused
A Phone Allocation accepted
B Phone Allocation refused
Q Interrogation accepted (not used)
R Interrogation refused
T Re-initialisation refused
6 reason 1 A Room already allocated
G Invalid number
O Room set out of service
R Invalid room extension number (not used)
U Unavailable room extension
M Not consulted message (in mailbox or at message desk):
Non available feature, messages are deleted on Check
Out
J Non available feature
K Wrong message
Q Unreachable database (the PBX doesn’t answer)
T Other
Total length msg 19
 List of possible Reply with room extension management (non exhaustive):

Reply to check-in
Refuse:
action = ‘J',
reason =
‘R’ Invalid room extension number (out of range)
‘A’ room already checked-in
‘Q’ the PBX doesn’t answer – bad hostname, unreachable system,
wrong password, OmniPCX Office PCMan connection busy (PM5,
MMC, 4760…).
 Accepted:
action = ‘I',
reason = ‘b’
Reply to modification
Refuse:
action = ‘N',
reason =
‘A’ room not checked-in
‘P’ Invalid or unavailable guest password ("INVb" in password field)
Unavailable value with OmniPCX Office
MMC, 4760…).

 Accepted:
action = ‘M',
reason = ‘b’
Reply to check-out
Refuse:
action = ‘P',
reason =
MMC, 4760…).
Reply to interrogation
Refuse:
action = ‘R',
reason =
MMC, 4760…).
5.18 Message acknowledgement

1 character ACK or NACK
5.19 Control characters

1 character XON or XOFF

6 Messages from Hotel Application to Hotel
Driver
6.1 Check-in
Length
(bytes)
2 type 1 A guest Arrival (Check-In) message
OmniPCX Office)
category 01 only local calls authorized
bbbb 'no change'
0 cancel wake-up
Total length msg 61
Deposit, on OmniPCX Office only fixed deposit available. If a floating-point deposit is transmitting,
the floating part will not be taking into account.
Possible cause of ‘Check-in’ reject, the check-in message will be refused by a ‘reply’ in case of:
- Invalid room extension number (out of range)

- Room already checked-in
- A PBX doesn’t answer response due to bad hostname, unreachable system,
wrong password or OmniPCX Office PCMan connection busy (PM5, MMC,
4760…).

6.2 Phone allocation
This message is sent by the Hotel Application to request the allocation of, or to program, a DDI
(Direct Dial In) number to the guest room.

Length
(bytes)
2 type 1 H phone allocation message
4 sub-type 1 R DDI number request
I DDI number information (to read an already allocated
number)
5 unused 8 bbbbbbbb for compatibility reason
Total length msg 22
Possible cause of ‘Phone Allocation’ reject, the ‘Phone Allocation’ message will be refused by a
‘reply’ in case of:

4760…).
6.3 Voice mail facility attribution

Not supported in OmniPCX Office (a mailbox is systematically and automatically allocated at check-
in).

6.4 Modification
Length
(bytes)
2 type 1 M Modification message
000000000 'no change'
OmniPCX Office)
0 'no change'
bbbb 'no change'
category bb 'no change'
12 deposit 9 0.0000000 to 99999999. force this value
+.0000000 to +9999999. add this value to the current deposit
-.0000000 to -9999999. subtract this value to the current deposit
bbbbbbbbb 'no change'
bbbb 'no change'
0 cancel wake-up
b 'no change'
Total length msg 61
Possible cause of ‘Modification’ reject, the modification message will be refused by a ‘reply’ in case
of:

- Room not checked-in
- Invalid or unavailable guest password
4760…).

6.5 Check-out
Length
(bytes)
2 type 1 D guest Departure (check-out) message
Total length msg 13
If the room extension is busy with an external outgoing call, when the Hotel Driver resets the pre-
payment value, depending on the PBX configuration the call will be immediately cut or not. No
indication is given to the Hotel Application: Reply message (parameters = “Ob”).
On checkout the following elements are set:
 Room State: Free
 Room clean status: Unclean
 Voice Mailbox: Content erased
 Personal code: Reset
 Wakeup call request: Disabled
 Do Not Disturb: Disabled
 Guest Name: set to “RoomNumber”
 Allocated DDI: Free
Possible cause of ‘Check-out’ reject, the checked-out message will be refused by a ‘reply’ in case of:

4760…).
6.6 Interrogation
The hotel Application uses this command to request guest telephone accounts.

Length
(bytes)
2 type 1 I Interrogation message
Total length msg 13
6.7 Data transfer

Not used in OmniPCX Office.
6.8 Night audit request


6.9 Re-initialization request
Length
(bytes)
2 type 1 Z Re-Initialization message
3 room extension 8 bbbbbbb0 to 99999999 to have a specific room state
bbbbbbbb to have all check-in room state
4 initialization type 1 F full guest data are required
P partial guest data are required
Total length msg 14
The Hotel Application can ask the PABX to send all the data it has on a specific guest or on every
checked-in guests/extensions.
The Re-initialization request is mandatory, otherwise de-synchronization between the
computer and the PABX occurs, the Hotel Application must use this command to retrieve the PABX
guest room database information, then modify the de-synchronized information. It must avoid
sending a succession of "Check-out" then "Check-in" commands.
The computer must wait up to the end of the database re-initialization (reception of a re-initialization
message with a sub-type value ‘E’ (End) for full data, and ‘O’ for partial data), before sending any
new command.
Possible cause of ‘Check-out’ reject, the checked-out message will be refused by a ‘reply’ in case of:
- Invalid room extension number (out of range) (in case of specific room state re-
initialization request)
4760…).
6.10 Dynamic suite

6.11 Message acknowledgement

1 character ACK or NACK.
6.12 Control characters

1 character XON or XOFF.

7 New messages for support of 6 digits
password
7.1 Messages sent from Hotel driver to Hotel Application
7.1.1 Check-in message format with six bytes password length

The new message introduced is similar to the existing check-in message except, change in ‘type’
value and change in length of password field
Fiel Length
Value Comments
d (bytes)
2 type 1 B guest Arrival (Check-In) message

OmniPCX Office)
10 password 6 bb0000 to bb9999 room set four digit password (bbbbbb = no password
proposed)
000000 to 999999 room set six digit password (bbbbbb = no password
proposed)
category
01 only local calls authorized
15 wake-up action 1 b not used
Total length msg 63

7.1.2 Modification message format with six bytes password length
The new message introduced is similar to the existing Modification message except, change in ‘type’
value and change in length of password field.
Length
(bytes)
2 type 1 N Modification message

000000000 'no change'
OmniPCX Office)
0 'no change'
proposed)
proposed)
category
bb 'no change'
bbbb 'no change'
15 wake-up action 1 b program wake-up or 'no change'
0 cancel wake-up
b 'no change'
Total length msg 63

7.1.3 Full re-initialization message format with six bytes password length
The new message introduced is similar to the existing Full re-initialization message except, change in
‘type’ value and change in length of password field.
Length
(bytes)
2 type 1 V re-initialization answer message
4 sub-type 1 F Full re-initialization on going

E End of re-initialization (last message, or only
message)

7 guest name 10 NNNNNNNNNN programmed name.
OmniPCX Office)
12 password 6 bb0000 to bb9999 room set four digit password
000000 to 999999 room set six digit password
13 barring 2 00 to 03 barring value
14 category
deposit 9 0.0000000 to 99999999. remaining deposit (balance)
15 message 1 0 no message waiting at the front desk
17 wake-up action 1 b unused
18 do not disturb 1 0 no DND and forwarding programmed
20 unused 5 bbbbb for compatibility reason.
22 problem code 3 000 to 999 The problem code of the room : the PBX transmits
the digits dialed by the maid without any
interpretation.
23 unused 11 bbbbbbbbbbb for compatibility reason.
Total length msg 98

If there is are no guests checked-in, the room number is set to blanks and the sub-type to ‘E’.
Sub- type E:
 If you have 3 guests checked-in: you will received 2 messages with sub-type “F” and the last
message with sub-type “E”;

 If you have only one guest checked-in: you will received only message with sub-type “E”;
 If you have no guest checked-in: you will received only message with sub-type “E”;
7.1.4 Partial re-initialization message format with six bytes password length
The new message introduced is similar to the existing Partial re-initialization message except, change
in ‘type’ value and change in length of password field.
Length
(bytes)
2 type 1 V re-initialization answer message
4 sub-type 1 P Partial re-initialization on going

O End of re-initialization (last message, or only
message)
6 password 6 bb0000 to bb9999 room set four digit password password

000000 to 999999 room set six digit password password
Total length msg 28
If there are no guests checked-in, the room number is set to blanks and the sub-type to ‘O’.
sub-type ‘O’:
 If you have 3 guests checked-in: you will received 2 messages with sub-type “P” and the last
message with sub-type “O”;
 If you have only one guest checked-in: you will received only message with sub-type “O”;
 If you have no guest checked-in: you will received only message with sub-type “O”;
Between the message “re-init request” and the last message “guest data-base reinit” (sub-type “O”)

7.1.5 Reply Message format with six bytes password length
The message is similar to existing Relpy message except, change in ‘type’ value and change in
length of the password field.
Length
(bytes)
2 type 1 S Reply (message type)
3 room extension bbbbbbb0 to 99999999 room set extension
8
4 password bb0000 to bb9999 room set with four digit password
6 000000 to 999999 room set with six digit password
5 action 1 I Check In accepted
J Check In refused
O Check Out accepted
P Check Out refused
M Modification accepted
N Modification refused
A Phone Allocation accepted
B Phone Allocation refused
Q Interrogation accepted
R Interrogation refused
T Re-initialisation refused
6 reason 1 A Room already allocated or Room not allocated
G Invalid number
O Room set out of service
R Invalid room extension number (not used)
U Unavailable room extension
M Not consulted message (in mailbox or at message
desk): Non available feature, messages are deleted
on Check Out
J Non available feature
K Wrong message
Q Unreachable database (the PBX doesn’t answer)
T Other
Total length msg 21

7.2 Messages sent from Hotel Application to Hotel driver
7.2.1 Check-in message format with six bytes password length

The message is similar to existing check-in message except, change in message ‘type’ value and
change in password field length.
Fiel Length
Value Comments
d (bytes)
2 type 1 B guest Arrival (Check-In) message

OmniPCX Office)
10 password 6 bb0000 to bb9999 room set four digitpassword with (bbbbbb = no
password proposed)
proposed)
category
01 only local calls authorized
15 wake-up action 1 b not used
Total length msg 63
Deposit, on OmniPCX Office only fixed deposit available. If a floating-point deposit is transmitting,
the floating part will not be taking into account.
Possible cause of ‘Check-in’ reject, the check-in message will be refused by a ‘reply’ in case of:
- Room already checked-in

4760…).

7.2.2 Modification message format with six bytes password length
The message is similar to existing Modification message except, change in message ‘type’ value and
change in password field length.
Length
(bytes)
2 type 1 N Modification message

000000000 'no change'
OmniPCX Office)
0 'no change'
proposed)
proposed)
category
bb 'no change'
bbbb 'no change'
15 wake-up action 1 b program wake-up or 'no change'
0 cancel wake-up
b 'no change'
Total length msg 63
Possible cause of ‘Modification’ reject, the modification message will be refused by a ‘reply’ in case
of:
- Invalid or unavailable guest password
4760…).

8 Appendix A: Example of CRC calculation
For the following message:
# 1 2 3 4 5 6 7 8 9 10
Value ‘STX’ D b 3 9 5 6 crc1 crc2 ‘ETX’
The CRC is calculated from field 2 to field 7.
6Dh is the result of XOR calculation on the following bytes: 44h(D), 20h(b), 33h, 39h, 35h, 36h.
0100 0100 XOR 0010 0000 = 0110 0100 (44h XOR 20h = 64h)
0110 0100 XOR 0011 0011 = 0101 0111 (64h XOR 33h = 57h)
0101 0111 XOR 0011 1001 = 0110 1110 (57h XOR 39h = 6Eh)
0110 1110 XOR 0011 0101 = 0101 1011 (6Eh XOR 35h = 5Bh)
0101 1011 XOR 0011 0110 = 0110 1101 (5Bh XOR 36h = 6Dh)
This result is then split into the 2 two ASCII characters 6 (36h) and D (44h).

9 Appendix B: ISO 8859-1 (or iso latin-1)
character set
0 1 2 3 4 5 6 7 8 9 A B C D E F
2 ! ” # $ %& ´ ( ) * + , - . /
3 0 1 2 3 4 5 6 7 8 9 : ; < => ?
4 @A B C D E F GH I J K L MNO
5 P Q R S T U VWX Y Z [ \ ] ^_
6 ` a b c d e f g h i j k l m n o
7 p q r s t u v w x y z { | } ~
8
A ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ - ® ¯
B ° ± ² ³ ´ µ ¶ . ¸ ¹ º » ¼½¾ ¿
C À Á Â Ã Ä ÅÆ Ç È É Ê Ë Ì Í Î Ï
D ÐÑÒÓÔÕÖ×ØÙ Ú Û Ü Ý Þ ß
E à á â ã ä åæ ç è é ê ë ì í î ï
F ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ
Characters not available on OmniPCX Office Reflexes sets. TM
They have to be replaced with a character as close as possible
End Of Document


OmniPCX Office OHL API Developer Guide Ed2.1 PDF

Uploaded by

Copyright:

Available Formats

OmniPCX Office OHL API Developer Guide Ed2.1 PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OmniPCX Office OHL API Developer Guide Ed2.1 PDF

Uploaded by

Copyright:

Available Formats

OmniPCX Office Hospitality Link

API Developers Guide

Platform Alcatel-Lucent OmniPCX Office

Revision Edition 2.1 – November 2013

Abstract This specification describes the OmniPCX Office Hospitality Link

Alcatel-Lucent Application Partner Program

1 ABOUT THIS GUIDE .............................................................................................................................. 6

AAPP – OHL API Developers Guide Edition 2.1 – Page 2

AAPP – OHL API Developers Guide Edition 2.1 – Page 3

Edition 1 - June 04 Creation of the document

Edition 1.1 - September 04 Update regarding R1.6.0

Edition 1.2 - April 05 Update regarding R1.7.0

Edition 1.3 - June 05 Update regarding R1.8.0

Edition 1.4 - August 09 New logos.

 [1] OHL Driver Installation & Configuration

OmniPCX Office OHL

Copyright ® 2012 by Alcatel-Lucent.

AAPP – OHL API Developers Guide Edition 2.1 – Page 4

AAPP – OHL API Developers Guide Edition 2.1 – Page 5

1.2 What This Guide Tells You

1.3 TERMINOLOGY – DEFINITIONS

AAPP – OHL API Developers Guide Edition 2.1 – Page 6

OmniPCX Office Hospitality Link location

Hotel Configuration links

OmniPCX Office Hospitality Link

Alcatel Application Partner Application :

AAPP – OHL API Developers Guide Edition 2.1 – Page 7

3.1 Acknowledgement on TCP/IP

3.2 TCP/IP connection message

3.2.1 Message format

3.3 TCP/IP keep alive messages

3.3.1 Message format

AAPP – OHL API Developers Guide Edition 2.1 – Page 8

3.5 Start And End Characters

3.6 Longitudinal Control Characters

3.7 Field Justification

AAPP – OHL API Developers Guide Edition 2.1 – Page 9

If OXO has software version 8.2 and above then 2 possibilities:

8.1 or earlier 8.2 and above 8.2 and above

AAPP – OHL API Developers Guide Edition 2.1 – Page 10

5.1 SMDR or telephone call ticket

5.1.1 Message format

AAPP – OHL API Developers Guide Edition 2.1 – Page 11

AAPP – OHL API Developers Guide Edition 2.1 – Page 12

5.2.1 Message format

5.3 Phone allocation

5.3.1 Message format

AAPP – OHL API Developers Guide Edition 2.1 – Page 13

5.4 Voice mail facilities attribution

5.5.1 Message format

AAPP – OHL API Developers Guide Edition 2.1 – Page 14

5.6.1 Message format

5.7 Room status change

5.8 Guest telephone account

AAPP – OHL API Developers Guide Edition 2.1 – Page 15

5.9 Data transfer

5.10 Interactive data transfer

5.11 Specific data transfer

5.12 Wake-up events