Dialog Designer Call Flow Elements

Dialog Designer Call Flow Elements A DevConnect Tutorial Table of Contents Section 1: Dialog Designer Call Flow Elements Section 1: Dialog Designer Call Flow Elements... 1 1.1 About this Tutorial When designing a call flow using Avaya Dialog Designer, there are a number of common elements often used by developers to reduce complexity. Section 2: Sub-flows... 2 Section 3: Phrases... 8 Section 4: Audio Variables...15 Section 5: Reporting Caller Hang-up Location... 22 Section 6: References... 28 This tutorial explains the following basic Dialog Designer call flow elements: 1. Sub-flows in call flow: Sub-flows are invoked from the main call flow to perform a defined task and return back to the main call flow for further operations. Sub-flows can be used to break down large call flows into smaller, modular call flows. This tutorial describes the process a creating a Dialog Designer sub flow and using sub-flows within a call flow. 2. Phrases and phrasesets: Phrases consist of prerecorded audio files used to build call flow prompts. Phrases within a Dialog Designer application can be grouped into phrasesets. This tutorial describes creating phrasesets using the Dialog Designer phraseset wizard and using phrases (with in a phraseset) in a Dialog Designer call flow. 3. Audio variables: Audio variables make use of prepackaged and prerecorded variables to play back standardized types of information to callers. Standard phrase sets are used, in conjunction with language localization bundles, to provide audio variable functionality to Dialog Designer applications. This tutorial describes using audio variables with in a prompt file in a call flow. Note: Before using audio variables, you must install the localization bundle and standard phrases for the corresponding language. 4. Reporting caller hang-up location: Dialog Designer applications can be customized to report the location of caller hang-ups within a call flow. This customized code looks back at the call stack to see the servlets (nodes) that were visited during the call flow, and to retrieve the information about the node where the caller disconnected from the call flow. DEVCONNECT TUTORIAL 1

Note: Each of the call flow element described above can be used independently in a call flow. The sections described below cover commonly used elements (or items) when designing a Dialog Designer call flow. 1.2 Prerequisites A basic understanding of Java programming and familiarity with Avaya Dialog Designer to create application call flows is required. This tutorial is primarily intended for application developers and managers already familiar with the technical aspects of speech application design and development, as well as a working knowledge of Dialog Designer. The examples and sample codes discussed in this tutorial are validated using Dialog Designer version 04.1.07 and Avaya Voice Portal version 4.1.0.2.0106. Section 2: Sub-flows Avaya Dialog Designer provides nodes and flow items for building call flows. These nodes and flow items use application resources such as prompts, phrases and grammars. In a Dialog Designer application, sub-flows can be invoked from the main call flow to perform a defined task before returning back to the main call flow for further operations. Sub-flows can be used to break down large call flows into smaller, modular call flows and improve readability of the call flow. A sub-flow is invoked by the main call flow using the sub-flow Reference node. This node defines a reference to a sub-flow defined in the project. The sub-flow mainly consists of two nodes: 1. Sub-flow Begin Node A Begin node is the entry point for a sub call flow. It is similar to the AppRoot/Start node for the main call flow. 2. Sub-flow Return Node This is the return point from a sub-flow, returning control back to the call flow which had invoked the sub-flow. It is similar to the Return Node of the main call flow. However unlike a Return node (in the main call flow), a sub-flow can have multiple return nodes. The properties of a sub-flow Reference node are: 1. Name An appropriate name that reflects the purpose of the node. 2. Flow Name The name of the flow that the sub-flow is associated with. 3. Comments Any description of the purpose or content of the node. This field could be left blank. 2

2.1 Demonstrating Sub-flows Consider the following Dialog Designer Application call flow (Figure 1): Figure 1: Sample Application main call flow The main call flow invokes two separate sub flows: Add and Subtract. The application plays a welcome message and prompts the callers to enter two numbers using the prompt and collect nodes Input_1 and Input_2. The application presents a caller with a choice to add or subtract these numbers. Add is responsible for calculating the addition of these two numbers, while Subtract is used for subtracting these numbers. In each of these sub-flows, the caller is given a choice to return to the main menu or exit the application. The input collected from the caller in the main flow is passed to the sub-flow. Figure 2: The Add Sub-flow demonstrates adding two numbers and returning results to the main flow 3

Figure 2 describes the Add sub-flow. The Add data node adds two numbers entered in the main call flow. The addition results are announced to the caller in the End_result node; subsequently the caller is given a choice to either replay the application or exit the application. Depending on the caller s choice, the respective return node in the sub-flow returns the value to the main call flow. The sub-flow return node points to the next node in the call flow. In this case, the sub-flow has the return nodes as replay and exit. Based on these return node values, the main call flow either replays the application or exits the application. Note: The above example flow describes encapsulating a section of the call flow in to a sub-flow. The Add and Subtract sub-flows described above can be used multiple times within the main call flow. 2.2 Creating a Sub-flow Step 1 Create a new call flow file by browsing to File -> New -> Call Flow File from the Dialog Designer menu (Figure 3). Figure 3: Dialog Designer menu selections to create a new Call Flow file. Step 2 Enter a unique Name of the sub-flow and click on Finish as shown in the screenshot below. A new.flow file is created in the project under the flow directory. 4

Figure 4: Name the new call flow file. This is the name of the sub-flow. Step 3 Create the appropriate call flow logic for the sub-flow using Dialog Designer. See Figure 2 for an outline of an example sub-flow. 2.3 Invoking a Sub-flow Step 1 Drag and drop a Sub-flow node from the palette on to the main call flow. Step 2 In the properties tab, select the appropriate call flow corresponding to the Flow Name property. A combo box lists the sub-flow names in the project (Figure 5). 5

Figure 5: Selecting a flow name in the Properties tab of a sub-flow node Once the call flow is complete, depending upon the caller s choice, the Add or Subtract sub-flow is executed. 2.4 Sub-flows versus Main Call Flows The key differences between main flows and sub-flows are listed below: Sub-flow A Begin node is the entry point to a sub-flow. Unlike the AppRoot node, a sub-flow Begin node cannot be edited and does not allow sub-items to be added. Sub-flows support multiple return points. Note: Each sub-flow return node forwards the request to the next node in the (main) call flow. Sub-items cannot be added to a sub-flow return. Main call flow An AppRoot node defines the entry point to a Dialog Designer (main) call flow. Sub-items (for example: catch) can be added to an AppRoot node. Note: An AppRoot node is the entry point into any call flow regardless of whether a call flow contains sub-flows. Main flows only allow one Return (exit) node. Sub-items (for example: Output parameter items) can be added to a main call flow return node. Table 1: Comparing Sub-flows and Main Call Flows 6

2.5 Sub-flow Features When using sub-flows, you should understand the following items: Sub-flows are always contained within the same application scope as the main flow. Sub-flows share the application context, session objects at runtime, project variables and resources, such as prompts, grammars, Database operations and Web Service operations. Sub-flows can be nested, i.e., one sub-flow can invoke another sub-flow. There is no limit to the number of sub-flows that can be placed in a Dialog Designer project. Sub-flow code is generated in a separate package. For example, MySub-flow.flow will generate Java code in the flow.sub-flow.mysub-flow package. For a sub-flow, the servlet names/mappings have a different format in the web.xml file. For example, MySub-flow.flow will have servlet names starting with MySub-flow-<node name>; servlet mappings start with /MySub-flow-<node name>. 2.6 Sub-flows vs. Dialog Designer Modules Dialog Designer modules appear similar in functionality to Sub-flows. However, modules are fundamentally different as they are separate speech projects that can be integrated into multiple application call flows, whereas sub-flows are specific to a project. Key differences between a Sub-flow and Module are listed below: Sub-flows Sub-flows can be used where project resources like prompts, grammars, variables are shared. Sub-flows are reusable only within a project. Sub-flows are not recommended where multiple developers (or teams) work on an application. It is likely that multiple sub-flows and resources are updated by different developers. Merging changes to these files is difficult. Sub-flows share the same application context at runtime. Sub-flows share session data and requests are forwarded while entering and exiting sub-flows. Sub-flows have better performance as they forward requests between servlets. Hence accessing sub-flows does not involve additional overhead. Modules Modules are used when project resources are self contained. Modules are reusable across projects. Developers can work on individual modules (projects) in an application without impacting files in other modules or the application. Modules have separate application context at runtime. Modules do not share session data and the Avaya VoiceXML browser fetches modules as VXML<dialog>. Modules require a VXML response back to a self service platform which creates a new dialog context (for the VXML sub-dialog) and then fetch the sub dialog (module) contents. Hence accessing a module requires multiple VXML requests and responses. Table 2: Comparing Sub-flows and Modules Note: For additional information on sub-flows, refer to the Sample Application DDIceCreamStore [1]. 7

Section 3: Phrases Phrases consist of prerecorded audio files. Phrases are used to build prompts used in the call flow. Phrases are accessible only through the Dialog Designer Prompt File Editor. Phrasesets are used to group phrases related to a particular speech application. The main advantage for grouping phrases, aside from better organization, is that with phrasesets file resource efficiencies are greatly improved and this translates into quicker build times. For Example: With a phrase, there are four files per phrase (one.phrase file, one.java file, one java.class file, and one.wav file for every phrase). Hence, when there are 1000 phrases in a project, there are actually 4000 files that need to be managed and built. With a phraseset, there can be 1000 phrases in a phraseset, and so in this example, there are only 1003 files to manage (.phraseset file, one.java file, one Java.class file, and 1000 audio files). Phrasesets also support referencing audio files stored on an external server. 3.1 Call Flow Demonstrating Use of a Phraseset file Consider the following Dialog Designer Application call flow (Figure 6): Figure 6: Call flow Using a Phraseset File This example application asks a caller to speak a phrase consisting of a number between one and four. Depending on the caller s response, the application plays a phrase. For example, if the caller says one, the appropriate phrase is played and so on. These phrases are selected from the phraseset file. The phraseset file consists of phrases which can be located locally or externally. 3.2 Creating a Phraseset File Note: A phraseset file can be created either by using the Dialog Designer Phraseset editor or imported from an external location. When importing a phraseset file from an external location, skip steps 3 and 4 below. 8

The steps to create a phraseset file are listed below: Step 1 From the File menu select New -> Phraseset File (Figure 7): Figure 7: Dialog Designer menu selections to create a new Phaseset File Step 2 A Create Phraseset dialog appears (Figure 8). Select the Project, Language and give an appropriate name for the Phraseset file and click Next. 9

Figure 8: Identifying the project, language and naming the phraseset file Step 3 Browse to the appropriate directory (containing phrase audio files) using the Browse button and click Finish (Figure 9). The specified directory contains phrase files that can be combined into a phraseset file. Figure 9: Select the directory containing the recorded phrase files to be combined into a phraseset Step 4 A phraseset file is created under the phraseset directory. Double click the phraseset file to open the phraseset editor (Figure 10). The phraseset file consists of all the audio files present in the audio directory (selected in step 3) as shown in the screenshot below. The play button could be used to check/verify the phrase selected. 10

Figure 10: The phraseset editor allows you to playback and verify the individual phrases Step 5 To create a phraseset file externally, choose the External option in the phraseset file editor and specify the URL the target system containing the phraseset (Figure 11). The URL for the external phraseset file should be in the following format: http://<ip Address>:<Port>/Path, where <IP Address> and <Port> identify the target external server and Path is the location of the phrases on this server. Click Test to verify the phrase file. Figure 11: Specifying and testing external phraseset files 11

3.3 Adding a New Phrase File to a Phraseset From time to time, you may wish to expand the phrases available within an existing Phraseset. Step 1 To add a new phrase file to this phraseset, click Add New (Figure 12). Figure 12: Adding a new phrase file to an existing phraseset, using the phraseset editor Step 2 Type a phrase name in the Phrase name field of the Add New Phrase window and click OK (Figure 13). Figure 13: Identifying the new phase name 12

Step 3 A new phrase with the given name will be created. To add audio to this newly created phrase file, select the phrase and the Local Audio tab. Click Browse and browse for an audio file (Figure 14). Figure 14: Adding a new phrase file from a local directory Step 4 For an external phrase file, click Add New (Figure 15). Figure 15: Adding a new phrase file from an external source 13

Step 5 Enter the appropriate File name and click Test to verify the phrase file (Figure 16). Figure 16: Testing the new phrase file Step 6 Name the newly added phrase using Set Name (Figure 17). Figure 17: Naming the new phrase within the phraseset file Step 7 After creating the phraseset file, select the required phrase file from the phraseset in the prompt file (Figure 18). 14

Figure 18: Selecting a phraseset file to use For more information on dynamic phrases, refer to the DynamicPhraseLoading Sample Application [2]. This sample application (DynamicPhraseLoading) demonstrates loading phrase files using Dialog Designer APIs and dynamically invoking phrase (audio) files based on caller input. Section 4: Audio Variables Audio variables make use of prepackaged and prerecorded variables to play back standardized information to a caller. This includes constantly varying information like time, date, currency etc. Audio variables make it possible to use prerecorded speech, rather than Text-to-Speech, to play the above type of dynamically changing information to callers. The Dialog Designer runtime framework treats audio variables in speech applications differently than other types of variables. When the runtime framework takes the value assigned to an audio variable and parses the variable into pieces that correspond with predefined elements, these elements are then mapped to the appropriate pre-recorded (*.wav) files and played at runtime. For example, consider a variable that stores the current date. If this variable is used as an audio variable segment in a prompt, then the localization bundle parses the value from the variable and assigns one part of the variable to 15

month, another part to day, and yet another to year. The localization bundle then maps each of these parts to the appropriate prerecorded audio files. 4.1 Adding a Localization Bundle The steps below describe the process of adding a localization bundle to a Dialog Designer application: Step 1 Download the desired localization bundle from the Avaya Support website (http://avaya.com/support). The localization bundle is available with the download of Dialog Designer. In this demonstration, the French localization bundle is used. Step 2 Browse to Windows -> Preferences (not shown). Select the Dialog Designer -> Speech -> Languages tab (Figure 19). Figure 19: The Speech Languages tab of the Preferences screen. 16

Step 3 Under Audio Localization Packages, click Add (Figure 20). Browse to the location of the localization bundle.jar file previously downloaded at Step 1 and click OK. Figure 20: Use Add to browse to the location of the downloaded localization file 4.2 Installing the Localization Bundle The steps to install the localization bundle are given below: Step 1 Select the Speech Project for which the localization bundle needs to be installed. Right-click the Speech Project and select Properties (Figure 21). 17

Figure 21: Select Properties for the target Speech Project with a right-mouse-click 18

Step 2 Browse to the Dialog Designer Languages tab. Select the project language and click Add to add a language (Figure 22). Figure 22: Adding a language for a Speech Project Step 3 Select the localization language for the localization bundle (Figure 23). Figure 23: Selecting the localization language 19

Step 4 Click Install to install the standard phrases (Figure 24) and then click OK. Note: This process creates the necessary directories and automatically installs the standard phrases for that language. Figure 24: Installing the standard phrases for the specified localization 20

Step 5 Select the desired language for the localization bundle and click Install (Figure 26). Note: This step installs the java code necessary for language localization. Both the standard phrases and Java code install steps are necessary for audio variables to work in a Dialog Designer project. Figure 25: Installing the Java code for the specified localization 4.3 Demonstrating the Usage of Audio Variables Consider the following Dialog Designer Application call flow (Figure 26): Figure 26: Call flow to demonstrate use of an audio variable 21

The audio variable can either be a user defined project variable or a system variable (for example: date and time). The application consists of an announcement for playing a welcome message followed by a data node. In this application, a user defined project variable is used as an audio variable. The user defined audio variable is assigned a date in the data node and this date is announced to the caller in the Announce_audiovariable announce node. The Announce_audiovariable has a prompt file named result which makes use of the audio variable. In the result prompt file, drag and drop the Audio Variable from the palette and select its properties (Figure 27). Figure 27: Using an Audio Variable node from the palette and assigning a value using the properties tab Note: For additional information on installing and using localization bundles, refer to [3]. Section 5: Reporting Caller Hang-up Location Dialog Designer applications can be customized to report the location of caller hang-ups within a call flow. The location of caller hang-ups can be used to analyze caller experience while navigating the call flow or for troubleshooting purposes. The Java code shown in this chapter outputs the node name in a call flow where a caller hangs up or opts out (such as to talk to an agent). The code looks back at the call stack to see the servlets (nodes) that were visited and saves the node name in a variable. This variable s value can be viewed in the report generated on Avaya Voice Portal as well as printed on the console. The code snippet below demonstrates over-riding the requestbegin() method in a servlet node. The servlet node utilizes the getvariablefield() method from the SCESession class, the setvalue() method from the IVariableField interface available in the Dialog Designer runtime API, and Java API methods. 22

This servlet node is invoked by the On Disconnect handler placed in the AppRoot node. A Dialog Designer application throws a disconnect event when a caller hangs up or gets disconnected before normal call flow termination. The On Disconnect event handler specifies the next node in the call flow after a disconnect event is caught. Note: The On Disconnect event handler is placed in the AppRoot node and acts as a global event handler for such (i.e., On Disconnect) events. However, if the On Disconnect event handler is placed in another node, it can catch an On Disconnect event only if it (the event) is thrown while in that node. If the On Disconnect event handler is placed underneath a node item, it can catch the On Disconnect event only if it is thrown within that node item. 5.1 Report Location of Caller Disconnect Event Application Logic The call flow below (Figure 28) demonstrates how to report the location of a disconnect event in a Dialog Designer call flow. In order to determine the node in which a caller hangs up during the call flow process, place the code snippet (Code Sample 1) in the servlet node named OnDisconnect_processing. Place a Catch item for the On Disconnect event in the AppRoot node of the call flow (not shown) and transition the call to the OnDisconnect_processing node. Also place a report item in the exit node after the servlet node (Figure 29). The report item is used to report the variable on Voice Portal. Figure 28: Dialog Designer call flow containing the OnDisconnect_processing node for reporting the caller hang-up location Figure 29: Using a Report node from the palette 23

@Override public void requestbegin(scesession mysession) { super.requestbegin(mysession); // Make a copy o the call stack so that we can manipulate it. Stack<String> callstack = new Stack<String>(); callstack.addall(mysession.getcallstack()); try { // Pop the Stack three times. callstack.pop(); // Retrieves the this servlet node callstack.pop(); // Retrieves the Approot node. String lastform = callstack.pop(); // Retrieves the node the caller hung // up on. mysession.getvariablefield (IProjectVariables.NODE_VISITED).setValue(lastForm); IVariableField variable = mysession.getvariablefield(iprojectvariables.node_visited String value = variable.getstringvalue(); System.out.println("Caller disconnected on Node: " + value); } catch (Exception e) { if(mysession.isapptraceenabled()) { } mysession.gettraceoutput().writeln(itraceinfo.trace_level_error, "Error determining last form."); } e.printstacktrace(); } Code Sample 1: Sample code snippet to detect hang-ups Explanation of Code Sample 1: 1. Over-ride the requestbegin() method in the Java servlet which is invoked when the On Disconnect event occurs. 2. Make a copy of the call stack so that it can be manipulated using the following code: callstack.addall(mysession.getcallstack()); 24

3. Pop the contents of the call stack to retrieve the last visited node on which the hang-up occurred and store it in the project variable NODE_VISITED using the following lines of code: String lastform = callstack.pop(); mysession.getvariablefield(iprojectvariables.node_visited).setvalue(lastf orm); Note: The stack should be popped thrice because when the pop function is executed for the first time, the servlet node (current node of execution) in which the above code is written is retrieved. When the stack is popped the second time, the AppRoot node is retrieved and when the stack is popped for the third time, the node at which the caller hung-up is retrieved. 4. The last visited node can be printed directly either by using the lastform variable or by retrieving the value of the project variable NODE_VISITED using the getstringvalue() method as shown in the following code lines: IVariableField variable = mysession.getvariablefield (IProjectVariables.NODE_VISITED) String value = variable.getstringvalue(); System.out.println("Caller disconnected on Node: " + value); The node name where the caller disconnected in the call flow is stored in a variable and a report is generated on Voice Portal displaying the variable name and its value as shown in the screenshot in Figure 31 below. 5.2 Viewing Dialog Designer variables in Voice Portal Reports To view the variable values in the report on Voice Portal, execute the following steps: Step 1 Login to Voice Portal web admin portal (http://<ip address of VPMS>/VoicePortal) with valid credentials. 25

Step 2 Browse to Reports -> Application Summary as shown in the screenshot below. Select appropriate Optional Filters for viewing Application Summary Reports and for Report Type, select Summarize by Variable Name. Figure 30: Selecting the report type within Avaya Voice Portal 26

Step 3 The variable name and its value, i.e., the node name where the caller hangs up in the application is displayed (Figure 31). Figure 31: Displaying the caller hangup node name on the Avaya Voice Portal console Note: The username and password for Application Reporting must be configured on Voice Portal to view the Application Summary Report. To configure the username and password for Application Reporting, browse to System Configuration -> VPMS server -> Application Reporting (Figure 32) and set the username and password. 27

Figure 32: Configuring User Name and Password for Application Reporting within Avaya Voice Portal Section 6: References The following sample applications are located under the folder: /Sample Applications/files/DD_4.1_ SampleApplications/workspace on the Dialog Designer Release 4.1 CD. [1] DDIcreamStore [2] DynamicPhraseLoading The following document can be downloaded DevConnect sample applications, accessed by logging in to the DevConnect Portal (http://avaya.com/devconnect). [3] Tutorial for Developing a Multilingual Speech Application using Avaya Dialog Designer. Please e-mail any questions or comments pertaining to this tutorial along with the full title and Document ID (LB4276DEV), to the Avaya DevConnect Program at devconnect@avaya.com. 28

About Avaya Avaya is a global leader in enterprise communications systems. The company provides unified communications, contact centers, and related services directly and through its channel partners to leading businesses and organizations around the world. Enterprises of all sizes depend on Avaya for state-of-the-art communications that improve efficiency, collaboration, customer service and competitiveness. For more information please visit www.avaya.com. 2009 Avaya Inc. All Rights Reserved. Avaya and the Avaya Logo are trademarks of Avaya Inc. All trademarks identified by and are registered trademarks or trademarks, respectively, of Avaya Inc. All other trademarks are the property of their respective owners. The information provided in this tutorial is subject to change without notice. The configurations, technical data, and recommendations provided in this tutorial is believed to be accurate and dependable, but is presented without express or implied warranty. Users are responsible for their application of any products specified in this tutorial. 05/09 LB4276DEV avaya.com