Using the Script Editor
This chapter provides information on using the Cisco Unity Express Script Editor.
Overview of the Cisco Unity Express Script Editor
The Cisco Unity Express Script Editor is a visual programming environment for creating autoattendant application scripts.
Figure 1 shows the Script Editor window, which is divided into the Palette (1), Design (2), Debug (3), and Variable (4) panes.
Figure 1 Cisco Unity Express Script Editor Window
Use the Palette pane to choose the steps you need to create your script. To display the contents of a palette, click the plus sign (+) to the left of the palette icon in the Palette pane.
Note If you try to drag a step to the Design pane when a customizer window is open, the Design pane will not accept the step. Before you drag a step to the Design pane, close any open customizer window(s), one or more of which may be hidden behind the Cisco Unity Express Script Editor window.
To create your script, click a step in the Palette pane and drag it on top of the step that it should follow in the Design pane. Each step performs a specific function and creates a portion of the underlying programming. You can customize most of the steps once you have placed them in the Design pane.
To add a step to your script, drag the step icon from the Palette pane and drop it onto the step it will follow in the Design pane. Place the steps in logical order for the script you are building.
To change the order of a step in the script, drag the individual step icon from its old location to its new location. To delete a step, select the step icon and press the Delete key.
To end the script, click the General palette and drag End to your script. The End step appears.
Many steps have output branches under which you add steps to provide desired script logic based on the exit condition of the step.
Script Example in the Design Pane
In Figure 2, the Menu step has five output branches:
Output branches often contain steps and other output branches. The DialByExtn output branch in Figure 2 contains five steps below it, one of which (the Get Digit String step) contains three output branches.
To expand the script under a step, click the plus sign (+) to the left of the step icon. To hide the script under a step, click the minus sign (-) to the left of the step icon.
At run time, each script follows a hierarchical sequence, as indicated by the vertical lines connecting steps. In Figure 2, for example, if the script reaches the Timeout output branch of the Get Digit String step, the script moves to the next step at the level of the Menu step, which, in this example, is the Play Prompt step.
Use the Design pane to create your script. Drag script steps from the Palette pane to the Design pane.
Most steps have properties which can be modified according to the needs of the script. Depending on the step, the properties can be grouped under multiple tabs. To display the properties window for a step, right-click the step in the Design pane and click Properties in the popup menu. For example, Figure 3 shows the Label step Properties dialog box.
Figure 3 Properties Popup Menu—Label Step
The Variable pane is where you add and modify the script variables. Variables store data that a script uses when it executes the steps. Any step in your script can use variables once you define them in the Variable pane of the Cisco Unity Express Script Editor window.
You can also map variables you define for your script to variables you define in a subflow, which is a set of steps that function as part of another script, called the primary script. A subflow can use and manipulate a variable, then return the data that is stored in the variable to the primary script. Scripts cannot share variables with other scripts, except in the case of default scripts, in which the primary script automatically transfers the values of its variables to a default script.
The value of a variable can change during execution.
Use the Variable pane to add and modify the script variables. Variables store user-defined data or the data resulting from the completion of a step or expression. Any step in your script can use a variable once it is defined. Because data comes in different forms, you must also declare a variable's type before you can use it. Variables are grouped into the following types:
Because data comes in different forms, you must also define the variable before you can use it. To define a new variable, click the New Variable icon (1 in Figure 4) at the top left corner of the Variable pane (1 in Figure 4). The Edit Variable window appears. After you use the Edit Variable window to define your variables, the variables appear in the Variable pane. Delete (2) deletes the selected variable. Use Modify (3) to change to the selected variable.
Figure 4 Variable Pane and Edit Variable Window
Table 2 describes the fields in the Edit Variable window.
Table 2 Edit Variable Properties
Name of the variable you want to declare.
Type of variable that you want to declare. See "Basic Built-in Data Types" section for the available variable types.
Fully qualified class name located using the CLASSPATH environment variable on your computer.
Note The field displays the actual Java type corresponding to the built-in data type chosen in the Type drop-down menu.
Data you initially assign to a variable. The type of data you enter must match the data type you declared in the Type field.
If checked, sets the value for this parameter in the autoattendant web interface when you provision applications that use this script.
Basic Built-in Data Types
You must set the type for each variable you define. A variable's type indicates the kind of information a variable contains and allows the script to process that information accordingly. For instance, the script uses a variable containing the string "Tuesday" differently than a variable containing the number 25.
Table 3 describes the basic built-in variable types:
Table 3 Variable Types
A Boolean is either true or false, and is used primarily by the If step in the General palette of the Cisco Unity Express Script Editor:
A Character consists of alphanumeric characters:
•Lowercase letters a to z
•Uppercase letters A to Z
•Digits 0 to 9
•Any escape sequence: "\t", "\r", "\0", "\n", "\f", "\\", "\"
•"\uXXXX" can be used to represent any character using the character hexadecimal Unicode number XXXX
A Float variable includes decimal numbers.
All Float values are stored as Double values and typecasts down only when the Float value is assigned to a Float variable. This feature prevents any loss in precision by how Java stores Float values.
If a value cannot be stored as a Float, the value is automatically stored as a BigDecimal values and typecast to a Float value when assigned to a variable, with some loss in precision.
An Integer variable consists of whole numbers from -2147483648 to and including 2147483647.
The script first parses the value as an Integer. If this attempt is unsuccessful, the script parses the value as a Long. If this attempt fails, the script parses the value as a BigInteger. The script may typecast the value to an Integer when the value is assigned to a variable. If the script cannot represent the value as an Integer, the result may be unknown.
A String variable consists of a set of Unicode characters from "\u0000" to and including "\uffff":
•"Hello", "C:\WINNT\win.ini"—This format does not support any escape characters or Unicode characters.
•u"\"This is a quoted string\"", u"\tHello", u"\u2222\u0065", u"C:\\WINNT\\win.ini", and so on. This format supports the same escape sequences or Unicode characters described for the Character type.
The Date variable contains date information.
•D[Dec 13, 2003]
•D[January 20, 2003]
•D[Tuesday, April 12, 2003]
•D[12/13/03 5:50 PM]
•D[April 1, 2003 12:00:00 AM PST]
The parameter that you specify in between D is parsed based on any combination of the following two formats:
The Cisco Unity Express Script Editor supports four <date> specification formats:
•MEDIUM (Jan 12, 2003)
•LONG (January 12, 2003)
•FULL (Tuesday, April 12, 2003)
The Time variable contains time information:
•T[11:59:58 PM EST]
The parameter specified inside brackets of T is parsed based on the format "<time>".
The Cisco Unity Express Script Editor supports three <time> specification formats:
•SHORT, such as "3:30 PM".
•MEDIUM, such as "3:30:32 PM".
•LONG and FULL (which are identical), such as "3:30:42 PM PST".
The BigDecimal variable consists of an arbitrary-precision integer with a scale, where the scale is the number of digits to the right of the decimal point:
The BigInteger variable represents arbitrary-precision integers:
The Double variable represents an expanded Float variable.
If the script cannot hold the value as a Double, the script automatically stores it as a BigDecimal and typecasts it down to a Double when the script assigns a value to a variable with some loss in precision.
The Long variable is an expanded Integer variable.
The script first parses the value as a Long and if it fails, the script parses the value as a BigInteger. The script may typecast the value to a Long when the script assigns the value to a variable. If the script cannot represent the value as a Long, the result may be unknown:
Exporting Variables by Using Parameters
You can declare variables as parameters by clicking Parameter in the Edit Variables dialog box. This feature allows you to set the value for a parameter in the auto attendant web interface. Because the value is initialized at configuration time for the script that uses it, you can change the value without editing the script in the Cisco Unity Express Script Editor. Such a variable is called an exported variable or parameter.
For example, when you add a new automated attendant by using the AA Wizard, the second window of the AA wizard (the Script Parameters window) provides a list of the parameters with their default or current values. You can modify the values in this list.
The variable types that Cisco Unity Express supports for parameters include Number, Character, String, Boolean, and Prompt.
A Contact variable consists of a contact representing a telephone call. You can pass a Contact variable as a parameter to a subflow.
A Prompt variable contains the information that the script uses to create prompts for callers. A Prompt variable can be as simple as a single prompt or as complex as a concatenation of multiple prompts.
A User variable contains information that is useful for user authentication. You cannot manually enter a User variable as a value. User variables can be returned only from the Name To User step of the Media palette. You can pass a User variable as a parameter to a subflow.
The Debug pane displays the error messages output by the Validate and Debug tools. If these tools run error free, the Script Editor displays messages indicating their success.
Script validation, accessed through the Tools menu, provides an initial and rudimentary check of your script. Figure 5 show the error messages resulting from a misnamed Label step. Label step MainMenu1 should be named MainMenu. The error message "Dangling GoTo" indicates that there is no MainMenu label to go to. The error message "MainMenu not exist" also indicates this. The four "Dangling GoTo" error messages indicate that the Goto step refers to a misnamed or nonexistent label four different times in the script. Double-clicking the error message highlights the line in the script that the error message refers to, in this case each dangling Goto step.
Debug Pane Validation Error Messages
Debugging features, available through the Debug menu, enable you to debug your script using the CUE Editor. You can select the script to debug, use breakpoints, proceed step by step through the script, and see the values of variables change as the script runs.
You can access debugging features through the debug menu or the toolbar. The toolbar is shown in Figure 6. The callouts are describes in Table 4.
The debugging features are described in Table 4.
Table 4 Debug Menu Options
Runs the current script in debug mode.
Stops the script and allows you to view or change the current values of variables and step properties before resuming execution.
Ends the current script.
Skips the currently executing step.
Inserts a breakpoint at the currently executing step. This insertion causes the script to halt whenever it runs in debug mode but does not affect the runtime version of the script.
Toggles the selected breakpoint on or off.
Clear All Breakpoints
Removes all breakpoints from the script.
Prompts for the name and timeout setting of the event-triggered script to be debugged.
Note System scripts contain steps that are not shown by the CUE Editor and cannot be debugged.
There are two types of debugging modes available - Reactive Debugging and Non-Reactive Debugging. In both these modes, you can insert a breakpoint at a step to let the script execute up to that point, and then debug it starting with that step. During a debugging session, the Editor communicates with CUE continuously, as the actual script execution occurs on CUE, not on the local PC where the Editor is running. This communication occurs through an RMI connection on port 1099. For debugging to work, there must be network connectivity between the Editor PC and CUE. Also, port 1099 must not be blocked by an ACL or some other means.
Note In addition to port 1099, ports in the TCP 32xxx range can be used. These port numbers are not well known and are determined dynamically at run time.
To enable the Editor to communicate with CUE, configure the CUE hostname or IP address through the Editor: select Tools->Options menu as shown in Figure 7 and Figure 8. Network connectivity is not be verified at this time, it is verified when a debugging session is initiated.
Cisco Unity Express Host
The Debug menu is shown in Figure 9
The reactive debugging mode allows you to debug a script while it is running on the CUE system. This debugging mode allows you to debug scripts that are triggered by an external event. Currently, the only external event that can trigger a script on CUE is an incoming call. The script must be loaded into the CUE script repository, and be triggered by an incoming call. The script can be changed and saved on the local PC while debugging, but it must be uploaded to the CUE again in order to debug those changes.
To start a reactive debugging session, select the script to debug through Debug->Reactive Script menu in the Editor. The Editor contacts CUE for a list of all the custom scripts currently existing on CUE. If the Editor is not able to establish connectivity with CUE (either due to network problems or due to port 1099 being blocked), the editor displays an error message.
If the Editor is successfully able to fetch this list, then it will be presented to the developer in a dialog box. The developer can select the script to be debugged from the drop-down list in this dialog box, as shown below:
Select Script and Wait Time
Wait Time is the duration for which the Script Editor waits for an incoming call to trigger the execution of the selected script on CUE; an incoming call must trigger this script within this interval once the "OK" button is pressed. If the script is not triggered within this interval, an error message is displayed.
Once the "OK" button is pressed, the Editor registers with CUE to receive events for the selected script. As soon as a call comes in, the script automatically displays in the Design Pane of the Editor window as shown below:
Selecting a Script for Reactive Debugging
Reactive Debugging in Progress
At this point, the Editor has complete control of the script execution. The script does not start execution until you press the "Play" button (F5) or the "Step" button (F10) on the toolbar. The caller hears the ringback tone until the script execution is started and the call is answered.
The "Play" button causes the script to run until it reaches a breakpoint, needs some input from the caller, or reaches the end of the script. Each time the Step button is pressed the next step in the script is executed and execution halts.
You can click on any step in the script and insert a breakpoint at that step by clicking on the Breakpoint button on the toolbar. A breakpoint can also be inserted through the Debug->Insert Breakpoint menu item. An example of a breakpoint is shown inFigure 13 and Figure 14.
When the script execution proceeds, the step being currently executed is highlighted. The Variable Pane always displays the current runtime values of the variables as the script executes.
If a call is aborted while the debugging session is in progress, you can see error messages.
The script being debugged using the Script Editor can also be saved to disk on the local Editor PC (File->Save menu). This is a way of downloading a script from CUE.
Inserting a Breakpoint
Script with Breakpoint Inserted
This mode of debugging is used only for those scripts which do not require external events to trigger their execution - they do not have any steps that use a step with a triggering contact. This procedure is useful for debugging script segments or subflows. Since there is no incoming call associated with the script in this debugging mode, media streams cannot be established and hence any steps making use of media stream, for example PlayPrompt, GetDigitString, and so on, cannot be effectively debugged. Although scripts and subflows using the Media and Call Control steps can be debugged using non-reactive debugging, it is mostly useful for debugging scripts that perform some computation. Once a script segment has been debugged, it can be incorporated into a larger script.
To begin a non-reactive debugging session, open a script using the File -> Open menu.
Once the script has been opened, start debugging by pressing the "Play" button (F5) or the "Step" button (F10) on the toolbar. The rest of the debugging options and functions are the same as those described for reactive debugging in Reactive Debugging.
Even in this mode, the script execution happens on the CUE system, not on the Script Editor PC. However, in this case, the script is sent from the Script Editor to CUE over an RMI connection when the debugging session is initiated. So, this mode also requires the Script Editor to connect to CUE on port 1099. If the Editor is not able to establish connectivity with CUE, an error message is displayed when the Play button or the Step button is pressed.
There are limitations to consider when debugging a script:
•In reactive and non-reactive debugging mode, stepping into a subflow from a main script is not be possible. CUE executes the subflow without providing debug controls. This is like stepping over the CallSubflow step.
•Scripts with syntax errors are uploaded successfully in some situations (with a warning), but they cannot be debugged because calls to such scripts fail and the script never gets triggered.
•Only one script can be debugged at a time. An error message is displayed to another user trying to start a debugging session.
The Cisco Unity Express Script Editor uses the following two types of prompts:
•System prompts—Used internally by Cisco modules and Cisco sample scripts.
Note System prompts are used internally by the system. There is no guarantee about the continued availability of any system prompt in future releases.
•User prompts—Defined by the user and manageable by the administrator by means of the Voice Mail > Prompts web page of the Cisco Unity Express GUI administrator interface or by calling in to the Greeting Management System. The script retrieves both user and system prompts from the Prompt Repository.
All Media and Prompt steps support prompts specified in the following ways:
•String expression—User-defined prompts that are located in the User Prompts directory.
•Prompt expression—Dynamically created at run time.
Note You must define all prompts played back and recorded with a RIFF header of type WAVE and G711 u-law format.
For more information on managing the prompts, refer to the Cisco Unity Express GUI and CLI administration documents for your system that can be found at http://www.cisco.com/univercd/cc/td/doc/product/voice/unityexp/index.htm.
Expressions are useful if you do not know the exact value at design time and instead enter a formula that can be evaluated at run time. The resulting type of the expression must match the expected input type or types (which you check at design time).
Many steps include an Expression Editor (...) button(1 in Figure 15) in the customizer window, which you can use to enter an expression.
You can enter an expression directly in the input text field, or click Expression Editor (...) to open the Expression Editor.
You can enter the expression in the text field, or choose the Variable drop-down menu to get quick access to variables you have previously defined in the script. When you choose a variable from the Variable drop-down menu, the variable name appears in the input text field.
After you enter the expression, click OK. The Expression Editor closes.
Figure 15 Expression Editor Button and Expression Editor
To create expressions, use operators to combine variables and other values (also known as operands) to produce a result that is not known until the script is run. Operator priority refers to the order in which the operators are evaluated if there is more than one operator in an expression. The following operators are listed in order of priority:
1. Parentheses (...)—Works with any expression; allows you to give priority to the expression contained in the parentheses.
2. Multiplication (*), Division (/)—Works with any number expression (integer, long, float, decimal, BigInteger, BigDecimal).
Number operands are properly promoted to a valid type before testing.
3. Addition (+), Subtraction (-)—Works with any number expression (integer, long, float, decimal, BigInteger, BigDecimal).
Number operands are properly promoted to a valid type before testing.
4. Less Than (<), Greater Than (>), Less Than or Equal (<=), Greater Than or Equal (>=)
Comparison operands work only on String, Character, and Number operands.
5. Equal to (==), Not Equal to (!=)
Testing for the <null> constant is supported by the two equality operators.
6. And (&&)— Works only with Boolean expressions.
7. Or (||)—Works only with Boolean expressions.
8. Concatenation (+)
If at least one of the operands is a String, and the other one is not a prompt, then the other one is converted to a String by using the String.value() method. The result is a new String corresponding to the concatenation of the String representation of both operands. Typically, the String.valueOf() method simply calls the toString() method of the object being concatenated, or returns the string "null" if the object is null.
If the operands are Characters, then they are concatenated together, resulting in a new String.
The Cisco Unity Express Script Editor provides a variety of ways to handle exceptions. Exceptions are errors in scripts from unexpected user input or unexpected result in scripts.
Continue on Prompt Errors Step
The Continue on Prompt Errors option allows the script to continue to run when the script receives invalid input (for example, Invalid Audio Format or File Not Found).
The Cisco Unity Express Script Editor provides the Continue on Prompt Errors option in the customizer windows of steps in the Media palette. (See "Media Steps" on page 92.) For example, Figure 16 shows the Prompt tab of the Get Digit String customizer window.
Figure 16 Continue on Prompt Errors Option—Prompt Tab of the Get Digit String Customizer Window
When enabled, the step continues with the next prompt in the list of prompts to be played back. If the prompt is last in the list, the script waits for caller input.
When you enable Continue on Prompt Errors, you instruct the script to ignore prompt errors and continue as if the playback of a particular prompt was successful. For example, in a sequence of prompts "1 + 2 + 3", if prompt #1 fails, the step will continue with prompt #2. If prompt #3 fails, the step continues to wait for caller input as if prompt #3 had been properly played back.
When you disable Continue on Prompt Errors, the media steps generate an exception, which can then be handled in the script.
Available prompt exceptions are the following:
Error Output Branches
Error output branches are parts of a script that provide instructions on what to do when typical errors occur.
Figure 17 shows error output branches under a Call Redirect step in a script.
Figure 17 Error Output Branches—Call Redirect Step
In this figure, the Call Redirect step includes logic for both an invalid extension and an out-of-service extension.
Note The script provides error branches only for expected error conditions, not for system errors.
On Exception Goto Step
The On Exception Goto step of the General palette (see "On Exception Goto" on page 78) causes the script to continue running at a specified place in the script when an exception is generated.
By using the On Exception Goto step for a specific exception in a script, you can register a new handler for a specific exception or override a previously existing one.
The registration process affects the complete script. The assigned handler activates the script no matter where the exception occurs (before, during, or after the given step). After the step runs, the handler is registered until either a new handler is reregistered or the exception is cleared with the On Exception Clear step.
If an exception results in a subflow, the script first consults the exception handlers of the subflows. If none are defined for the given exception, the exception aborts the subflow, and the Cisco Unity Express application looks for exception handlers in the parent script. This process continues until the script finds an exception handler or the top level of the script is reached.
If no exception handlers are registered, the script aborts and error handling falls back to the last level of error handling, which is the default script.
Using Default Scripts
The default script is the last level of user-defined error handling before the Cisco Unity Express Script Editor applies a default system treatment to all active contacts.
The Cisco Unity Express Script Editor invokes this default script under the following conditions:
•The main script aborts, which happens for either of the following reasons:
–An uncaught exception occurs.
–The Cisco Unity Express application software is unable to invoke the primary script because it has not been properly validated.
•An incoming call must be aborted because the Cisco Unity Express application software has reached its limit for the number of simultaneous sessions for the application.
In each of these scenarios, the Cisco Unity Express Script Editor marks all active contacts as aborting before the default script is run. The final state of these contacts is Aborted, even if the contacts are transferred or redirected as a result of the default script running.
The purpose of the default script is to gracefully terminate the call when the main script fails, not to have a fallback to provide the original services intended by the primary script. This distinction is important because using system resources to run this default script may impair system performance. If the primary script fails too often, fix the primary script rather than provide another script to attempt the same task.
The default script does not run if the primary script ends normally. If contacts are still active when the primary script ends, all active contacts not marked as handled will abort, and all active contacts marked as handled are simply terminated. In this case, check the primary script for any design problems.
Note The default script provides only a final feedback to the contact regarding the system problem and does not continue the service or restart the service.
The system applies the CallContact script if the contact is still active after the system executes the default script (if any). The CallContact script plays back the prompt, "We are currently experiencing system problems, please call back later" as an announcement, followed by a fast busy signal.
Script interruption is a feature that allows external events to interrupt the current processing of a script in order to return to another part of the script or stop the execution of the script.
Script interruption is typically used when the script needs to be notified that one of its contacts has been remotely terminated, such as when the caller hangs up.
Note In every case, any event that triggers the need to interrupt the script can occur at any time while the script executes other steps.
By default, scripts are automatically interruptible before any step is executed. Should any external event (such as that described in the preceding text) interrupt the script, the script continues running based on the proper handling for the specific event before the script continues with the next step.
If you want two consecutive steps to run without the possibility of interruption, you must move these two steps to a subflow where you can disable interruptions completely while the script processes that subflow.
Cisco Unity Express Script Editor has an "interruptible" option for some steps that allows you to indicate whether or not the script can interrupt the step from within when an external event occurs.
When a contact terminates remotely, the script performs one of the following actions:
•When a caller hangs up, the script is interrupted (if possible) and a ContactInactiveException is generated. This exception can then be handled with the OnExceptionGoto step of the General palette.
•If a caller hangs up and no exception handling logic is available, the script immediately aborts.
•When managing multiple contacts, the OnExceptionGoto step cannot differentiate which contact was remotely terminated. Instead, it must specify a Label to which it can loop through all known contact variables and use the Get Contact Info step of the General palette to search for an Active flag.
If an interrupting event occurs when the script is not currently interruptible, the script is automatically interrupted whenever it becomes interruptible again. For example, although a script is not interruptible when it is running a subflow that is marked to disable interruptions, the script processes the interruption as soon as the subflow terminates, and control is returned to the parent (if that primary script is interruptible).
Installing the Cisco Unity Express Script Editor
This section describes how to install the Cisco Unity Express Script Editor application.
Note Do not install the Cisco Unity Express Script Editor application on hardware on which the Cisco Customer Response Applications Developer (CRA) Editor application is currently installed. These applications share registry files and will not work if installed on the same hardware.
The CUE Script Editor is a Microsoft Windows application. The computer you install it on must be running one of the following operating systems:
•Windows NT (Workstation or Server) with Service Pack 4 or later
•Windows 2000 (Professional or Server)
•Windows XP Professional
Follow these steps to install the Cisco Unity Express Script Editor:
Step 1 Download the Cisco Unity Express Script Editor software at the following URL on Cisco.com (registration required):
Select the specific Cisco Unity Express 2.3 version you are using.
Alternatively, you can install the Cisco Unity Express Script Editor from the Cisco Unity Express Application Software CD.
Step 2 Double-click the executable Cisco Unity Express Script Editor file. The filename will be similar to CUEEditorx.x.x.exe, where x.x.x is the release that you are installing.
The InstallShield Wizard appears and begins extracting files for the installation. (This process may take a few minutes.)
Step 3 Follow the prompts to install the application. A default installation is acceptable for most users: click Yes and Next buttons when prompted.
The prompts also allow you to move back to an earlier step in the installation process or cancel the installation completely.
Step 4 To verify that the application is installed correctly, start the application: on the task bar click Start, All Programs, Cisco CUE Developer, Cisco CUE Editor.
The default installation path on your hard drive is