Configuring the Gateway to Use a Tcl Script

Five steps are required to implement a Tcl application on a Cisco voice gateway:

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 fromeither 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 receptionistsone 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.