Chapter 15. Using Tcl Scripts and VoiceXML
Cisco voice gateways have the ability to support interactive voice response (IVR) and advanced call-handling applications using Toolkit Command Language (Tcl) or VoiceXML (sometimes referenced as VXML). Tcl and VoiceXML are scripting languages that allow the gateway to provide specialized call treatment, such as playing audio prompts and accepting user input using dual-tone multifrequency (DTMF) tones.
Dr. John Ousterhout developed the Tcl script language at the University of California, Berkeley. Cisco voice gateways run Tcl IVR 2.0, which is based on Tcl with a proprietary Cisco application programming interface (API). On the Cisco website, you will sometimes see Tcl referred to as “TCL,” but the official name is Tcl.
VoiceXML is a standards-based markup language for voice browsers. VoiceXML can utilize existing web server and application logic, which can reduce development time and expense.
This chapter helps you to do the following:
• Understand how Tcl and VoiceXML applications operate
• Understand the difference between Tcl and VoiceXML applications
• Review sample Tcl scripts that are available from Cisco
• Implement Tcl scripts in a voice gateway
• Create audio files for use with Tcl scripts
• Verify and troubleshoot applications
Tcl IVR and VoiceXML Application Overview
Both Tcl IVR 2.0 and VoiceXML can support extremely complex applications. These complex applications are built by stringing together basic functions that fall into the following categories:
• Play audio prompts
• Collect user input in the form of DTMF tones
• Modify automatic number identification (ANI) or dialed number identification service (DNIS)
• Record call information
• Perform call admission control
Note
MGCP is not supported with Tcl or VoiceXML applications. To support applications, the gateway must have local control of the call.
The main difference between Tcl and VoiceXML is that the router executes a Tcl script, whereas a VoiceXML script is a client-server model. If the gateway associates a call with a VoiceXML application, the application loads the appropriate VoiceXML document that can call for the gateway to interact with various web applications. This document might play audio prompts and collect digits. You can load additional VoiceXML documents based on the caller input.
Both Tcl and VoiceXML servers can utilize external RADIUS authentication, authorization, and accounting (AAA) servers for authentication and billing and TFTP servers for storing of scripts or prompts.
Figure 15-1 shows the interaction between a caller and a typical Tcl application providing prepaid calling card service. The caller dials a toll-free access number. The Tcl script prompts the caller for his calling card number, his personal identification number (PIN), and the number he wants to reach. After the Tcl application authenticates the calling card number and PIN with the AAA server, it extends the call to the remote gateway. The remote gateway then completes the call to the destination.
Figure 15-1. Caller Interaction with a Tcl Application
Figure 15-2 shows the interaction between a caller and a VoiceXML auto attendant (AA) application. The application prompts the user for his account number and uses this to access the customer records. The web application can then prompt the caller through checking balances, transferring funds, or other self-help activities, or it can transfer the caller to an agent for personalized service.
Figure 15-2. Caller Interaction with a VoiceXML Application
Tcl IVR 2.0 added support for Real Time Streaming Protocol (RTSP) servers. This allows you to store the audio files, or prompts, on the external server and stream them directly to the caller. This increases both the size and number of prompts that you can use in an application. Prompts that you store in the flash of the gateway or on a TFTP server are loaded into the DRAM and are played from DRAM to the caller. The applications discussed in this chapter would not typically require an RTSP server.
If a custom application requires access to servers for prompts or data retrieval, you should consider survivability if the servers are not accessible. For example, Cisco Voice Portal (CVP) includes a call survivability script that attempts to transfer callers to an alternate location in the event of CVP application errors.
Developing Tcl or VoiceXML scripts requires knowledge of programming that is beyond the scope of this book. Cisco provides numerous Tcl applications, some of which are described in the next section. This chapter focuses on implementing Tcl scripts using these Cisco-provided applications for illustration purposes. The methods for implementing VoiceXML applications are similar from the gateway perspective.
Programming Resources
Cisco provides two excellent resources for developing your own Tcl or VoiceXML applications. The TCL IVR API Version 2.0 Programmer’s Guide and Cisco VoiceXML Programmer’s Guide are available from Cisco.com to registered users. Aspiring Tcl programmers should also review the wealth of information that is available at http://www.tcl.tk.
Cisco Systems also has a fee-based application development group that can develop an application to your specifications. In addition, a Cisco Technology Developer Program can provide support to third-party developers. Information on these programs is available from Cisco.com or from your Cisco account team.
Note
Only Tcl/VoiceXML applications that are developed through the Cisco Technology Developer Program are supported by the Cisco Technical Assistance Center (TAC).
Sample Applications
Cisco provides numerous Tcl applications for download from Cisco.com. The majority of these applications are focused on service provider needs, but several are useful to enterprise customers.
Auto Attendant
The auto attendant (AA) script is available for Survivable Remote Site Telephony (SRST) and Cisco CallManager Express (CME). This script provides basic call redirect based on caller input. When it is not possible or desirable to acquire a direct number for each phone at the location, the AA script allows you to use a single number, called the pilot number, to route calls. For example, a caller to the AA pilot number hears a customizable prompt to enter the desired extension or press 0 for the operator. When the caller enters a valid extension, the call is transferred. If the caller enters an invalid extension or does not enter any digits, the prompt is replayed. The steps for implementing the AA script are detailed in “Implementing the AA Tcl Script,” later in this chapter.
Note
If Cisco Unity Express (CUE) is installed in an SRST/CME router, you should use it to provide AA functionality.
Note
Both SRST and CME have an AA script, but the scripts are not compatible. Make sure you download the correct script for your application.
Basic ACD
The Basic-ACD (B-ACD) script provides automatic call distribution (ACD) support for basic call center or help desk-type applications. The B-ACD script works in conjunction with the CME AA. It provides an IVR, which prompts callers through a menu to determine into which queue they should be placed. Each queue has an associated AA. The AA uses an e-phone hunt group to route the call to the next available agent. The B-ACD also provides statistics about calls, such as how long a caller waited before his call was answered and how many calls were routed to voice mail because the configurable max call timer expired.
Fax Detect
The Fax Detect script allows you to use a single number for both voice and fax calls. The script provides an option for prompting callers to press a particular key if they are placing a fax call. Alternatively, the script can detect that a call is a fax by listening for CalliNG (CNG) tones. When the script detects a fax call, it routes the call to the dial peer that is associated with the appropriate fax machine.
Caution
Fax Detect has several caveats, including a delay in call setup. Before you deploy the Fax Detect script, test it thoroughly to understand its possible side effects.
T.37 Store and Forward Fax
T.37 is a standard for converting faxes to Tagged Image File Format (TIFF) attachments that are sent via e-mail. T.37 Store and Forward Fax consists of an on-ramp and an off-ramp process. The on-ramp process converts an incoming fax to an e-mail message with a TIFF file attached. It can route an e-mail to an inbox or to an off-ramp process. The off-ramp process converts an e-mail that has a TIFF attachment back to a fax. You can load the on-ramp and off-ramp scripts on the same gateway or on different gateways.
Malicious Call ID
The Malicious Call ID (MCID) script works in conjunction with the MCID feature in Cisco CallManager 4.0. MCID allows a call recipient to press a programmable key on a Cisco IP phone if he receives a malicious call. This notifies the system administrator, flags the call in the call detail record (CDR) database, and instructs the gateway to send a message to the public switched telephone network (PSTN), allowing the service provider to take appropriate action. MCID is supported only on NET5 switches and must be enabled by the service provider.
Cisco Voice Portal
The Cisco Voice Portal (CVP) is a component of the Cisco customer contact product suite. CVP provides call treatment with self-service IVR options for both time-division multiplexing (TDM) and Voice over IP (VoIP) systems. Unlike the other sample applications listed here, CVP is not downloaded from Cisco.com.
CVP is included in this list because of the ability for a gateway to act as a remote site VoiceXML-controlled gateway for a centralized CVP server in a distributed contact center design. This is becoming a compelling network design for many Cisco customers. It allows the remote gateway to answer a call, play prompts, and collect the caller input. It keeps Real-Time Transport Protocol (RTP) streams off the network until the central ACD selects an agent to answer the call. If the caller uses the self-service features to complete his transaction and does not require an agent, the RTP call almost never uses bandwidth on the IP network.
Embedded Event Manager
The Cisco IOS Software Embedded Event Manager (EEM) is not a voice application; rather, it is a powerful tool that uses Tcl to greatly enhance network management. With EEM, you can define policies to take specific actions when Cisco IOS recognizes certain events. EEM uses event detectors to detect certain conditions in the device. EEM v2.2 has 15 event detectors; new event detectors are added with each version. The event detectors can either trigger an application policy included in EEM or can trigger custom Tcl scripts.
Downloading Tcl Scripts from Cisco.com
Tcl scripts are available in several locations on Cisco.com, depending on the application. You can find most Tcl applications by searching for “tclware.” The notable exceptions are the AA and B-ACD Tcl scripts, which you can find in the CallManager Express/SRST software download section of Cisco.com.
It can be difficult to find the CME and SRST scripts because they are handled differently on Cisco.com. The CME AA and B-ACD scripts are available as individual downloads in zip and tar formats. The B-ACD script is also contained within some of the CME bundles. The SRST AA script is contained in a zip file called SRST-2.0.zip. This file is described as optional files for use with SRST 2.0. “Optional files” are also available for SRST 3.0 and SRST 3.3, but they do not include the AA Tcl script. The SRST 2.0 version of the AA script currently works with all available versions of SRST.
One of the most common problems with the AA script is using the wrong version. This is easy to do because only the CME script is labeled as an AA script, and the SRST AA script is not clearly labeled. If you use the CME version on an SRST router, the application loads and even answers the call. However, the caller does not hear prompts even though debugs indicate that the prompts are being played.
Configuring the Gateway to Use a Tcl Script
Five steps are required to implement a Tcl application on a Cisco voice gateway:
1. Load the script to flash memory or the TFTP server.
2. Load the associated audio prompts to flash memory or the RTSP server.
3. Initialize the application.
4. Specify the initial parameter values.
5. Configure the dial peers to use the script.
Cisco-developed Tcl scripts include a Readme file that describes the associated audio prompts and parameters that are associated with the script. Default audio prompts are typically included in the script, but you can rerecord them to meet your business needs.
Initializing Tcl Scripts and Specifying Parameters
The method of initializing a Tcl script and specifying initial parameter values changed in Cisco IOS Release 12.3(14)T. Prior to Cisco IOS Release 12.3(14)T, the call application voice command was used.
call application voice application-name location
The application-name is a label used within the gateway configuration, and the location is where the actual script is loaded from—either flash or a TFTP server.
After you load the application, you set parameters to their initial states:
call application voice application-name parameter-name value
This command is repeated for each parameter within the script.
Cisco IOS Release 12.3(14)T introduced an application configuration mode. This method is more hierarchical, which makes it much easier to read the configuration file and understand what is being loaded.
application
service application-name location
param parameter-name value
Applying Tcl Scripts
After you load the application and set the parameters to their initial values, you assign the application to a dial peer. You do this by using the service command under the dial-peer configuration.
service application-name
Configuring Inbound Applications
You run most applications on the inbound dial peer. For example, you run the AA script on the dial peer that is associated with calls coming from the PSTN. It is important to understand which dial peer will be matched for these inbound calls. To ensure that calls are routed as you expect, configure an explicit dial peer with an appropriate incoming called-number command.
You can associate applications with both plain old telephone service (POTS) and VoIP dial peers. When you associate an application with an inbound VoIP dial peer, the session target should point to a loopback interface on the local router. If you use an interface address, the application will be unavailable if that interface is down.
Configuring Outbound Applications
You can also configure applications on outbound dial peers. You use an outbound application when some preliminary processing is required before you enter the application. An inbound application must process a call before an outbound application can process it. You configure an outbound application by using the outbound keyword on the service application-name command.
service application-name outbound
A typical scenario would be routing calls to different VoIP dial peers based on the caller response to a prompt. The inbound application plays the prompt and collects the caller input. You can use the caller input to modify the DNIS, resulting in a specific outbound dial peer being selected. The outbound application on this dial peer can then perform additional functions.
Tcl Packages and Parameter Namespaces
Cisco IOS Release 12.3(14)T also provided a method to define packages and added the Parameter Namespace, or parameterspace. Tcl packages are Tcl or C functions or subroutines that Tcl scripts call. These packages give programmers a method of creating a “toolbox” of common functions, which can reduce the development time for new applications. Cisco gateways are preloaded with some packages. The packages vary by Cisco IOS version. The show call application voice summary command lists all available packages. Developers can create and load new packages using the package command in application configuration mode.
package package-name location
Parameter Namespaces, or parameterspaces, were added to prevent problems with two or more applications or packages that use the same parameter names. When you load an application or package, its parameterspace is defined. The parameterspace allows you to set initial values for parameters outside your local parameterspace. For example, your application might call functions that are defined in a package. Because the package has a defined parameterspace, you can set the initial values for the package parameter under your service configuration.
Tcl Parameters in Cisco IOS Release 12.3(14)T and Above
Cisco gateways support both global and local parameters. Global parameters are available to all scripts that run in the gateway. An example of a global parameter is a parameter used in a package, as just described. A single script or package uses local parameters. You set initial values for global parameters by using the paramspace command.
paramspace parameter-namespace parameter-name parameter-value
You set initial values for local parameters by using the param command:
param parameter-name parameter-value
The param command is used under the service or package. The “Implementing the AA Tcl Script” section in this chapter demonstrates the use of the paramspace and param commands.
Note
If you change a parameter value, you must reload the script for the changes to take effect.
With the introduction of parameterspaces, you can set parameter values under the service, package, or dial peer using the paramspace command. The ability to set parameter values in the dial peer strongly influences the way that a script functions. For example, assume that a company has two departmental receptionists—one for sales at extension 2000 and one for service at extension 3000. The company has published unique numbers for the two departments, so it has an incoming dial peer for each departmental number. You can load the same AA application on the two incoming dial peers. In one dial peer, you could set the operator number to 2000, whereas in the other, you could set the operator number to 3000. Prior to this Parameterspace feature, you would have needed to load the AA application twice, with two unique application names.
Note
You should register parameters in an application per the TCL IVR 2.0 Programmer’s Guide. Some Tcl scripts available from Cisco have not been updated to register their parameters. When you set the initial value for these parameters using the param command, you might receive a warning message stating that the parameter has not been registered under the namespace. This should not affect the operation of the script.
Order of Parameter Precedence
If you configure the same parameter in multiple locations, the value that you assign in the dial peer takes precedence over the value that you assign in the service configuration mode. The value that you assign in the package configuration mode has the lowest precedence.
Upgrading to Cisco IOS Release 12.3(14)T and Later
The call application voice commands in previous versions of Cisco IOS are automatically updated to the new format. No manual reconfiguration is required. In Cisco IOS Release 12.3(14)T, the call application voice command is still available, but no help exists for the command. If you enter the call application voice commands, they appear in your configuration file in the new application format.
Caution
Downgrading from 12.3.14T to an earlier version does not automatically modify the application commands. You should always back up your configuration file before upgrading to a new Cisco IOS release.
Implementing the AA Tcl Script
Figure 15-3 shows the call flow that is associated with the AA script for CME.
The script takes the following actions when a call matches the incoming dial peer that is configured with the AA script:
• A caller places a call to the AA pilot number.
• The script plays Prompt en_welcome.au, thanking the caller. Then it plays Prompt en_enter_dest.au, asking the caller to enter an extension.
• If the caller enters no digits or presses 0, the script transfers the call to the operator extension that is configured in the command-line interface (CLI).
• If the caller enters an invalid destination, the script plays en_reenter_dest.au prompt, asking the caller to reenter the destination. The script repeats this up to three times. After the third time, the script plays en_disconnect.au prompt and disconnects the call.
• If the caller enters a valid extension, the script transfers the call.
• If the extension is busy, the script plays the en_dest_busy.au prompt, asking the caller to enter a different extension or try the call at a later time.
• If the extension is unreachable, the script plays the en_dest_unreachable.au prompt, asking the caller to enter a different extension or try the call at a later time.
Example 15-1 illustrates the configuration required to load the Tcl AA script for CME from the flash of the router.
Example 15-1. Loading the Tcl AA Script for SRST
Miami#config t
Miami(config)#application
!
! Load the AA script from flash
!
Miami(config-app)#service aa flash:its_CISCO.2.0.1.0.tcl
!
! Configure the AA parameters that are associated with the English package
!
Miami(config-app-param)#paramspace english language en
Miami(config-app-param)#paramspace english location flash:
Miami(config-app-param)#paramspace english prefix en
Miami(config-app-param)#paramspace english index 1
!
!Configure the AA application local parameters
!
Miami(config-app-param)#param operator 150
Miami(config-app-param)#param aa-pilot 100
!
! Apply the AA script to the dial peer
!
Miami(config)#dial-peer voice 100 pots
Miami(config-dial-peer)#incoming called-number 100
Miami(config-dial-peer)#service aa
Miami(config-dial-peer)#direct-inward-dial
Miami(config-dial-peer)#port 1/0/0:1
Example 15-2 illustrates the configuration required to load the Tcl AA script for CME prior to Cisco IOS Release 12.3(14)T. The dial peer configuration is the same as in Example 15-1.
Example 15-2. Loading the Tcl AA Script Prior to Cisco IOS Release 12.3(14)T
Miami#config t
Miami(config)#call application voice aa flash:its_CISCO.2.0.1.0.tcl
Miami(config)#call application voice aa language 1 en
Miami(config)#call application voice aa operator 150
Miami(config)#call application voice aa aa-pilot 100
Miami(config)#call application voice aa set-location en 1 flash:
Creating Audio Files
You can rerecord audio files to meet your business needs. When you are using Cisco-provided Tcl scripts, you must save audio files using the same names. Audio files must have these properties:
• au format
• 8-bit
• μ-law
• 8-KHz encoding
Restrictions and Caveats
You need to keep several important restrictions in mind when you are applying or developing applications:
• To collect digits over an IP call leg, configure DTMF-Relay.
• RTSP multicast is not supported.
• Tcl IVR 1.0 and Tcl IVR 2.0 are not compatible.
• For VoiceXML, the web server must support HTTP 1.1.
• Load Dynamic VoiceXML documents by using HTTP. Using FTP or TFTP impacts performance.
• VoiceXML does not support ISDN Overlap signaling.
• You cannot apply applications to CallManager-controlled Multiple Gateway Control Point (MGCP) gateways.
• The SRST and CME AA scripts only work on POTS dial peers. They do not support calls from IP phones.
Case Study: Implementing ACD Application
The Leeds branch wants to implement a simple ACD for the service department, as shown in Figure 15-4. The three service technicians will answer calls to the pilot number of 496-0400. The manager wants all available phones to ring simultaneously to reduce the amount of time that callers have to wait.
Figure 15-4. Leeds Branch ACD Call Flow
To implement this solution, download the B-ACD version 2.1.0.0 Tcl script, load it on the flash of the Leeds gateway, and rerecord the prompts. Because only one queue is available, you can implement the B-ACD script in “drop-through” mode. This mode plays an optional welcome audio prompt and then sends the call to the queue. If multiple queues exist, you can configure the AA application with multiple pilot numbers and provide the capability to dial by extension. Example 15-3 details the configuration required to enable the B-ACD application. The parameters are subject to change based on the version of the script. Always review the Readme file for any script downloaded from Cisco.com to determine how to set parameters.
Example 15-3. Configuring the B-ACD Tcl Script
Leeds#show config
!
!Unnecessary output omitted
!
ip dhcp excluded-address 10.40.25.1 10.40.25.99
ip dhcp excluded-address 10.40.50.1 10.40.50.99
!
ip dhcp pool Data
network 10.40.25.0 255.255.255.0
default-router 10.40.25.1
dns-server 10.1.25.100
!
ip dhcp pool voice
network 10.40.50.0 255.255.255.0
default-router 10.40.50.1
dns-server 10.1.25.100
option 150 ip 10.40.50.1
!
application
!
! Load the acd script from flash and define the service name as queue
!
service queue flash:app_b_acd_x.x.x.x.tcl
param queue-len 10
param aa-hunt1 6400
param number-of-hunt-grps 1
param queue-manager-debugs 1
!
! Load the acd-aa script from flash and associate it with the queue service
!
service aa flash:app_b_acd_aa_x.x.x.x.tcl
paramspace english location flash:
paramspace english index 0
paramspace english language en
param aa-pilot 5400
param call-retry-timer 15
param second-greeting-time 60
param max-time-call-retry 600
param max-time-vm-retry 2
param service-name queue
param hand-off string aa
param drop-through-option 1
param drop-through-prompt Leeds_svc_welcome.au
param voice-mail 5350
param number-of-hunt-grps 1
!
voice translation-rule 1
rule 1 /(4960)(...)/ /52/
!
voice translation-profile Chg_DNIS
translate called 1
!
controller E1 1/0
ds0-group 1 timeslots 1-31 type r2-digital r2-compelled ani
!
voice-port 1/0/0:1
translation-profile incoming Chg_DNIS
!
dial-peer voice 5400 pots
service aa
incoming called-number 5400
port 1/0/0:1
!
telephony-service
load 7960-7940 P00307020200
max-ephones 120
max-dn 240
ip source-address 10.40.50.1 port 2000
max-conferences 8 gain -6
!
ephone-dn 42
number 5442
!
ephone-dn 43
number 5443
!
ephone-dn 44
number 5444
!
ephone 42
mac-address 4242.4242.4242
button 1o42,43,44
!
ephone 43
mac-address 4343.4343.4343
button 1o42,43,44
!
ephone 44
mac-address 4444.4444.4444
button 1o42,43,44
!
! Build the hunt group with the three technician phones
! Selected a pilot number outside the range for Leeds
! since only the queue application will use this number
!
ephone-hunt 1 sequential
pilot 6400
list 5442,5443,5444
!
Review Questions
1 Why would you choose to implement an application in Tcl instead of VoiceXML?
2 Why would you choose to implement an application in VoiceXML instead of Tcl?
3 What is the precedence order for setting parameter values?
4 What is a package?
5 What is the purpose of a parameter namespace?
6 What application enhances the network management capabilities of Cisco routers?
7 What protocol can you use to increase the size and number of prompts available to an application?
8 What are the requirements for recording an application prompt?