3cx_hotelusermanual_A9RF298

7/31/2019 3cx_hotelusermanual_A9RF298

1/39

UserManual3CXHotelModule

Version2


2/39

Copyright2011,3CXltd.

http://www.3cx.com

http://www.3cx.com/blog

http://www.facebook.com/3CXPhoneSystem

E-mail:[email protected]

Informationinthisdocumentissubjecttochangewithoutnotice.Companiesnamesand

data used in examples herein are fictitious unless otherwise noted. No part of this

documentmaybereproducedortransmittedinanyformorbyanymeans,electronicor

mechanical,foranypurpose,withouttheexpresswrittenpermissionof3CXLtd.

3CXPhoneSystemforWindowsiscopyrightof3CXLtd.

3CXisaregisteredtrademark,and3CXPhoneSystemforWindowsandthe3CXlogo

aretrademarksof3CXLtdinEurope,theUnitedStatesandothercountries.

Version2.1Lastupdated19October2011


3/39


4/39

TableofContents

Introduction.....................................................................................................................................7Whatisthe3CXHotelModule?................................................................................................7Components...............................................................................................................................7OperationsandFunctionsPerformedbythe3CXHotelModule..............................................8OperationsOnCheckIn........................................................................................................8CheckOutOperations...........................................................................................................8DoNotDisturb(DND)...........................................................................................................8Wake-upCalls.......................................................................................................................8Billing.....................................................................................................................................8

HowItWorks..............................................................................................................................9Installing3CXHotelModule.........................................................................................................11DeploymentConsiderations.....................................................................................................11SystemRequirements..............................................................................................................11InstallingtheSoftware..............................................................................................................11Activatingthe3CXHotelModule.............................................................................................12CreatingaWakeUpCallDR...................................................................................................12AutomaticWakeUpServiceExtension...................................................................................14ConfiguringtheMiniBarFeature.............................................................................................14

UsingtheHotelModuleWebInterface........................................................................................17Introduction..............................................................................................................................17FunctionsAvailable..................................................................................................................17CheckingInGuests.............................................................................................................17CheckingOutGuests..........................................................................................................18SettoDoNotDisturb..........................................................................................................18SchedulingaWakeUpCall................................................................................................19BlockExternalCalls............................................................................................................20ViewingtheCallsMadebyaGuest....................................................................................20SetRoomStatusbyPhone.................................................................................................20EnteringMinibarUsage.......................................................................................................21

HotelSoftware/PMSIntegration.................................................................................................23Introduction..............................................................................................................................23


5/39

IntegrationOptions...................................................................................................................23Configuring3CXPMSProtocolIntegration.............................................................................24ConfiguringFidelioProtocolIntegration..................................................................................24

ConfiguringtheBillingInterface...................................................................................................25Introduction..............................................................................................................................25AdjustingBillingcosts..............................................................................................................25CDROutput..............................................................................................................................26ChangingCDROutputLocation..............................................................................................27EditingCDROutputFormat.....................................................................................................27CompleteCDRTemplate....................................................................................................28

SMDROutput...........................................................................................................................29EnablingSMDR...................................................................................................................29CustomizingSMDROutput.................................................................................................30

3CXPMSProtocolSpecification..................................................................................................33Introduction..............................................................................................................................33GeneralProtocolInformation...................................................................................................33PMStoSystemTransmission.............................................................................................33

PMSFormatSpecification.......................................................................................................34CheckIn/OutMessages......................................................................................................34NameMessage...................................................................................................................35WakeUpMessages............................................................................................................35DNDMessage.....................................................................................................................36MessageRegistrationMessage.........................................................................................36MessageWaitingMessage.................................................................................................37StationRestrictionMessage...............................................................................................37MaidStatusMessage..........................................................................................................38MiniBarMessage...............................................................................................................38


6/39


7/39

3CXPhoneSystemforWindowsSystemforWindows www.3cx.com

Page7

Introduction

Whatisthe3CXHotelModule?

Screenshot1-3CXHotelModule

The3CXHotelModuleaddsadditionalfunctionsto3CXPhoneSystem,whichallowsitto

beusedinhotelsorotherhospitalityenvironments.The3CXHotelModuleperformsthe

followingfunctions:

AllowsforCheckinandCheckoutofguests

AllowssettingofguestextensionstoDonotDisturb

Allowsblockingofexternalcalls

Allowswakeupcallstobescheduled.

Allowsbillingofcallstorooms

Allowshousekeepingtosetroomstatusviathephone

Allowsminibarusagetobereportedviathephone

The3CXHotelModulecan integratewithahostofHotel softwaresystems /Property

Management Systems (PMS) such asMicros Fidelio, Roommaster, Hilton and more.

Alternatively the receptionist can use the system directly through the provided web

interface.

Components

The3CXHotelModuleconsistsofafrontendapplicationandaWindowsService.

TheWindows Service operates in the background and allows for integration with the

Property Management System. With the integration, many of the functions can be

triggeredfromwithinthePMSsoftware.


8/39


Page8

TheFrontDeskPhoneControlApplication isasimple touseWindows orweb based

application thatallows the frontdeskclerk toperformtheaboveoperationswitha few

mouseclicks.Thisapplicationcanbeusedseparatelyfrom,orintandemwiththePMS

system,andthusrequiresnointegrationatall.Formanysmallerhotels,thiscanbegood

enough.

OperationsandFunctionsPerformedbythe3CXHotelModule

The3CXHotelModuleperformsthefollowingfunctions:

OperationsOnCheckIn

SetsExtensionName

Unblockstheextensiontoallowoutboundcalls

Deletesallvoicemailmessages

ClearsanyDoNotDisturb(DND)functions

CheckOutOperations

Setsnametoblanktoshowthatthereisnooneintheroom

Deletesallvoicemailmessages

Disablesoutboundcallsonextension

ClearsanyDoNotDisturbset

DoNotDisturb(DND)

SetsuserstatustoAway(sameasininterface)

Allcallswillbesenttovoice-mail

Wake-upCalls

The systemallows forwakeupcalls tobescheduled. Thereare 2 typesofWake-Up

Callsin the3CXHotelModule.Thefirstis aschedulesetby the receptionist from the

3CXHotelModulewebinterface.Thiswillcalltheguestatthescheduledtimeandplaya

predefinedmessagesoastowakeuptheguest.Thesecondissetbytheguestfromthe

roomwithoutthereceptionistsintervention.Acallwillbemadefromtheguestsroomtoa

pre-configuredWake-UpCallserviceIVR, followthepromptsandconfigurehis/herown

wake-upcallaccordingly.Thisextensionnumbercanbeprintedin thehotelstelephone

directorybrochures.

Billing

Thesystemwilllogcallsfromeachroomandshowcostsbasedonthecostconfiguredin

the3CXPhoneSystemmanagementconsole.

ThesystemcanoutputaconfigurableCDRreportforeachcall.TheCDRreportcanbe

senttoaseparatetextfile(onecallpertextfile)toatextfileforallcalls(allcallswillbe


9/39


Page9

listed in the same text file,or toaTCPport. For eachcase, the exact format can be

customized

HowItWorks

The3CXHotelModuleisanadditionalmodulethatisinstalledonthe3CXPhoneSystem

machine.Themoduleaddsanadditionalservicetothe3CXPhoneSystemmachineas

wellasawebapplication.

The3CXHotelModuleServicestartsonlyiftheHotelislicensed.

Thewebserverselectionforthe3CXHotelModuleisautomaticthismeansthatif3CX

PhoneSystemwasinstalledusingtheIISoption,thentheHotelModulewebinterfacewill

automaticallybeonIIS.Alternatively,if3CXPhoneSystemwasinstalledusingtheAbyss

option, the 3CX Hotel Module will use Abyss. In both scenarios, the 3CX Hotel

ManagementWebpagewillbeaccessedonhttp://IP:5000.


10/39


11/39


Page11

Installing3CXHotelModule

DeploymentConsiderations

Prior to deploying the 3CX Hotel Module, you must install 3CX Phone System and

configureitasperthedocumentation.Keepthefollowingpointsinmind:

Havetheextensionnumbersmatchyourhotelroomnumbers.Thismakesitintuitive

for guests to dial other room numbers,aswellas for hotelstaff to identify room

phones.3CXPhoneSystemcanbedeployedwith2,3,4or5digitlengthextensions

soitshouldbepossibletomatchalmostanyhotelroomnumber

Ifyouarereplacinganoldphonesystemandwanttokeepcertainnumberssuchas

room service or reception using the same shortcuts, keep this in mind when

assigningextensionnumbers.

Itmightbeadvisabletoblockaccesstothe3CXMyPhoneUserportal.Inthiscase,

disable access to the 3CX MyPhone User Portal from the 3CX Phone System

Managementconsole>EditExtension>Other>TurnOffMyPhone.

SystemRequirements

The3CXHotelmodulerequiresthefollowing:

WindowsXPProSP3,VistaSP2,Windows7,Server2003SP2,Server2008

.NETFrameworkversion3.5orhigher

1GigabyteMemoryorhigher,Pentium4processororup

3CXPhoneSystem10mustbeinstalledandrunning

InstallingtheSoftware

Toinstallthe3CXHotelmodule:

1. Downloadthelatest3CXHotelModulefrom:

http://www.3cx.com/downloads/3CXHotelmodule2.msi

2. Run the 3CXHotelModule setup on the3CXPhoneSystem computer. The3CX

HotelModulemustbeinstalledonthesamemachineas3CXPhoneSystem.

3. NowfollowtheinstructionsofthesetupWizard.

4. Youwillbepromptedtoenterausernameandpasswordforthe3CXHotelModule

webinterface.Thiswebinterfacewillbeusedbythereceptionistsofthehotel.Itsa

sharedlogon,anddoesnotprovideadministrativeaccesstothesystem.

5. ClickFinishtocompleteinstallation.


12/39


Page12

6. The3CXHotelwebinterfacewillbeautomatically launched:http://:5000/Hotel.Loginwiththecredentialsspecifiedduringthesetup.

7. Youwill see anotificationdialog to activate the license andconfigureaWakeUp

DigitalReceptionist.

Note: If you installed the 3CX Hotel Module on an existing 3CX Phone System

installation,youneedtoCheck-OUTandCheck-INtheexistingextensionsinorderto

resetanycostcounters,voicemailsandsettingsassociatedwiththeextensions.AllCall

Detailswillberemovedforthoseextensions.

Activatingthe3CXHotelModule

Thenextstepistoactivateyourlicense.

1. Start-upthe3CXHotelModule from thestartmenuprogramgroupthathasbeen

created.

2. ActivateyourlicensebygoingtotheFile>ActivateLicensepagemenuoption.

3. EnteryourLicenseKey,Company,ContactName,E-mail,TelephoneandCountry

andclickonActivatetoactivateyourlicense.Thisinformationwillbesenttoour

licensekeyserverandyourlicensekeyandinstallationwillbeactivated.

4. Depending on your license key, the product will activate with or without PMS

integration. 3CXH stands for the hotel module without PMS integration and

3CHPMSindicatesthatthelicensehasPMSintegration.

CreatingaWakeUpCallDR

Thefirsttimeyoulogintothe3CXHotelModule,youwillbepromptedthatyouneedto

configureaDigitalReceptionist(DR)fortheWakeUpcallfunctionality.ThisDRisusedtoperformtheactualwakeupcalls.ToconfigureaDR:

1.Accessthe3CXPhoneSystemManagementConsole,clickontheDigitalReceptionist

nodeandclickonAddDigitalReceptionist.

2.ConfigureanameforthisDigitalReceptionist.Example:Wake-UpCallIVR.


13/39


Page13

Screenshot14-ConfiguringaDigitalReceptionist

3.Record anaudioprompt thatsays,for example,DearGuest,Thisis yourwakeup

call.Forinformationonhowtorecordsoundfiles,seethe3CXPhoneSystemmanual.

You can also use the Record on Phone feature button to quickly record an audio

prompt.InthisexamplewewillnamethefileWakeUpCallPrompt.wav

4.Now click on the Addbutton and specify the file that you just recorded.No further

optionsarenecessary-clickOKtosavethedigitalreceptionist.

5.LoaduptheHotelwebapplicationandgototheFile>Configuration>Wake-UpCall

Configurationsection,andnext to theoption Wake-upDigitalReceptionistselect the

WakeUpDigitalReceptionist you just created.In this exampleyouwillseeWake-Up

CallIVR.ClicktheOKbuttontosave.


14/39


15/39


Page15

1. Inthe3CXManagementconsole,createaDigitalreceptionist.CallitDialCodeIVR.

ThisdummyDRwillbeusedforboththeMaidstatusandtheMinibarfeatures.You

donotneedtouploadaPromptfile.

2. In the 3CXHotelModule interface, go to the configurationdialog andenable the

MaidStatusCodeandtheMinibarCodescheck-boxes.

3. SelectasDigitalreceptionist:DialCodeIVR(theDRyoupreviouslycreated)

4. Specifyalocalportnumber-Chooseahighporthere,forexample60000.Thisport

isusedinternallybythehotelmoduletopassdialcodeinformation.

5. ConfigureDialCodeput, forexample,*68here.Itmustnotstartwithanyofthe

dialcodesinthe3CXPhoneSystemDialCodesPage.Example:*44willnotwork

becauseitwilltryandmatchthedialcode*4whichwilltakeyoutoVoicemailand

nottotheMiniBar.*9willnotworkeitherbecausethePBXwillthinkitisacallto

Pageanextension.

6. Specify aSuccessMediaFileandaFailedMediafile.Examplecontent couldbe

InputconfirmedandInputfailed.Whenthedialcodeisacceptedthesuccessful

promptfilewillbeplayedbacktothecaller.Whenadialcodeisnotunderstoodbythe3CXHotelService,thefailedmediafilewillbeplayedtoinformtheuserthatthe

dialcodewasnotaccepted.

7. NowundertheEnableMiniBarCodessection,addthevalidProductcodesand

Productnames.Thisway, thesystemwillknowthattheuserhasenteredavalid

product code and can givemini bar personnel the appropriate feedback. If your

HoteloffersSparklingWaterintheMinibarstypeSparklingWaterintheProduct


16/39


Page16

Name field and in the Product Code field enter a unique numeric code, for

example10.

8. DialMinibarStockorders inthefollowingorder.Inthisoptionyouspecifywhether

the Mini bar personnel dials the number of units consumed first followed by the

productcodeorwhethertheproductcodeisenteredfirstfollowedbythenumberof

units.

a. NoofItems*Codemeanstheuserhastotypethenumberofitemsfirst,

followedbythe*andthentheproductcodeexample2*10means2bottlesof

SparklingWater

b. Code * No of Items means the user has to dial the product code first,

followedbya*andthenthenumberofitems,example10*2.

The * character for mini bar codes will be used asmultiplication character and as a

delimitercharacter.

Forexample:InRoom101weneedtofilltheminibarwithtwobottlesofsparklingwater

(code 10) and 3 cokes (code 30). Given the configured dial code is *68, the diallednumberfromtheextensioninRoom101shouldlooklikethis:

*68*2*10*3*30ifNoofItems*Code(a)

*68*10*2*30*3ifCode*NoofItems(b)

Inbothcases,theabovesyntaxmeansthataMinibarorderof2waterand3cokesare

neededtofilluptheMiniBarofroom101.HencethisimpliesthattheGuestinRoom101

consumed2bottlesofwaterand3bottlesofcokewhichofcourseneedtobecharged.


17/39


Page17

UsingtheHotelModuleWebInterface

Introduction

Thischapterexplainshowtousethe3CXHotelModulewebinterface.

Screenshot2-TheWebInterface

The 3CX Hotel Module web interface is located at: http://:5000/Hotel.Afteryoulogin,youwillsee4nodes:

AllRoomsAllextensionscreatedin3CXPhoneSystem

OccupiedRoomsThesearealltheextensionsthatarecheckedin

EmptyRoomsAllextensionsthatrepresentcheckedoutstatus.

Wake-UpCallsAllscheduledwakeupcalls.TheseshowinRED

FunctionsAvailable

CheckingInGuests

Screenshot3-CheckinginaGuest

Tocheckinaguest:

1.SelecttheroomnumberfromtheAllRoomsorEmptyRoomsnodeandclickonthe

CheckINiconfoundonthetoptoolbar.


18/39


Page18

2.Youwillbepromptedtoentertheguestsname,emailaddressandcallerID.Theemail

canbeusedforvoicemailnotificationiftheguestwishestoreceivetheirvoicemailvia

email.

3.ClickOK.Thiswill:

SettheExtensionNametotheGuestsname

Unblocktheextensiontoallowoutboundcalls

CheckingOutGuests

Tocheckoutaguest:

1.SelecttheroomnumberandclickontheCheckOUTicon.

Screenshot4-CallCostsDialog

2.The3CXHotelModulewillbringupthecostofanycallsmadeinaseparatedialog.Ifnocallswithcostsweremade,adialogconfirmingthiswillpop-up.

3.Youcanchoosetoprintthisdialogforinclusionwiththehotelbill.

4.Nowclosethecallcostdialog.Theextensionwillnowbecheckedout.Thiswill:

DeletetheguestnameandmovetheroomtoEmptyrooms

Deleteallvoicemailmessagesoftheroom

Disableoutboundcallsontheextension

ClearanyDoNotDisturbsset

SettoDoNotDisturb

TheDonotDisturb functionwillsendallcalls to the room totheguestvoicemail.The

DNDstatuswillbeshownintheDNDOn/Offcolumn:

AvailableGuestwilltakecalls

DoNotDisturbCallswillbesenttovoicemail


19/39


Page19

Note:WakeupcallsoverrideDoNotDisturb.Therefore,ifanextensionissettoDoNot

DisturbbutthereisascheduledwakeupCall,thewakeupcallwillstillbemadewhilsta

normalcallwillgotovoicemail.

SchedulingaWakeUpCall

Screenshot5-WakeUpCalls

Thewakeupcallfeatureallowsyoutoscheduleanautomaticcalltobeplacedtoaroom

ataparticulardateandtime.Toscheduleawakeupcall:

1.SelecttheroomnumberandclickonSetWakeup.

Screenshot6-SetWakeUpCall

2.Youwillbepromptedforthedateandtimeofthewakeupcall.ClickOKtosetthe

wakeupInthisexamplewehaveconfiguredawakeupcalltobemadeonthe22nd

Septemberat3:00AM.

3.Whenthetimeofthewakeupcallisreached,theextensionintheguestsroomwillbe

called automaticallyby the digital receptionist created and transferred to the recorded

wakeupmessage.Pleasenotethattheguestwillbecalledonlyonce.


20/39


Page20

Screenshot7-ListofWakeUpCalls

4.YoucanviewalistofscheduledwakeupcallsatanytimebyclickingontheWakeup

callsnode.

Note:Currentlyonlyonewakeupcallperextensionisallowed.

BlockExternalCalls

YoucanblockexternalcallsinroomsbyselectingtheroomandclicktheBlockbuttonin

thetoolbar.

ViewingtheCallsMadebyaGuest

Screenshot8-DisplayingCallsMadebyaGuest

ClickontheroomnumberandViewcallstoviewallthecallsmadebyaparticularroom

andtheassociatedcost.Youcanprintthisdatabyclickingprint.

SetRoomStatusbyPhone

Thisfunctionallowscleanerstosetthestatusoftheroomviathephone.Themaidstatus

message is triggered bya call from the room in questionand by entering the special

featurecode (thedial code set in the configuration section of the 3CX Hotel interface

whichisalsousedfortheMinibarcodes),followedbytheappropriatecodetospecifythe

statusoftheroom.

Note:ThecodesaredifferentdependingonthePMSsystemused.3CXPMSsupports9

MaidcodestateswhilstFideliosupports6.


21/39


22/39


Page22

If the code is correct, the successmedia filemessagewill be played. If the code is

incorrect the failed media file message will be played. These messages can be

configuredfromthe3CXHotelModuleinterface,File>Configurationsection.


23/39


Page23

HotelSoftware/PMSIntegration

Introduction

Although all hotel related functions canbe performed via theweb interface, it isoften

preferabletoperformthesefunctionsautomaticallyatcheckinorcheckoutoftheguest

viathePropertyManagementSystemsoftware.

3CXPhoneSystemsupportsawiderangeofhotelsoftwaresystems.

IntegrationOptions

The3CXHotelModulecanintegratewithPMSsystemsinthefollowingways:

1. Viathe3CXPMSprotocol.ThisprotocolisverysimilartotheMitelprotocol.Most

hotelsoftwarehaveaMitelPBXinterfacesoitispossibletoselectthisintegrationoptionintheHotelSoftwareanditwillworkwiththe3CXPMSprotocol.Ifmultiple

Miteloptionsareoffered,theMitelSX2000optionmustbeselected.

2. ViatheFidelioprotocol

3. Exchange of data can also be done on a custom basis. In this scenario,

documentationmustbeprovidedbytheresellerastohowtheintegrationmustbe

performed.Additionalchargesmayapply.


24/39


Page24

Configuring3CXPMSProtocolIntegration

When using the 3CXPMS protocol, the 3CX HotelModuleacts as aserver. Inother

words,thePMSsoftwaresendsmessagestothe3CXHotelModule.InthePMSsoftware

youmustspecify:

1. TheIPaddressof3CXPhoneSystem.

2. Specifyport15374fortheHotelSoftwareconnection

3. IfmultipleMiteloptionsareoffered,chooseMitelSX2000

Naturally,ifyouchangethedefaultports,youmustchangetheminthePMSsystemas

well.

Then access the 3CX Hotel Module and go to File > Configuration. In the PMS

Configurationsectionyoumustspecify:

4. TheIPaddressofthePMSSystem

5. TheportmustmatchthatconfiguredinthePMSsystemexample15374

6. TheselectedPMSintegrationtypeshouldbe3CXPMS

ConfiguringFidelioProtocolIntegration

The Fidelio Protocol integration can be used for Micros Fidelio, Protel and Brilliant

HotelConceptshotelsoftware.Inthiscase,nobillinginterfaceneedstobeconfigured.

The 3CX Fidelio protocol integration acts as a client. Thismeans that in this case,

messageswillbesentfromthe3CXHotelModuletotheFidelioManagementSystem.

Specify the IP and thePort of the FidelioPMS server in the3CXHotel Module web

interface,bygoingtoFile>Configuration>PMSConfiguration.SelectFideliofromthe

PMSintegrationtypedropdownlist.PressOKtosavethisconfiguration.The3CXHotel

ServicewillrestartandloadthenecessaryparameterstocommunicatewiththeFidelio

PMS.


25/39


Page25

ConfiguringtheBillingInterface

Introduction

THEBILLINGINTERFACEONLYNEEDSTOBECONFIGURED IFUSINGTHE3CX

PMS INTEGRATION (WHICHEMULATESMITEL). IT ISNOT REQUIRED IFUSING

THEFIDELIOPROTOCOLFORMICROS-FIDELIO,PROTELANDHOTELCONCEPTS.

3CX Phone System provides billing information so that you can charge your guests

accordingly for each phone call. This information is displayed per room in the web

interface,oralternativelyyoucanoutputittoatextfileortoaTCPportsothatyoucan

integrateitwithyourPMSsoftware.

CallcostsarecalculatedandinsertedintoaCDR(CallDataRecord)whichisoutputted

todiskasa textfileorsent toaparticularhostataparticularport. Inthismanner itis

easytointegratewithahotelsoftwaresystemorcallaccountingsoftware.

AdjustingBillingcosts

3CXPhoneSystemcalculatescallcostsbasedondestinationnumberandcallduration.

Youwillneedtoenterthecostforeachcountry,fornationalcallsandformobilecalls.

Thedefaultbillingrateis1.0.Tochangetheserates

1.Inthe3CXManagementConsole,gotoView>BillingInformation

2.EdittheratesasappropriateandclickApply.

3.Whencallsaremadetoexternalnumbers,theyarecheckedagainstthisprefixtable.If

amatchisfoundthenthecostiscalculatedasfollows:TotalCost=Talkingtime*ratewherearateof1.0means100per60secondsoftalkingtime(1minute)


26/39


Page26

Screenshot9BillingInformationinthe3CXManagementConsole

CDROutput

TheCDRfeatureprovides5outputchannels.

1. OneCDRfileforallcalls

2. OneCDRfilepercall

3. ActiveSocketoutput(initiatesconnection)

4. PassiveSocketOutput(waitsforconnection)5. CustomizedFeedviaPlugin(CDRPlugin.dll)


27/39


Page27

Each channel can be enabled separately. To Enable the CDR feature, from the

managementconsolegototheSettings>Advanced>CDROutputtab,andselectthe

CDROutputtab.

ChangingCDROutputLocation

The file output default location can be changed by editing each template file. Thetemplate files are located in%allusersprofile%\3CX\Data\CDRTemplates. In this folder

youwillfind4xmltemplateswhichyoucanmodifyinC#.

Inthecaseof thetemplatesCDRTemplate-SocketandCDRTemplate-SocketListen, the

hostnameand portmust be specifiedin the tags Host="127.0.0.1"and Port="33555"

whenyouopentheXMLfile.

Alloutputistextbasedandcanbeformattedbymodifyingthetemplateforeachchannel.

Eachchangemadeinthetemplatefilesrequiresarestartofthe3CXCallHistoryService.

EditingCDROutputFormat

IfyouneedtoaltertheformatwithwhichtheCDRsareoutputted,youcandobyediting

the XML template files. Each template file contains XML tags that describe which

databasefieldsshouldbeincludedintheCDR,inwhichorderandhoweachfieldshould

beformatted.

Eachnodeoutputsthetextquotedinthetextafter{0}andisreplacedbythevalueof

theactualfield.Forexample,thexmlnode

wouldoutput:

XXcallerID=00357999999,

TheformattingcanbecustomisedusingC#formattingstrings.Thereforeitispossibleto

inserttextbeforeandafterafieldvalueandtoformatnumberswithdecimalsandformat

dates.

Herearesomeexamples:

FormattingtheTotalCostandstarttimefields:

wouldoutputCallCost=003.40

wouldoutput210911160729,


28/39


Page28

wouldoutput21.09.201116.07.29

AddingnewlinecharactersinXML

wouldoutput:

Calldetails=2where

CR=LF=(CRcarriagereturnLFlinefeed)

EachcallhasonemainCallhistory3entryand1ormoreCallDetailsentries.EachCall

Detailisforonedestinationofthecall,soifacallistransferred2times,therewillbe3

calldetailsrecordsforit:onefortheinitialdestinationandoneforeachtransfer.

CompleteCDRTemplate

BelowisasnapshotofthecompletecontentsofoneoftheCDRtemplatesincludedin

3CXPhoneSystemCDRTemplate-Single.xml.It includesallthepossiblefields.Fields

thatarenotrequired,canberemovedbyremovingorcommentingthecorrespondingxmlnode.

Thecontentsinthetemplatecanbemodifiedbutthetemplatefilenameandlocationon

diskshouldnotbechanged.TheCallHistoryservicemustloadthetemplatesfromthe

\3CX\Data\CDRTemplatesfolder.


29/39


Page29

SMDROutput

TheSMDRfeatureisseparatefromtheotherCDRfeatures.

EnablingSMDR

ToenableSMDRyoumustenterthehostandporttolistenonforincomingconnections.

Inthe3CXManagementconsole,navigatetoSettings>Advanced>CustomParameters

Tab.In thesearch filter type inSMDR.Youwillseethataparameterwillbedisplayed

calledSMDRHOSTPORT.SMDRHOSTPORT=0.0.0.0:1752shouldworkformostcases

whereonly1networkconnectionexists.

Todisableityoumustsetanemptyhost,e.g.SMDRHOSTPORT=


30/39


Page30

SMDRwillopenasocketandlistenontheportspecifiedabove.Itwilloutputeachcallin

SMDRformat toallestablishedconnections.ThedefaultformatiscompatiblewithMitel

SX2000,andhasbeentestedwithCallAccountingMatesoftware.

The 3rd party software has the responsibility to connect and to maintain the socket

connectiontotheSMDRservice.ToconnectyouwillneedtogototheSMDRsectionof

your3rd partysoftware andenter the IP Address of 3CXPhone Systemand theportwhichinthiscasewillbe1752.

Youcantestthiseasily by openingacommandpromptwindow and telnet tothe3CX

SMDR connection - simply type in telnet ip-of-3cx-phonesystem 1752 example: telnet

10.172.0.1801752.

After thismakeasimple call and you should see SMDRoutputted onyourcommand

prompt screen. SMDR output is sent in specific intervals. You can configure the

frequencyfromtheCDROutputtabinthe3CXManagementConsole

CustomizingSMDROutput

ItisalsopossibletocustomizetheoutputbyeditingtheC#scriptthatproducesthis.The

templatecanbefoundinthefollowinglocation:

%allusersprofile%\3CX\Data\CDRTemplates\SMDR.cs

ChangingthescriptrequiresknowledgeofC#oratleastprogrammingskills.Thescript

hasaccessto2objects,callinfoanddetails.

callinfo:containsinformationregardingtheentirecall.Ithasaccesstothefollowingfields:


31/39


Page31

nHistoryID - the unique ID used for identifying the call. This is used internally to write the call incallhistory3, the primary key.

tmDuration - the duration of the call if answered, or 0 if not answered.

tmCallStart Date and Time when the call started.

tmCallAnswered Date and Time when the call was answered.

tmCallEnded Date and Time when the call was dropped.

sCallFrom - the initial caller.

sCallTo - the initial callee.

sGroupNum - the group number, if the call comes from a group(Queue, Ring Group, ivr). Eg: if the callwill come from queue 800, sGroupNum will be 800.

sLineNum - the external port number through which the call passes. If an extension is calling anexternal number through a VoIP Provider, the sLineNum will be the Virtual line number of that VoIPProvider Ex: 10000.

sRecCallID - the internal unique identifier of the call used by the PBX to uniquely identify calls.

sCallerID - the initial caller id. Eg. if the call is from extension 100 to 101, the caller id will beoutbound caller id of extension 100 which usually is 100.

sDialedNumber - the exact dialled number. Eg: if for instance extension 100 is calling *9102(*9intercom) the dialled number will be *9102.

sLastCallerID - last caller ID of the current call. A call can go through many transfers and this willbe the last caller ID of the call. Eg: if extension 100 calls 101, 101 transfers to 102, the lastcaller ID will be 101.

sLastDialedNumber - last dialled number. From the above example, last dial number is 102 which is lastdialled number of this call.

sBillPrefix - the billing prefix used to make the billing. This is configured from 3CX ManagementConsole > View > Billing Information.

sBillRateName - the billing country name.

bIsAnswered - true if the call is answered, false otherwise

bIsFailed - true if the call has failed, false otherwise

bIsCompleted - true if the call is completed, false otherwise

bCallFromOutside - true if the call was from an external line, false otherwise.

fRate - the rate used to bill this call.

fTotalCost - total cost for the call

eGroupType This is a group type for calls coming from a group. Possible values are RingGroup = 3,Queue = 4, DR = 5

iMediaType - media type used for recording.

iGrpAnswer - used internally.

details:Representsthedetailsanddestinationsofacall.Inthecaseoftransfersacall

mayhavemultipledetails(DetailData3objectforeachtransfer)


32/39


Page32

ParentIdx - internally used to make the link with the parent call. Eg: extension 100 call 101, 101transfers to 102. For this call we will have 2 "DetailData3" objects, one for 100 to 101, and anotherfor 101 to 102. In this case ParentIdx of the second call(101 - 102) will be the iNDetail of the first"DetailData3" object (100 - 101).

DestDN - the destination of the call. Eg: in case we have a call from 100 - 101, destination dn will be101, if for instance the call is from 100 - "external number" using the line 10000, DestDN will be10000 (Virtual extension number of the line)

DestNum - the destination number as dialled by the caller. Eg: 100 - "external number", destinationnumber will be the "External number"

StartTime - the start time of the call

AnswerTime the answer time of the call

EndTime the end time of the call

Dur the duration of the call. Ex: 100 calls 101, 101 transfers to 102. If Dur belongs to"DetailData3" object of call 101 - 102, Dur will be the duration of this call.

Status - the status of the call. Possible statuses are the following:

Connecting = 0Answered = 1DestBusy = 2DestNoAnswer = 3DestNotAvailable = 4NotAnswered = 5Completed = 6DstUnknown = 7

IsCompl - true is this call is completed

bCallToOutside - true if it is from/to external line

SpecType iIdCallHist, iNDetail, ExtType used for internal use only

ForamoreextensiveexamplepleaselookintoSMDR.cslocatedintheCDRTemplates

folder.


33/39


Page33

3CXPMSProtocolSpecification

Introduction

Thischapterdetails the 3CXPMSprotocol,which integrateswithPMShotel software.

The 3CX PMS protocol closely resembles the Mitel PMS protocol, and therefore its

possible to specify theMitelPMS protocol in the PMS system.Theprotocol is further

detailedinthischapter.

GeneralProtocolInformation

ThePMS/Systembi-directional(throughhalf-duplex)linkusestheENQ/ACK/STX-text-

ETX/ACKprotocol.ThePMStosystemtransmissionsequenceis:

Thetransmissionofthemessageiscomplete.

Therearetimingrestrictionsimposedonthetransmissionsequences:

Themaximum time to wait for theACK after aSTX+msg +ETX transmission is 3

seconds.

PMStoSystemTransmission

After receiving an ENQ character from the PMS, the system responds within three

seconds with either an ACK or an NAK. The ACK indicates the transmission was

successful.TheNAKindicatestherewasatransmissionerror,orthatthesystemisbusy.

Thesystemgeneratesahotel log indicating such anerroroccurred.After sending the

ACK,thesystemisimmediatelyreadytoreceivetheSTX,messagetext,andETX.Within

threesecondsofreceivingtheETX,itrespondswitheither:

.ACKindicatingthe transmissionwassuccessful,andallofthemessagefieldsare

valid.


34/39


Page34

.NAKindicating therewas an error in either the transmission itself, in oneof the

message fields,or in the syntax of themessage (specifically STX, ETX, function

codeand status code;for example,CHK3 issent instead ofCHK1).The system

generatesahotellogindicatingthiserroroccurred.ThePMSisabletoretrysending

only the message txn (STX, message text and ETX) three more times without

prefacingitwithanENQmessagefirst.

ThefollowingexampleillustratesaPMStransactionretry:

ThePMSthendiscardsthetransaction.

PMSFormatSpecification

Themessageshavethefollowinggeneralformat:

CheckIn/OutMessages

Themessagehasthefollowingformat:

where:XistheCheckIn/Outstatuscode

ASCIIcharacter1forCheckIn

ASCIIcharacter0forCheckOut

SPistheASCIIblankcharacter.nisanextensionnumberdigit.

Note thatextension numbers less than five digitslongare filled with spacecharacters

(ASCII32,HEX20),notzeros(ASCII48,HEX30).


35/39


Page35

IfthemessagereceivedfromthePMSisinvalid,thesystemreturnsanNAK(anASCII

characterforNegativeAcknowledge).

Example:

CheckIn:(checkinforextension100)

STXCHK1100ETX(whereSTX=2,ETX=3)resultingthefollowingmessage2CHK11003

NameMessage

ThismessageissentfromthePMSandisusedtodisplaytheGuestnameonthephone.

TheNamemessagehasthefollowinginputformat:

where:NAMisthenamefunctioncode.

NAMEisacharacterofthename(maximum21characters).

nisanextensionnumberdigit.

Thelengthofthename(upto21characters)isleft-justified,withblanksusedforpadding.

Thecharacterscanbeupperor lowercase, andmayalso includenumericcharacters.

Firstandlastnamesmaybegiven(separatedbyacommaplacedanywherebutinthe

1stand21stlocation),butifonlyonenameappearsitisrecordedasthesurnameby

default.Thefirstnameinthestringmustbethelastnameorsurname,followedbythe

firstname.Ifonlyonenameisgiven,the21stcharacterisablank(themaximumsizeofa

nameis20).

Use of the string operation code allows for addition and deletion of a specific name

againstanextension.

Thesystemallowsmorethanonenametobeaddedagainstastation.Mostsituations

usuallyhavejustonenameassociatedwithastationnumber.

TheStringOperationcodeisthefirstbyteofthestatuscode,andmaybeoneofthese

options:

1. (addition)-ThenameisADDEDtothecurrentlistofnamesagainstthisstation.If

thereisnonameagainstthisnumber,anewtelephonedirectoryentryiscreated.

2. (replacement)-ThenameisusedtoREPLACEthefirstalphabeticalnameagainst

thisnumber.Allothernamesagainstthisnumberarenotaltered

IfaninvalidmessageisreceivedfromthePMS,thesystemreturnsanNAK.

WakeUpMessages

ThePMSsystemcaninformthesystemwhentosetawakeupcallforaparticularguest

station.Thewakeupmessagehasthefollowingoutputformat:


36/39


Page36

where:tisthewake-uptime.nisanextensionnumberdigit.

Thewakeuptimeisspecifiedin24hourtime.Allfourcharacters,filledwithASCIIblanks,representadeletionofthewakeuptime(timeformat:HHmm).

Exampleofwakeupcallat23and30minutestoextension100:

2MW23301003

DNDMessage

ThePMSsystemcaninformthePBXwhentosettheDNDstatusforaparticularguest

stationbysendingthefollowingmessage.

TheDNDmessagehasthefollowingformat.

WhereSTATUSCODE:

1DNDON

0DNDOFF

SPistheASCIIblankcharacter.

Example:setDNDONforextension302

2DND13023 STXDND1SPSPSP302ETX

StxValue=2

EtxValue=3

ENQ=5;

ACK=6;

NACK=21

MessageRegistrationMessage

Eachtimeahotelextensionmakesatrunkcall,thesystemsendsamessagetothePMStoupdatethetotalcountofoutsidecallsmadeagainsttheguestroom.Nodistinctionis

madebetweenlocalandlong-distancecalls.MessageRegistrationworksbycountingthe

numberofmeterpulsesmadeoverthedurationofthecall.

TheMessageRegistrationmessagehasthefollowingoutputformat:


37/39


Page37

where:

SPistheASCIIblankcharacter.

nisanextensionnumberdigit.

Thestatuscodeinthiscaseisafeeorpegcount.Thisistheoneexceptiontothelength

ofthestatuscode,being4bytesinsteadof2.

MessageWaitingMessage

Theformatofthismessageisthesameforbothdirections.Theformatofthemessageis

similartothecheckin/outmessagewheretheuseofbinarystatuscodeprovidesthenew

stateofthemessagewaitinglamp.

TheMessageWaitingmessagehasthefollowingformat:

where:SPistheASCIIblankcharacter.XistheMessageWaitingLampstatuscode

ASCIIcharacter1forLampOn

ASCIIcharacter0forLampOffnisanextensionnumberdigit.

StationRestrictionMessage

A Station Restriction message can be used to establish call restrictions. When this

message is sent from the PMS to the system, it brings previously programmed Call

Restrictionsintoeffect.

Note:EmergencyServices(911/999)andinternalcallsareneverrestricted.

TheStationRestrictionmessagehasthefollowingformat:

where:RSTistheStationRestrictionfunctioncodeXisanextensionorsuitenumber

digitSisoneofthefollowingstatuscodes:

.0-Internal

.1-Local

.2-LongDistance

StxValue=2

EtxValue=3


38/39


Page38

ENQ=5;

ACK=6;

NACK=21

MaidStatusMessage

Themaidstatusmessageisusedtoallowcleanerstosetthestatusoftheroomviathe

phone.Themaidstatusmessageistriggeredbyacallfromtheroominquestionandby

enteringthespecialfeaturecode,followedbytheappropriatecodetospecifythestatus

oftheroom.

Forexample,dialing*682fromtheroomwilltriggeramaidstatusmessagetothePMS

thatwillsetthestatusoftheroomtoclean.

TheMaidStatusMessagehasthefollowingformat:

STX S T S X SP n N n n n ETX

Xisthemaidstatuscode

SPistheASCIIblankcharacter

nisthestationnumberdigit(upto5digits)

WhenaFeaturecodeisdialled,thesystemsendsbothaFunctionandStatuscodetothe

PMS,andthePMSinterpretsthecodesinthefollowingway:

MessageOccupancyCondition

STS1maidpresent

STS2clean

STS3notclean

STS4outofservice

STS5tobeinspected

STS6Occupied/Clean

STS7Occupied/NotClean

STS8Vacant/Clean

STS9Vacant/NotClean

MiniBarMessage

TheminibarmessageallowsminibarpersonneltoforwardminibarusagetothePMS

systemvia thephone. Themini barmessage is triggered by a call from the room in

questionandbyenteringthespecialfeaturecode,followedbytheappropriateitemcode

andtheamount.Forexample

*68(specialdialcodesetinthemanagementinterface)10*2.

WillsendtothePMSthattheroomhad2unitsofitemcode10


39/39


If the code is correct, a success message will be played. If its incorrect, an error

message will be played. Thesemessages can be configured from the interface. The

correctminibaritemcodescanbeconfiguredfromthehotelmanagementinterface.

Theminibarmessagehasthefollowingformat:

STX M N B SP ccccc(30) nnnnn ETXnnnnn-theextensionnumber

cccccc-datalength30digit,canbefilledwith0-9,*

'*'characterhastworoles:delimiterandmultiplication

Example:Aminibarrequestfromextension100:

[STX]MNB[SP]1*20*3*50[SP..SP][SPSP100][ETX]

This means posting code item 20 (Coke) with a total of 1 pcs and item code 50

(Chocolate)withatotalof3pieces.

Documents

3cx_hotelusermanual_A9RF298