Customizing the Cisco UE AA

The system AA is fairly simple, and the menu flow cannot be customized. (The only customization possible is rerecording the greetings, setting the business hours and holiday dates, and setting the operator extension.) If a different AA menu flow is needed, a custom AA script must be placed on the system. Up to five AAs (including the system AA) can be loaded into the Cisco UE system to provide a wide range of flexible AA menus to cover very specific business needs.

This section of the chapter covers how to prepare a custom AA script using the Cisco UE AA Script Editor. You'll explore script elements such as steps, parameters, and variables. You'll learn about operations such as viewing, uploading, downloading, and executing scripts. System limits governing scripts and prompts on your system are also discussed.

AA Scripts, Prompts, Variables, and Parameters

To understand how to build a custom AA script, some programming knowledge is helpful. However, even if you do not have any programming background, customizing an AA script is not a complex task. The Cisco UE Script Editor provides a graphical drag-and-drop interface for easily rearranging the steps in a script. An AA script is essentially a computer program, which means that it is a list of steps executed for every call that arrives at the system. The sequence of these steps is specified at a very high level with an easy-to-use icon-based GUI interface.

An AA script is an ordered, logical sequence of actions called steps. Each step signifies a task or operation to be performed on the call, such as playing a prompt, collecting DTMF digits, or redirecting a call to another destination. Each script step has one or more attributes associated with it, such as the Menu step in which the attributes describe what should be done when the caller presses 1 or 2 or any other DTMF digit on the phone keypad.

The following elements make up an AA script:

• Steps Programming steps in the script perform actions such as answering the call, playing prompts, receiving DTMF digits from the caller, making conditional choices based on time-of-day or any other internal value, transferring a call, looking up a username in a directory, and many more.
• Prompts Scripts use short sections of recorded voice to interact with the caller, such as "Please enter the extension of the person you want to reach," "Press 1 for sales," or "Our business hours are 8 a.m. to 5 p.m. Monday through Friday." Each of these recorded voice segments is called a prompt and is referenced by the script as a variable. A prompt is physically stored in a .wav file on the system.
• Variables A variable is a label or tag representing a value that may change during the life of the script. For example, retry_limit may be a variable referenced in a script. This tag has a value of three or five, indicating how many times you want to retry a prompt after a timeout.
• Parameters A parameter is a variable whose value can be changed while the script is running on the Cisco UE system. In other words, you can change the value without editing the script and reuploading it to the system. For example, operExtn is a parameter that can be populated with extension 3001 on Monday and 3002 on Tuesday and so on without the need to edit the script. Not all script variables have to be parameters. Only those that you want to change without editing the script are assigned the property of parameter.

Preparing a Script Using the Cisco UE AA Editor

Custom AA scripts are executed on the Cisco UE system, but they are prepared offline on a Windows PC platform by using the Cisco UE AA Editor. Follow these steps, which are shown in Figure 9-4, to prepare and install a custom Cisco UE AA script:

Step 1.	Install the Cisco UE AA Editor software (from CD or by downloading it from Cisco.com) onto a Windows 2000/XP PC or server.
Step 2.	Open the Cisco UE Editor to create or edit an AA script. After all the editing changes have been made, validate the script to ensure that no logic errors exist in it.
Step 3.	Record the prompts used by the script either offline in a recording studio, with standard PC .wav file recording equipment, or via any telephone connected to the Cisco UE system.
Step 4.	Upload the script to the Cisco UE system. If prompts were recorded offline, these too must be uploaded to the Cisco UE system.
Step 5.	Assign values to all script parameters. Associate the script with a phone number (pilot number) so that callers can reach the script.

Figure 9-4. Preparing a Custom Cisco UE AA Script

The Cisco UE AA Editor has several window panes that allow you to construct different aspects of the script, such as the steps, variables, and parameters. Instead of opening an empty file and creating a script from scratch, you may find it easier to reuse several sample scripts available on Cisco.com. The sample scripts can expedite your construction of a custom script. You can open the sample scripts in the Editor, and then copy and paste script segments that you want in your AA menu flow rather than creating a completely new script.

The Cisco UE AA Editor Panes

After you have downloaded and installed the Cisco UE AA Editor onto your PC and have downloaded the sample scripts from Cisco.com, you can open the script files in the Editor application. As with any other Windows application, you can launch the Editor, and then choose files to open. Or you can simply double-click an existing .aef (script) file to launch the Editor automatically (provided that your PC is set up to associate the Editor application with .aef files). Figure 9-5 shows what the Cisco UE Editor screen looks like with an open script.

Figure 9-5. Cisco UE Editor Screen

The Cisco UE Editor window consists of the following four panes:

• Palette pane This is the top-left pane shown in Figure 9-5. It includes the palette of icons (representing the steps) that can be used in a script.
• Design pane The top-right pane shows the script's content. This is where the steps are sequenced to form the design or flow of the script under construction.
• Variable pane The bottom-left pane shows the variables defined in the script. Columns show the type, current value, and attributes of each variable. The last variable shown in Figure 9-5, MainOperExt, has an attribute of Parameter. The variable pane is where variables are marked as parameters such that as soon as the script is installed on a Cisco UE system, the value of a parameter variable can be viewed and controlled without editing the script.
• Debug pane When a script is validated, any error or warning messages are shown in this window pane.

The Cisco UE Editor uses a simple and intuitive GUI. Expert users can create sophisticated AA scripts using multilevel nesting and conditional statements. Novice users may find it easiest to start with an existing script, such as one of the sample scripts covered in the "Using Sample Scripts" section later in this chapter, and merely adjust it slightly to suit their needs rather than writing a script from scratch.

After it has been edited and validated, a script is saved to the local hard disk on the PC as an .aef file. It can then be uploaded to Cisco UE (using the GUI or command-line interface [CLI]) to be installed and executed as the system's AA.

Constructing a Script

The Cisco UE AA Editor allows you to have multiple script files open at one time, or you can have multiple Editor windows open on your PC, each viewing a single script file.

A script is constructed by using a series of steps to control a call's flow. You can start by opening an existing script and rearranging the sequence of steps, copying and pasting steps from another file to new positions in the Design Pane, or dragging steps from the Palette Pane to the Design Pane to build a new sequence of steps. Many steps have attributes that must be checked or filled in on a dialog box. You can access these attributes by right-clicking the step in the Design Pane and selecting Properties from the resulting Windows menu.

A typical script is constructed from the following components:

• Start step This starts execution of the call in the script.
• Accept step This step answers the call and opens a speech path between the caller and the application.
• Menu and Play Prompt steps Usually a series of these steps form the main body of the AA script. A menu (with multiple choices) or a single prompt is played to the caller. After that, the script waits for input on the caller's selection from the menu.
• Call Redirect step This step transfers the call to a selected destination, of which the value is usually kept in a variable in the script that was filled in during an earlier step.
• Call Subflow step An optional step to pass control of the call to another script. When it finishes executing that script, the phone call returns to executing in the calling script.
• Goto and If steps Unconditional or conditional branching within the script steps to control the flow of execution based on variable values or input from the caller.
• End This terminates the script and ends processing of this call.

A full explanation of every step and step attribute that you can use in a script is beyond the scope of this chapter. The Cisco UE Editor is based on the Cisco Customer Response Solutions (CRS) Editor. Therefore, you can use the Cisco Customer Response Applications Developer's Guide (available at Cisco.com) as reference material for a detailed explanation of each step and its attributes. The Cisco UE Editor supports fewer steps than the full Cisco CRS Editor used with some other Cisco products.

The Cisco UE Editor uses several categories of steps to perform AA tasks. These categories are shown in the Palette Pane of the Cisco UE Editor window and include the following:

• General steps
• Contact steps
• Call Contact steps
• Media steps
• User steps
• Prompt steps

The following tables list the exact steps in each category available in the Cisco UE Editor.

Note

The term step is used here to denote the individual actions you are building into a script. No sequence is implied in the steps listed in the following tables; instead, they are listed alphabetically. You can use these steps in almost any sequence you like in a script. (Obviously steps such as Start and End will occupy a certain logical position within the script, but steps such as Menu and Redirect can be used anywhere.) When you build the content of the script in the design pane of the Editor is when you apply your preferred sequencing to the steps.

Table 9-1 lists the steps in the general category.

Table 9-1. General Steps

Step Name	Description
Annotate	Comments in the script (similar to the C language /* */ comments).
Business Hours	Configures the business hours schedule for each of the seven days in a week.
Call Subflow	Invokes a subflow (one script passing control to another script).
Day of Week	Used to branch, depending on the current day of the week.
Decrement	Decreases the value of an integer variable by one.
Delay	Pauses the script's execution for a specified number of seconds.
End	Ends the script and frees all the allocated resources.
Goto	Causes script execution to branch to the specified Label step.
Holiday	Specifies a list of dates to be treated by the system as holidays. A maximum number of 26 holidays can be entered into the list.
If	A branch based on the evaluation of a Boolean expression.
Increment	Increases the value of an integer variable by one.
Label	Inserts a label into a script as a target for the Goto step.
On Exception Clear	Removes an exception set by the previous On Exception Goto step.
On Exception Goto	Catches an exception or problem during script execution and handles it.
Set	Changes the value of a variable (assignment operator).
Start	Start of the script.
Switch	Causes script execution to branch to one of a number of cases.
Time of Day	Used to branch, depending on the current time of day.

Table 9-2 lists the steps in the contact and call contact categories.

Table 9-2. Contact and Call Contact Steps

Step Name		Description
Contact	Accept	Answers a call.
	Get Contact Info	Extracts information from a contact and stores it in script variables.
	Set Contact Info	Modifies the context information associated with a contact.
	Terminate	Disconnects a call.
Call Contact	Call Redirect	Redirects a call to another extension.
	Get Call Contact Info	Accesses call-specific information and stores it in script variables.

Table 9-3 lists the steps for the media category.

Table 9-3. Media Steps

Step Name	Description
Explicit Confirmation	Confirms an explicit response to a promptDTMF 1 for yes and 2 for no.
Get Digit String	Collects DTMF digits in response to a prompt.
Implicit Confirmation	Confirms an action without asking a question.
Menu	Provides a menu from which the caller can choose from a series of options.
Name To User	Collects DTMF and tries to match it to a person's name.
Play Prompt	Plays a specified prompt to the caller.

Table 9-4 lists the steps for the user and prompt categories.

Table 9-4. User and Prompt Steps

Step Name		Description
User	Get User Info	Accesses user attributes.
Prompt	Create Conditional Prompt	Creates one of two prompts based on the evaluation of a Boolean expression.
	Create Container Prompt	Combines multiple prompts into a larger prompt.
	Create Generated Prompt	Creates prompt phrases from intermediate variablesfor example, number, currency, and so on.

Example 9-3 shows the logic of one of the sample AA scripts you can download from Cisco.com. It illustrates how the steps are sequenced in a script to determine the flow of the AA menu for a caller. This simple script illustrates how to build a basic office hours-based AA menu. During office hours, a menu (dial-by-number or transfer to the operator) is given to the caller. After hours a recorded prompt is given, telling the caller when the office is open.

Example 9-3 is not meant to be an example of a complete AA script. It is merely a script fragment illustrating the use of the time-of-day and day-of-week steps to build a branch into a script based on office hours. In a complete AA script, the office hours menu choices, the after-hours caller options, and the error-handling script instructions would be much more comprehensive.

Example 9-3. Sample AA Script

Start
/* S1_Main-OfficeHours.aef */
/* Basic Day-Of-Week and ... */
Accept (contact: --Triggering
/* Office Hours check */
Day of Week
 Weekdays
 Time of Day
 Work hours
 Goto Main Menu
 After hours
 Goto After-hours
 Weekend
 Goto After-hours
/* Main menu: Press 1 if ... */
Main Menu:
Menu (contact: --Triggering Contact--, prompt: S1_MainMenu)
 Dial by Number
 Call Subflow -- S1_DialbyExtension.aef
 End
 Operator
 Call Subflow -- S1_XfertoOper.aef
 End
 Timeout
 Play Prompt (contact: --Triggering Contact--, prompt: S1
 _SystemProblems)
 Terminate (contact: --Triggering Contact--)
 End
 Unsuccessful
 Play Prompt (contact: --Triggering Contact--, prompt: S1
 _SystemProblems)
 Terminate (contact: --Triggering Contact--)
 End
/* Present after hours msg ... */
After-hours:
Play Prompt (contact: --Triggering Contact--, prompt: S1_AfterHours)
Terminate (contact: --Triggering Contact--)
End

Figure 9-6 shows the same script open in the Cisco UE Editor, where the graphical representation of the steps can be seen.

Figure 9-6. Sample AA Script

 

Using Sample Scripts

The Cisco UE Editor and scripting design offers maximum flexibility to customize the system to your individual business needs. However, it can be somewhat daunting to write your first script, especially if you are unfamiliar with programming.

For this reason, a number of sample scripts, or script fragments, have been developed to help you cut and paste to build an AA script from known elements, rather than requiring you to develop it from scratch. These sample scripts are posted on Cisco.com and can be accessed from the Software Center, where Cisco UE software is downloaded.

The contents of these sample scripts may change over time, but in general they offer script fragments or examples of the following functions:

• A dial-by-number component
• A dial-by-name component
• Call transfer to an operator or a given extension
• An office hours menu using time-of-day and day-of-week branching
• A loop that repeats a menu three times, in case no input is received from the caller
• An office directory (a menu that has a branch for each individual in the office)
• A branch that gives the caller the office location and directions
• A branch that gives the caller the option of leaving a message (not for an individual employee, but for the business in general)
• The EAG

Using the EAG in a Custom Script

As explained in the earlier "Emergency Alternate Greeting" section, the EAG is a system function that is executed automatically by the system AA script. It is not automatic, however, in your custom AA scripts. Any script can call on this system function, but a Call Subflow step to the EAG script must be inserted into your custom script at the location in the sequence where you want to call out the EAG.

The EAG is implemented on Cisco UE as a system script called checkaltgreet.aef. To activate the EAG feature within your script, all you have to do is insert a Call Subflow checkaltgreet.aef step into your script at the appropriate spot, as shown in Figure 9-7.

Figure 9-7. Including the EAG in a Custom Script

The general EAG feature operation has not changed; it is still activated by the existence or absence of the actual greeting. It is stored in a .wav file called AltGreeting.wav, just as it operates with the system AA. But now you have incorporated the EAG feature into your own custom script.

Validating a Script

Before a script can be uploaded to Cisco UE for execution, you should validate it in the Editor. This function is found on the Tools menu on the Editor's Windows toolbar.

Validating a script is a necessary but insufficient step to ensure correct operation of your custom AA script. It is a necessary step because any syntax or flow errors caught by the validation step will prevent the script from executing properly. All validation errors must therefore be fixed before the script is uploaded to Cisco UE. However, it is an insufficient step, because the Cisco UE Editor cannot check runtime error conditions that may occur when the script executes. It also cannot check for missing prompts (missing .wav files) referenced by the script, because the Editor has no access to the script's runtime environment. These types of errors can be found only during script execution.

Viewing Scripts and Prompts in the System

You can use the Cisco UE GUI or CLI to manage AA scripts and prompts. Scripts cannot be edited on the Cisco UE system; they are edited offline on a PC with the Cisco UE Editor. You can manage the AA scripts on the Cisco UE system, including operations such as

• Listing the scripts present in the system
• Deleting a script
• Uploading or downloading a script
• Associating a script with a phone (pilot) number
• Setting a script's parameter values

Figure 9-8 shows an example of a Cisco UE system with a number of scripts installed. You can access this screen by selecting Voice Mail > Scripts from the GUI menu.

Figure 9-8. Listing the AA Scripts in a Cisco UE System

Scripts that have a checkbox to the left and grayed out are system scripts. The others are custom scripts. A script can call another script (using the Call Subflow step), so not each of these scripts is an AA. Some of the scripts are associated with a phone (pilot) number and therefore constitute an AA. The other scripts are merely subflows (subroutines) called by the main AA script(s) to make the logic easier to understand and to allow you to craft reusable functions, such as the EAG, which you can use in many AA scripts. This relationship between the scripts cannot be seen in Figure 9-8. You have to open a script in the Cisco UE Editor to see which other scripts (subflows) are called from the script you are viewing.

You can see a list of prompts present on a Cisco UE system by selecting Voice Mail > Prompts from the GUI menu, as shown in Figure 9-9.

Figure 9-9. AA Prompts in a Cisco UE System

The scripts and prompts present on the system can also be seen from the CLI of the Cisco UE system. Example 9-4 presents the CLI command and output to show all the scripts available on the system. Each script is shown (the name of the script file is highlighted), followed by its parameters. The CLI doesn't indicate whether a script is a system or custom script.

Example 9-22. CLI That Shows Scripts on a Cisco UE System

cue>show ccn application
Name: autoattendant 
Description: autoattendant
Script: aa.aef
ID number: 2
Enabled: yes
Maximum number of sessions: 8
MaxRetry: 3
operExtn: 0
welcomePrompt: AAWelcome.wav
Name: promptmgmt 
Description: promptmgmt
Script: promptmgmt.aef
ID number: 3
Enabled: yes
Maximum number of sessions: 1

Name: main-dow-tod 
Description: main-dow-tod
Script: s1_main-dow-tod.aef
ID number: 4
Enabled: yes
Maximum number of sessions: 8
MainOperExt: 6001

Name: s2-office-dir 
Description: s2-office-dir
Script: s2_main-office-dir.aef
ID number: 5
Enabled: yes
Maximum number of sessions: 8
Mary: 6001
Mike: 6012
Bruce: 6020
S2_OfficeDir: S2_OfficeDir.wav
S2_FaxInfo: S2_FaxInfo.wav
Candice: 6007
S2_LocationInfo: S2_LocationInfo.wav
John: 6005
Janet: 6008
S2_MainMenu: S2_MainMenu.wav

Name: s4-dial-by-name 
Description: s4-dial-by-name
Script: s4_main-dialbyname.aef
ID number: 7
Enabled: yes
Maximum number of sessions: 8

Name: s5-emerg-alt-grt 
Description: s5-emerg-alt-grt
Script: s5_main-emergaltgrt.aef
ID number: 6
Enabled: yes
Maximum number of sessions: 8

 

Uploading and Downloading Scripts

After a script is edited and validated on an offline PC, it is uploaded to the Cisco UE system to be associated with a pilot phone number and, thus, to run as an active AA. Also, if you need to change a script, download it from Cisco UE to your PC, where you can view its content, edit it, and revalidate the new script. Upload the new version to Cisco UE to make the change active.

You can upload a script by clicking the Upload button on the Voice Mail > Scripts GUI screen. The resulting screen is shown in Figure 9-10. There is a Download button on the same Voice Mail > Scripts screen to start a download operation.

Figure 9-10. Uploading an AA Script to the Cisco UE System

Note

The Cisco UE system scripts cannot be uploaded, downloaded, viewed, or deleted. Custom scripts can be fully controlled.

 

Executing a Script

The AA in Cisco UE runs as a Workflow script. It interacts with the Workflow engine and various subsystems to perform the operations specified in the AA script. (The basic architecture of the Cisco UE system is covered in Chapter 3, "Cisco IPC Express Architecture Overview.") A Workflow is a Cisco-developed scripting format that can be executed by an engine. This Workflow format is used in a variety of Cisco products. Cisco UE is also used to run the system's GMS and voice mail components. Understanding the script execution environment is necessary only for troubleshooting purposes.

When a call is placed to the AA pilot number, the Workflow engine is notified of the incoming call by the underlying call control subsystem. Based on the configuration, the engine recognizes that this particular phone number is associated with the AA (as opposed to the GMS or voice mail scripts), so it starts (triggers) the appropriate AA Workflow script and starts executing it. The engine starts from the first step in the script. Based on the output of each individual step, the execution either moves on to the next step or branches to some other location in the script to continue execution there.

For the execution of each step, the engine communicates with either a library or an underlying subsystem to perform the actual operation. For example, the engine communicates with the media termination library to play a specific prompt to the caller, and the prompt is streamed out by the media termination library. Similarly, the engine communicates with the call control subsystem to redirect the call. Based on the results reported by the subsystem, it carries on with the execution of the next step in the script.

System Limits on Scripts and Prompts

Many more scripts and prompts may exist on the Cisco UE system than are actively executed as part of the AA. As explained in the earlier section "Viewing Scripts and Prompts in the System," not every script is an AA. An AA is a phone number associated with a script that is the main entry point for that AA. This script may call on other scripts with the Call Subflow step to handle sections of the AA menus.

The Cisco UE hardware platform has limited storage space for scripts and prompts. Table 9-5 lists the system limits on custom scripts and prompts for Cisco UE 1.1, 2.0, and 2.1 software. Consult Cisco.com for changes in these limits that may become effective in later software releases.

Table 9-5. System Limits for Scripts and Prompts

Hardware Platform	Maximum Number of Stored Scripts	Maximum Number of Stored Prompts
NM-CUE	8	50
AIM-CUE	4	25

The limits shown in Table 9-5 do not apply to or include system scripts or prompts. There is no limit on the size of an individual script, the number of steps per script, or the number of nesting levels within a script. Script complexity and readability become limiting factors before the software limits these attributes.

A prompt may have a maximum file size of 1 Mb, which represents about 2 minutes of recording time.

The Cisco UE Greeting Management System