Knowlege base

Product Configuration

Article ID: 161
Last updated: 01 Jul, 2020

Warning: you must install and configure the Application Suite before being able to configure the single applications.
Please go through the AppSuite Deployment, Main Configuration, and User Management sections before reading on.

To fully configure Hotel Pack you need to:

  • Define the PBX numbering plan
  • Complete the Application Suite common configuration
  • Create the room list through the users management web interface
  • Configure Billy Blue's 4
  • Configure StoneLock
  • Configure SSAm
  • Configure Hotel Link
  • Configure CuCM for the Wakeup service and Room Maid status service
  • Optionally, add IAS users for the hotel staff
  • Activate the applications licenses (within 30 days from installation)
  • Evaluate the features without a PMS connection
  • When the PMS interface IP address and port are available, configure the PMS connection

PBX Numbering Plan

The most important concept in Hotel Pack is:

1 room = 1 extension number

The extension number is what is called "Directory Number" in Cisco CallManager documentation. If you have more than one phone in an hotel room, they must share the same line (shared lines).

Partitions are not supported, i.e. they are ignored. So the numbering plan must be flat, meaning no overlapping numbers.

Globalized Numbering Plan (i.e. +E.164 dial plan configuration) including the symbol '+' is not supported for the rooms.

On the PMS, the line number must match the room number.

Only numbers are supported as room names. Therefore, rooms having different names (like "Royal Suite") should be renamed in the PMS with a (unique) numeric id.

On the CuCM the extension number must match the room number.

For instance, room 202 on the PMS must be associated to line 202. On CuCM, you should register one phone with the DN 202. Any secondary phone in the room must share the same DN (202).

Analog phones are supported with some limitations: the guest name on the line and MWI for voicemail are not available.

Multi-Property configuration

In order to support multi-property organizations (that is multiple hotels sharing the same Cisco CallManager cluster) a property prefix number can be used to match each room with the associated directory number defined in CUCM. 

As a sample, suppose you have to manage two properties (Hotel Panorama and Hotel Majestic) having an overlapped room numbering schema, for instance, both of them having a room '201'. This scenario can be supported:

  • Defining in the PMS of each property the regular room number, that is '201' with phone number 201.
  • Defining in the CUCM the directory numbers in a hyerarchical format, that is, using a common prefix number for all extensions beloging to the same property. In the sample above it could be:
    • Hotel Panorama:  directory number 1201 for room 201.
    • Hotel Majestic: directory number 2201 for room 201.
  • Defining in the Application Suite, two properties each one with a different property prefix . In the sample above:
    • '1' for Hotel Panorama
    • '2' for Hotel Majestic
  • Defining in the Application Suite each room with a username equal to its phone extension. In the sample above, you should define:
    • a room with username '1201', having Internal phone number 1201 (room 201 of Panorama)
    • a room with username '2201', having Internal phone number 2201 (room 201 of Majestic)

Please, notice that this kind of configuration:

  • still requires a flat (not overlapping) global numbering plan in the CUCM
  • does not permit to have in the same property phone extensions starting by different digits
  • permits to manage also single-property scenarios where the room numbers in the PMS are one or more digits shorter than the corresponding CUCM directory numbers or, to be more precise , they are the same number unless a common prefix.  

IMPORTANT: if you are going to use the AppSuite without a PMS, please specify a dummy property without any prefix and pointing to a fake IP address.

Global Application Suite Configuration

Ensure you completed all the Application Suite global configuration steps, including all the system parameters, monitoring, TAPI, AXL. Presence is not required.

Application Suite Authentication

In a standard Hotel Pack installation, the authentication type is not meaningful for the rooms. Administration is usually done by the global administrator whose credentials (admin/admin) are created during setup.

For this reason, the suggested authentication type is "Application Suite".

AXL setup and device association with the rooms

Hotel Link needs AXL access to CuCM to change the phone display name and clear the call history. Ensure you complete all the AXL configuration steps, let the AXL service work for some minutes, then check the result through the Detected phones and devices web page. It can be displayed by clicking Admin, System Parameters, IP Telephony System Parameters, Detected phones and devices.

Note: Analog phones are not displayed in the Detected phones and devices web page

TAPI and TSP configuration

The recommended blocking technology for the room phones is ECC/Curri. Nevertheless, TSP installation is required if you want to integrate Imagicle Attendant Console and to display the lock message on some IP phone model. For this reason, installing Cisco TSP is recommended.

Users List Synchronization

If your Hotel Pack only manages room phones and a few phones for the staff, you do not need User synchronization.

If you need to provide services for the staff, you'll need to create standard users for them. In this case, you can automatically create the users list via user synchronization and select the appropriate Authentication setting.

Network Configuration

Ensure the firewall is configured as described in the Network Setup page of this guide, which includes Hotel Link.

In particular, the PMSLink2 service must be able to communicate via TCP with the PMS interface.

Creating the room list through the users management web interface

Imagicle Hotel Link must know the list of the room configured in the PMS. You can manage the features associated to a room through the Users Management interface. You can add a new room to the configuration by clicking the "Create room" link.

Here is the list of the mandatory properties for a room:

  • Username: the room ID as defined in the PMS. This is usually equal to the room number. E.g. 201.
    For multi-property configurations the room number must include the property unique prefix.
  • Password: anything you like. You should never access the web interface as room. E.g. MyPassword
  • Pin: empty
  • First Name: empty
  • Last Name: empty
  • First extension number: this is the line number associated to the room phone or phones. This must be equal to room ID. E.g. 201
    For multi-property configurations the room number must include the property unique prefix.
  • Department: Name of the Hotel or property. E.g. Hotel Bellavista
  • Enable billing for first extension number: Checked (true)
  • Enable billing for voicemail number: Unchecked (false)
  • Enable billing for fax number: Unchecked (false)
  • Number of masked digits in billing: 0 (must always be 0)
  • Voicemail number: must match the number configured in the PBX. E.g. 4201
  • Do not keep sent voicemails: Unchecked (false)
  • Published directory number: this is used by the Attendant Console and Speedy Enterprise. Set it to the room line number. E.g. 201
  • Disable caller lookup on phone: Checked (true)
  • Lock phone: Unchecked (false)
  • Lock phone administratively: Checked (true)

Once the room has been added to the configuration, it can be searched and displayed in the Room and Guests web page.

A room cannot share the same first extension number with another room or user. A common mistake is to create a standard user instead of a room. Users are not displayed in the Rooms and Guests web page, and are not linked to the PMS. Once created, a IAS user cannot be turned into a room, so it must be deleted and a new room created in its place.

Importing the room list from a CSV file

You can import the room list from a CSV file as you would with a standard users list. You download the template, fill it with your favorite application, and save it as a CSV file. The only difference is that the lines which represent "rooms" in the CSV file have the IsRoom column value set to 1.

For general concepts on how to populate the users list through a CSV file, please refer to the general section of this guide.

After importing the list, please verify that the rooms were correctly imported by using the "Rooms and Guest" web page. If a room is not displayed in that web page, it has been created as a standard user. The user must be removed, the CSV file must be fixed, and importation must be repeated.

Warning: after importing the room list from a CSV file, you must restart the StoneLock service.

Adding IAS users for the hotel staff

You may want to enable other Application Suite services for the staff members, such as Attendant console, IVR, ACD, FAX, Corporate Directories, Call Recording and more. Those services are not included in Hotel Pack and require separate licenses.

In this case, you should create one standard IAS user for each person. Please refer to the specific application administration guide.

Configuring Imagicle Billing

Hotel Link relies on Billy Blue's 4 to calculate the call costs, so it must be fully configured and tested before configuring Hotel Link. Please refer to Billy Blue's 4 administration guide.

When configuring Billy Blue's 4, please mind the following:

  • Only calls that have a cost will be posted (that is, calls which are Outgoing and Answered). So configure Billy Blue's to discard internal calls, to save database and CPU resources. You should activate internal calls processing only if advanced call analysis is explicitly required by the customer.
  • The number of calls placed from the hotel rooms is usually low. When configuring the call check interval for the Recorder service, the recommended value is 30 seconds.
  • Calls older than 20 minutes are discarded. For this reason, it is mandatory that the Imagicle Application Suite server time and the PBX time are aligned. Usage of a NTP service is recommended.
  • Calls with a wrong date and time are not reported in the Hotel web interface, even if they are displayed in Billy Blue's home page. Please double check the gateway time zone setting on the PBX.
  • In the tariff, make sure emergency calls have no cost.
  • PMS protocols do not include currency information. Make sure you create a tariff with costs calculated in the currency of the country where the hotel is located.
  • PMS protocols do not support masking digits in the called number. This feature might be provided by the PMS on the guest folio. In the IAS room configuration, always set "Number of masked digits in billing" to 0.
  • PMS protocols do not support timezone information. Call begin time always refer to the Hotel timezone. Make sure the IAS server timezone is the same as the Hotel timezone.

When testing the call costs posting hotel feature, please keep in mind:

  • Any cost lesser than 0.01 is not posted to the PMS.
  • Costs are sent to the PMS almost in real time, that is, within 3 minutes from the moment the call is placed.
  • Imagicle Billing license limit during the 30 days free evaluation period is 250 extensions. Do not use the free evaluation with more than 250 rooms and users.
  • Call details other than the call cost, such as the called number and the call duration, are sent to the PMS only if the connection protocol (FIAS, UHLL...) allows it

Proceed to Hotel Link configuration only when you can see Outgoing Answered calls with a cost displayed in Billy Blue's web home page.

Configuring Phone Lock

Hotel Link locks the room phone by changing the StoneLock "Lock phone administratively" flag, to prevent the room phones to call external numbers when the room is not occupied by guests. This means the StoneLock application must be fully functional and tested before continuing with Hotel Link configuration. Please refer to StoneLock administration guide for the configuration steps.

StoneLock can work through two blocking technologies, TAPI and ECC/Curri. ECC/Curri is recommended because it allows easier troubleshooting and has a lower impact on the system performance.

You should create an ECC profile which is involved when the room phones try to reach the PSTN. The recommended configuration is through Translation Patterns. Route Patterns call the ECC profile each time a digit is typed on the phone, slowing call processing. ECC profiles for Directory Numbers are triggered only for incoming calls.

Configuring the Annunciator to play a message to let the caller know the call is locked is highly recommended, and simplifies the application testing.

When configuring StoneLock parameters:

  • Remember to properly set the numbering parameters in the Application Suite System Parameters. They are needed to tell internal numbers from external numbers.
  • On the room phones, do not configure the Phone Lock XML service, or the Automatic Lock when Idle url
  • Remember to configure the list of the emergency numbers in the "List of allowed numbers when phones are locked" on the Phone Lock -> Global Settings web page.
  • If you are using the TAPI technology, and redirecting the locked calls to a service number playing the "phone is locked", make sure this number is included in the "List of allowed numbers when phones are locked" on the Phone Lock -> Global Settings web page.

StoneLock also clears the Call history at checkout, provided that Imagicle AXL service is running and configured, as described in the Main Configuration, System Parameters section of the Application Suite System guide.

Continue Hotel Link configuration only when you are able to administratively lock/unlock a phone from the web interface.

Configuring Voicemail

SSAm is required to allow the guests to receive personal messages, left from internal phones (such as the reception) or from external callers if DID is available.

It must be fully functional and tested before continuing with Hotel Link configuration. Please refer to SSAm administration guide for the configuration details.

SSAm configuration is pretty standard. You might want to customize the default welcome message from the web interface.

When used in a room, the voicemail IVR does not ask for a PIN to listen to the messages. If needed, the guest could set a personal PIN number through the voicemail IVR. The pin is removed at checkout.

The IVR language is the Application Suite default language you choose during setup. To change the IVR language for a specific room, open the room configuration in the Users Management web interface, and enter the language code in the web interface. Warning: the language is not reset at checkout.

If you need the concierge to be notified when a voicemail message has been left on a room IVR, go to the room configuration is Users Management. Fill the voicemail address with the reception email address (e.g. Make sure "do not keep sent voicemails" is not checked.

Configuring Hotel Link

Hotel Link does not require any additional configuration, if you followed the directions above.

Configuring CuCM for Hotel Link

Provided you have already configured the PBX for other IAS applications (SSAm, Billy Blue's 4, StoneLock), CuCM configuration for Hotel requires just another SIP trunk and a route pattern.

The SIP trunk is need by the wakeup service to call the room phones. The same SIP trunk is used to reach the Room Maid status IVR from the room phones. The route pattern is needed to assign a number to the maid status service.

CuCM configuration for Hotel Link is described in the dedicated page in this guide.

Activating the applications licenses

If you already bouth the product, activate it through the Admin -> Licenses web page. More details on Hotel Pack licensing can be found on the License Activation page of this guide.

Hotel Pack can also evaluated for free for 30 days. During evaluation, you can configure a maximum of 250 rooms/users.

Evaluating Hotel Pack without a PMS connection

The PMS connnection is not mandatory to test Hotel Pack features. It can be done at a later time, or in advance.

All Hotel Pack features can be tested though the IAS web interface, with the help of two IP phones registered to the PBX, one representing a room, and the other representing the reception.

The tests are detailed in the Troubleshooting section of this guide.

When the actual PMS configuration is available, the tests should be repeated issueing commands from it.

Configuring the PMS connection

When the PMS interface IP address and port are available, you can easily configure the PMS connection by the Hospitality -> Property settings web page.

PMS connection is provided by Imagicle PMSLink2, included in the Application Suite. PMSLink2 always acts as a TCP client towards the PMS interface. The PMS interface must be configured as a TCP server.

The PMS vendor personnel will let you know the PMS interface IP address and port, and supported connection protocol.

Just enter the data in the web page and press the Save button. PMSLink2 will be automatically restarted. From the moment the IP address is available, it will try to connect to the PMS interface.

Tip: try to reach the PMS interface via TELNET to make sure no firewall is blocking the communication.

Receiving a Database Sync

A Database Sync is the process of sending the current occupation state (occupied or free) and guest name from the PMS to Hotel Pack, for each room.

This operation, when available, should be started from the PMS interface by the vendor personnel.

Receiving a Database Sync requires that all the rooms were configured on the Application Suite in Users Management.

Fine tuning Imagicle Monitoring Service

Whenever a PMS command for a room X, such as a check-in request, is issued by the PMS interface towards Hotel Link, a lookup is made in the IAS room list. If the room X cannot be found, an alert is recorded by the Monitoring Service in the IAS event list.

Checking the Monitoring Service Event History web page for errors can be an effective troubleshooting.

Unfortunately, it is a common practice to define extra "virtual" rooms on the PMS. The PMS messages for those rooms will be sent to Hotel Link, even if they should be ignored. Those messages will always trigger an alert and will be recorder in the Monitoring service Event History.

You may want to disable email notification for those alerts.

Article ID: 161
Last updated: 01 Jul, 2020
Revision: 30
Views: 1987
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Hotel Link - PMS Interface Module     PBX Configuration