Download - Tutorial for Avaya Dialog Designer – Developing Telephony … · Tutorial for Avaya Dialog Designer – Developing Telephony Web Service Applications using Avaya Application Enablement

SJ; Reviewed; SPOC 1/28/2008

Solution & Interoperability Test Lab Tutorial ©2008 Avaya Inc. All Rights Reserved.

1 of 32 Telephony_ws

Tutorial for Avaya Dialog Designer – Developing Telephony Web Service Applications using Avaya Application Enablement Services




Contents

About this Tutorial..................................................................................................................3

Intended Audience....................................................................................................3

Prerequisites 3

Chapter 1: Telephony Web Service ...................................................................................4

Chapter 2: Getting Started .................................................................................................5

2.1 Network Architecture....................................................................................5

2.2 Equipment and Software..............................................................................6

2.3 Checking for Web Service Availability on AE Server ...................................7

2.4 Third Party Requirements ............................................................................7

2.5 Checking the Access to Telephony Web Service WSDL File......................8

2.6 Creating TSAPI Link in AE Server ...............................................................9

2.6.1 Configuring the Avaya Communication Manager System ...........................9

2.6.2 Configuring Phone Extensions...................................................................10

2.6.3 Creating CT User in AE Server ..................................................................11

2.6.4 Setting up the TSAPI Link on the Avaya AE Server ..................................13

2.6.5 Testing the Configuration using the ‘TSAPI Test’ Utility ............................19

Chapter 3: Telephony Web Service Dialog Designer Application....................................21

3.1 Developing the Application using Dialog Designer ....................................21

3.2 Exporting the Dialog Designer Application.................................................25

Chapter 4: Testing the Application ...................................................................................29

4.1 Adding the Phone Extensions to Devices List in AE Server .....................29

4.2 Testing the ‘makeCall’ Operation on Avaya Application Simulator............29

4.3 Exception and Error Handling ....................................................................30

4.3.1 Error (Compile time)...................................................................................30

4.3.2 Handling Exceptions ..................................................................................30

4.3.3 Using Try Catch Nodes for Exception Handling.........................................30

References ..........................................................................................................................31




About this Tutorial This tutorial explains how to use Telephony Web Service in a Speech Application created using Avaya Dialog Designer 4.1.7. Using Telephony Web Service, a Speech Application can perform basic third-party call control operations. It covers most of the features available in Telephony Web Service as well as shows developers how to test these features and describes the setup required for testing. The document is divided into following chapters:

• Chapter 1: Telephony Web Service provides information about the features of Telephony Web Service and gives an overview of the operations supported by this web service.

• Chapter 2: Getting started explains how to use the web service in Dialog Designer Application. • Chapter 3: Testing the Application explains all the set up required for testing and how to test

the features individually. • Chapter 4: Exception and Error Handling section explains how to handle some commonly

occurring errors while developing and testing the application. After completing this tutorial, the developer will be able to use Telephony Web Service in a Speech Application created using Avaya Dialog Designer. The developers will also gain knowledge on adding and using a web service in a Dialog Designer Speech Application.

Intended Audience This Tutorial is intended for application developers who want to develop Telephony Web Service Applications using Avaya Dialog Designer. It is not required to understand CSTA concepts or Avaya Communication Manager Features and concepts, but they both might be helpful. For those new to Avaya Communication Manager, a course can be taken from Avaya University (http://www.avaya.com/learning) to learn more about Communication Manager and its features. It is recommended to start with the Avaya Communication Manager Overview course (course ID: AVA00383WEN).

Prerequisites This tutorial assumes that the developer already knows how to create a simple speech application using the Avaya Dialog Designer (Eclipse IDE) and is familiar with Java language, Telephony concepts, XML and Web service.

Chapter 1: Telephony Web Service The Telephony Web Service is a feature available with Avaya MultiVantage™ Application Enablement (AE) Server 4.1. It provides a high level interface to a small subset of call control services. The Service hides the complicated concepts associated with traditional CSTA based call control such as connections, call identifiers and call states. Applications are not required to maintain any call state or information other than a session ID to manage their session on the server. This service exposes core telephone functionality and enables access to basic 3rd party call control features on Communication Manager. The main advantage of Telephony Web service is the ease of integration with enterprise applications. Refer to [3] for additional details of AE Services Overview. Table 1 provides information about the requests that this service supports.

Service Description Make Call Originates an outbound call from one party to another Single Step Conference Call Conferences in a new party to the existing active call Single Step Transfer Call Transfers the remote party on the current active call to the

specified destination Disconnect Active Call Disconnects the specified extension from the active call Answer Alerting Call

Answers an alerting call at the specified destination

Attach Allows an application to authenticate the user and explicitly establish a session before invoking a telephony request.

Release Explicitly ends the session

Table 1: Telephony Web Service Requests




Chapter 2: Getting Started This section describes the prerequisites for setting up the dialog designer application and using the telephony web service. It explains in detail about how to develop the application using dialog designer.

2.1 Network Architecture The network configuration for deploying and testing the Avaya Dialog Designer Telephony Web Services application using Avaya Voice Portal is as shown below.

Figure 1: Network configuration for testing Avaya Dialog Designer application.







2.2 Equipment and Software Table 2 shows the equipment and software version information used by this tutorial for developing the application with Avaya Dialog Designer.

Equipment Software

Avaya Dialog Designer 4.1.7

Eclipse IDE 3.2

Apache Tomcat Web Server 5.5.23

Table 2: Equipment and Software version information (Development Requirements)

Table 3 shows the equipment and software version information used by this tutorial for running the application on Avaya Voice Portal.

Equipment Software

Avaya Voice Portal Management System (VPMS) 4.1 Version 4.1.0.0.2501

Avaya Media Processing Platform (MPP) Version 4.1.0.0.2501

Apache Tomcat Web Server 5.5.23

Avaya AE Server 4.1

Table 3: Equipment and Software version information (Runtime Requirements)




2.3 Checking for Web Service Availability on AE Server For using Telephony Web service the following RPM should have been installed on the AE Server. Note: The RPM Package Manager (RPM) is a powerful command line driven package management system capable of installing, uninstalling, verifying, querying, and updating computer software packages on Linux systems. Verify that the following RPMs have been installed and configured correctly on the AE Server. • User Service RPM (mvap-userService-config-4.1.0.585-1 or later version) • Telephony Web Service RPM (mvap-telephonysvc-4.1.0.585-1 or later version) • System Management Service RPM (mvap-sms-4.1.0.585-1 or later version) • Call Control RPM for Telephony Web Service (mvap-callcontrol-4.1-327 or later version)

To verify the installation of the RPMs, use the swversion command from the command line: /opt/mvap/bin/swversion -a

From the OAM web pages: • Log in to the OAM pages • Navigate to CTI OAM Home > Help > About AE Services

This page will give the list of all MVAP RPMs that are installed on the AE Server.

2.4 Third Party Requirements In addition to above, the following third party RPMs should have been installed on the AE Server. Verify that the following third party requirements have been met and have been configured correctly (Required by Telephony Web Service). • Tomcat version 5.5.9 (tomcat-5.5.9-AV7 or later) • Axis (axis-1.4-AV7 or later)

Note: Both Tomcat and Axis require the latest J2SE JDK installed (1.5.0_02 or later).

2.5 Checking the Access to Telephony Web Service WSDL File Open a Web browser and access the URL: http://ServerName:8080/axis/services/TelephonyService?wsdl ‘ServerName’ is the AE Server name or IP Address. The WSDL is displayed as shown below.

Figure 2: Telephony Service WSDL File

Incase the above screen is not visible, • Check whether the browser proxy settings are correct. • Check whether the AE Server is accessible from the system where application is being developed,

ping the server to check this.




2.6 Creating TSAPI Link in AE Server To access the telephony web service, a TSAPI link needs to be configured on AE Server. This section describes about how to configure a TSAPI link in AE Server.

2.6.1 Configuring the Avaya Communication Manager System

1. Open a SAT terminal to the Avaya Communication Manager. Provide a username and password to login to the system.

2. Type ‘add CTI-link <link number>’ Enter an Extension number. Select the type as ‘ADJ-IP’ and

create a name for the link as shown below. Save the changes.

Figure 3: Adding CTI Link




3. Type ‘change ip-services’ and move to the ‘AE Services Administration’ page. Under the ‘AE Services Server’ column enter the machine name assigned to the AE server. Type in a system password and set the value under the ‘Enabled’ column to ‘y’ as shown below.

Figure 4: Change ip-services

2.6.2 Configuring Phone Extensions Refer to [5] for detailed description on creating and configuring the phone extension types on the Avaya Communication Manager. Refer to [6] for configuring Voice Portal extensions on the Avaya Communication Manager.




2.6.3 Creating CT User in AE Server This section describes the procedure to create a CT user assigned with an ‘Avaya Role’ of ‘userservice.useradmin’.

1. Access the AE Server login page as shown below by opening any web browser and typing: http://<IP address of AE server>:8443/MVAP/index.jsp. Login using a username and password.

Figure 5: AE Server Login Page

2. Click on ‘User Management’ as shown below.

Figure 6: CTI OAM Admin Page




3. Select UserManagement> Add User Link. Enter the mandatory fields ‘Userid', ‘Common

Name’, etc marked with a *. In ‘Avaya Role’ field select ‘userservice.useradmin’ from the drop down list. In ‘CT User’ select ‘Yes’ from the drop down list.

Figure 7: Select CT User and Avaya Role Option

4. Click on ‘Apply’ to create a new CT user.

Figure 8: Creating CT User




2.6.4 Setting up the TSAPI Link on the Avaya AE Server Perform the steps described below to configure the AE Server with respect to setting up a TSAPI link for CTI operations. The steps below assume that some components of the AE Server are already setup. Refer to [5] for a complete description of setting up AE Server.

1. Click on ‘CTI OAM Administration’ on the AE Services Home Page as shown below.

Figure 9: CTI OAM Admin Page

2. Click on ‘Switch Connections’ link under ‘Administration’ as shown below. Type in the name of

the ‘CTI-link’ created on the Avaya Communication Manager as shown in section Configuring the Avaya Communication Manager Systems - Step 2 and click the ‘Add Connection’ button.

Figure 10: Add CTI-Link




3. Type the AE Server password (described in section Configuring the Avaya Communication

Manager System Step 3) in the ‘Switch Password’ and ‘Confirm Switch Password’ fields as shown below and click the ‘Apply’ button.

Figure 11: Set Password

4. Click on the ‘Edit CLAN IPs’ button to enter the IP address of the CLAN card in the Avaya

Communication Manager system.

Figure 12: Edit CLAN IP Address




5. Click on ‘TSAPI Links’ under ‘CTI Link Admin’ and click on ‘Add Link’.

Figure 13: Add TSAPI Link

6. Select the ‘Switch Connection’ setting from the drop down box. Select the same ‘Switch

Connection’ name configured in the steps above. Select the ‘Switch CTI Link Number’ from the drop down box. This should correspond to the CTI-Link number assigned to the switch as shown in section Configuring the Avaya Communication Manager System - Step 2 . Select Unencrypted from the Security drop-down if using unencrypted Tlink. Click on the ‘Apply Changes’ button to proceed.

Figure 14: Edit TSAPI Link




7. Click on the ‘Apply’ Button to proceed and use the ‘Service Controller’ page to restart the

TSAPI server for changes to take effect.

Figure 15: Apply Changes to TSAPI Link

8. Access the ‘Switch Conn Summary’ page under ‘Status and control’ as shown below. View the

switch connection details and verify that the ‘Conn State’ is ’Talking’.

Figure 16: Switch Connection Summary




9. Click on the ‘Tlinks’ link under ‘Security Database’ and ensure that the name for the configured Tlink is seen under the ‘TLink Name’ column below. The second part of this string will contain the switch name used to configure the Tlink.

Figure 17: TLinks Page

10. Click on ‘Devices’ and ensure that the phone extensions created on the Avaya Communication Manger are listed under the ‘Device ID’ column. Use the ‘Add Device’ button to add these extensions and select the ‘Device Type’ as ‘PHONE.’

Figure 18: Devices Page




2.6.5 Testing the Configuration using the ‘TSAPI Test’ Utility This utility uses the configured TSAPI link to dial between two extensions on the AE server. The same extensions should be created on the Avaya Communication Manager.

1. Click on the ‘TSAPI Test’ link under ‘Utilities’ as shown below.

Figure 19: TSAPI Test

2. Select the appropriate TLink Name from the drop down box. Type in a username and password (ensure that this user is a CT user). In the ‘From’ and ‘To’ fields type in the extension numbers. These extension numbers should be viewable under the devices page (Step 10 in previous section). Click on the ‘Dial’ button to dial the extension.

Figure 20: Providing Inputs for TSAPI Test




3. The page shown below is seen if the ‘Dial’ event is successfully completed.

Figure 21: TSAPI Test Result




Chapter 3: Telephony Web Service Dialog Designer Application 3.1 Developing the Application using Dialog Designer This section describes how to access Telephony Web Service through a Dialog Designer Application. For additional details of developing a Dialog Designer speech application refer to [1] and [2].

1. Open a Web browser and access the following URL: http://ServerName:8080/axis/services/TelephonyService?wsdl where ServerName is the AE server name or IP Address. The WSDL is displayed as shown below.

Figure 22: Telephony Web Service WSDL




2. Create a ‘Speech’ project. Right click on the project and select New. Choose ‘Web Service Operation File’ as shown below. If ‘Web Service Operation File’ not visible as shown below, select ‘Other’ and then select ‘Web Service Operation File’ from ‘Avaya Speech Development’ option.

Figure 23: Creating WSOP File

3. Enter appropriate name in the ‘File Name’ column and enter the Telephony Web Service URL in

the ‘WSDL URL’ column as shown below. In the ‘Authentication’ drop down select ‘Basic’. In the ‘User Name’ and ‘Password’ field enter the ‘CT user name’ and ‘password’. Then click on Load Button, if the load is successful, a drop down list containing the operation supported by the web service is displayed. Select ‘makeCall(string, string)’ operation. Then click ‘Next’ button.

Figure 24: Selecting ‘makeCall’ Operation




4. Click on ‘Auto Create’ to automatically create the variables ‘originatingExtension’ and ‘destinationNumber’. Alternatively variables can also be created by dragging a simple variable in ‘flow/project.variables’ pane. Then corresponding variables can be selected from the ‘Variable Name’ drop down list. Click on ‘Next’ to proceed.

Figure 25: Mapping Input Variables

5. The next screen is for mapping output parameters. But since this web service does not return

anything, click on ‘Finish’.

Figure 26: Mapping Output Variables




6. To maintain a session, the sessionID parameter needs to be added in the SOAP Headers. To add the sessionID parameter click on ‘Add’ button, enter the name ‘sessionID’ in the Name field. Create a simple variable sessionidentifier using ‘Flow -> project variables’ palette. Select the created variable from the variable drop down list. For getting new sessionID, select ‘In’ from the drop down list of Direction column. And to reuse the existing sessionID, select ‘Out’ from the same drop down list. Save the WSOP file.

Figure 27: Adding ‘sessionID’

7. Select application flow view and drag the ‘Data node’ from the ‘Application Items’ section in the

palette as shown below. Rename the node.

Figure 28: Adding Data Node




8. Double click on the ‘Data’ node to open it. Drag the ‘Web Service’ node from the palette and select the WSOP file that was created earlier from the drop down list in properties window. Save the settings.

Figure 29: Editing ‘MakeCall’ Data Node

9. Similarly the ‘TransferCall’, ‘DisconnectCall’, ‘AnswerCall’ operations from Telephony Web

Service can be used in any Speech Application. The corresponding operation needs to be selected while creating the WSOP file.

3.2 Exporting the Dialog Designer Application 1. Right click on the project and select ‘Export’ as shown below:

Figure 30: Select Export Wizard




2. Select ‘Export Dialog Designer Speech Project’ and click ‘Next’.

Figure 31: Exporting Dialog Designer Speech Project

3. Select the destination directory where the War file needs to be saved. Click on ‘Next’.

Figure 32: Specify Destination Directory




4. Select the platform-specific details, i.e. if deploying on Voice Portal, select ‘Voice Portal’ from the

drop down list. Select the ‘Servlet container’ from the drop down list that will be used for deploying the War file. Select the Speech Recognizer. Click on ‘Next’.

Figure 33: Select Runtime Platform Settings

5. Select the options as per the screen shown below. If application needs to be rebuilt before

deploying select the ‘Rebuild applications’ check box. If Trace logs are required then deselect the ‘Tracing’ check box. Click ‘Next’ to proceed.

Figure 34: Export Dialog Designer Project




6. Check the configurations before clicking on ‘Finish’.

Figure 35: Web Application Descriptor

If the export operation is successful the ‘war’ file gets created in the destination directory specified in step 3.




Chapter 4: Testing the Application This section describes how to test the application, what setup is required to test the application. Avaya softphone has been used for testing the operation.

4.1 Adding the Phone Extensions to Devices List in AE Server To test the web service the extension used should be added to the devices list in AE Server. Refer section Setting up the TSAPI Link on the Avaya AE Server - step 10 for adding extensions to devices list.

4.2 Testing the ‘makeCall’ Operation on Avaya Application Simulator

1. To test the makeCall operation two extensions one for originating call and one for destination call are required. Ensure that the extensions are present in the devices list of AE Server.

2. Select ‘Application’ tab in the Avaya Application Simulator window as shown below. If this

window is not visible select it from ‘Eclipse Window > Show View > Avaya Application Simulator’.

Figure 36: Testing the Application

3. Click on ‘Run Application’ to run the application. If the ‘makeCall’ operation succeeds, a call

gets initiated from the original extension to destination extension. In case of errors refer to error handling section to know how to debug the errors.

4. On similar lines the remaining Telephony Web Service requests can be tested.




4.3 Exception and Error Handling This section describes how to handle the commonly occurring errors.

4.3.1 Error (Compile time) In Dialog Designer, the web service stubs are created using Axis, so if the web service has an Empty namespace, then the following error is displayed: ‘connectivity.ws.beans.Empty cannot be resolved to a type’. Fix: To remove this error, create an empty class in ‘connectivity/ws/beans’ folder.

4.3.2 Handling Exceptions The web service might throw exceptions if the operation doesn’t succeed, this exceptions can be caught using try catch node available in DD 4.1.7.

4.3.3 Using Try Catch Nodes for Exception Handling 1. Double click on the ‘MakeCall’ node in ‘Application Flow’. Drag the try and catch node and

place it as shown in the figure below.

Figure 37: Exception Handling using Try Catch Nodes

2. The error code and error message of the last generated exception get stored in ‘ddLastException’ variable.

3. Individual exceptions can be caught by adding the specific exceptions in ‘Exceptions’ column of

Catch node’s properties.

Figure 38: Adding exceptions to be handled







References While planning, developing, deploying, or troubleshooting the application, reference to other documents may be required, these references are listed below. Dialog Designer Documents

[1] Getting started with Dialog Designer Available at:

• Avaya Dialog Designer 4.1 CD-ROM (which includes the software). • Avaya Dialog Designer 4.1 as CD-ROM image downloadable from the Avaya

DevConnect web site at: http://www.avaya.com/devconnect.

[2] Avaya Dialog Designer Developer’s Guide

Viewable from within Dialog Designer. In Eclipse, click Help (menu) > Help Contents > Dialog Designer documentation.

Application Enablement Services documents

[3] Avaya MultiVantage™ Application Enablement Services Overview (02-300360)

[4] Avaya MultiVantage™ Application Enablement Services Installation Guide Software Only Offer (02-300355)

All these documents are available online on the Avaya DevConnect Web Site: http://www.avaya.com/devconnect. Communication Manager Documents Since these web services gives programmable access to Avaya Communication Manager Features, the reference documents about that system might be required. Those documents are found on the Avaya DevConnect Web Site: http://www.avaya.com/devconnect.

[5] Administrator’s Guide for Avaya Communication Manager (03-300509) Voice Portal Documents

[6] Configuring Avaya Voice Portal with Avaya Communication Manager and Designing a Sample Speech Application using Avaya Dialog Designer Issue 1.0.

©2008 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. Please e-mail any questions or comments pertaining to this tutorial along with the full title name and filename, located in the lower right corner, directly to the Avaya DevConnect Program at [email protected].




Download - Tutorial for Avaya Dialog Designer – Developing Telephony … · Tutorial for Avaya Dialog Designer – Developing Telephony Web Service Applications using Avaya Application Enablement

Top Related