Dialog Designer Call Flow ElementsA DevConnect Tutorial

Table of Contents

Section 1: Dialog Designer Call Flow

Elements .................................. 1

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

Section 1: Dialog Designer Call Flow Elements

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.

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.

1DEVCONNECT TUTORIAL

avaya.com

2

avaya.com

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.

3

avaya.com

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

4

avaya.com

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.

5

avaya.com

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).

6

avaya.com

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 Main call flowA 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.

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.

Sub-flows support multiple return points.

Note: Each sub-flow return node forwards the request to the next node in the (main) call flow.

Main flows only allow one Return (exit) node.

Sub-items cannot be added to a sub-flow return. 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

7

avaya.com

2.5 Sub-flow Features

When using sub-flows, you should understand the following items:

• Sub-flowsarealwayscontainedwithinthesameapplicationscopeasthemainflow.

• Sub-flowssharetheapplicationcontext,sessionobjectsatruntime,projectvariablesandresources,suchas

prompts, grammars, Database operations and Web Service operations.

• Sub-flowscanbenested,i.e.,onesub-flowcaninvokeanothersub-flow.

• Thereisnolimittothenumberofsub-flowsthatcanbeplacedinaDialogDesignerproject.

• Sub-flowcodeisgeneratedinaseparatepackage.Forexample,MySub-flow.flow will generate Java code in the

flow.sub-flow.MySub-flow package.

• Forasub-flow,theservletnames/mappingshaveadifferentformatintheweb.xmlfile.Forexample,

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 ModulesSub-flows can be used where project resources like prompts, grammars, variables are shared.

Modules are used when project resources are self contained.

Sub-flows are reusable only within a project. Modules are reusable across projects.

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.

Developers can work on individual modules (projects) in an application without impacting files in other modules or the application.

Sub-flows share the same application context at runtime. Sub-flows share session data and requests are forwarded while entering and exiting sub-flows.

Modules have separate application context at runtime. Modules do not share session data and the Avaya VoiceXML browser fetches modules as VXML<dialog>.

Sub-flows have better performance as they forward requests between servlets. Hence accessing sub-flows does not involve additional overhead.

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].

8

avaya.com

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.

9

avaya.com

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.

10

avaya.com

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 playbuttoncouldbeusedtocheck/verifythephraseselected.

11

avaya.com

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

thefollowingformat: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

12

avaya.com

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

13

avaya.com

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

14

avaya.com

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).

15

avaya.com

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

16

avaya.com

“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.

17

avaya.com

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).

18

avaya.com

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

19

avaya.com

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

20

avaya.com

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

21

avaya.com

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

22

avaya.com

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.

23

avaya.com

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

24

avaya.com

@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());

25

avaya.com

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)withvalidcredentials.

26

avaya.com

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

27

avaya.com

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.

28

avaya.com

Figure 32: Configuring User Name and Password for Application Reporting within Avaya Voice Portal

Section 6: References

Thefollowingsampleapplicationsarelocatedunderthefolder:/SampleApplications/files/DD_4.1_

SampleApplications/workspaceontheDialogDesignerRelease4.1CD.

[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.

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.

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