About the Application#

The application triggers on call control incoming call, simple grammar that responds to three commands (hi, how are you, bye). When you say 'hi', the application should say: "Hey there, tex". When you say, "how are you", the application should say, "I'm dandy, how are you?". And when you say "bye", the application should say: "See ya, don't let spleeny the evil spleen get you on the way out".

Note: The CUAE server should be added as a H323 gateway to the CUCM and CUCM server should be added as a H323 gateway to the CUAE. Create a route pattern e.g 10XXXX associated with the H323 gateway (CUAE server)in CUCM. Trigger Ip Phone number should belong to the route pattern.

Requirements#

The development machine where you are creating this application should have the following installed.

1. Install Visual Studio. Version we have used is 2005.

2. Install the CUAE Developer Tools to get the etch framework and cuae-tool.

3. Add Speech Recognition Server to CUAE.

4. Add Speech Recognition License Servers to CUAE.

Creating the Application Project#

1. Open a Command Prompt window.

2. Navigate to the directory you want to use as your workspace. To use the CUAE command-line tool to create a new application, type the cuae create command and the name of the application project.

c:> cd \workspace

c:\workspace> cuae create JeevesTheVoiceRecRobot_CSharp}}}

The tool then prompts you for additional information.

Note: Once you are more familiar with the options, you can type the full command rather than answering the prompts by using the following syntax://

cuae create -l language -m namespace -t project type [options] projectname

3. First the tool prompts you to choose between building an application or a plugin. In this example, the correct choice is application:

Project Type? [application or plugin] application

4. Next the tool prompts you to specify the programming language. In this example, the correct choice is csharp:

Programming language? [java or csharp] csharp

5. The tool asks you for the namespace for the application. A program might want to use a fully qualified namespace like com.company.jeevesthevoicerecrobot or something simple like jeevesthevoicerecrobot_csharp. The tool offers you a simple namespace based on the project name. Let's accept the tool's suggestion for now and use jeevesthevoicerecrobo_csharp.

Project namespace? [default: jeevesthevoicerecrobot_csharp] <Return>

6. Finally, the tool asks if you would like to specify a triggering event. All applications need to register against at least one triggering event. You can specify the triggering event now or wait and specify the triggering event later. You can also change the triggering event during development. Again, since we know that this application needs to be triggered on an incoming call, let's go ahead and specify the triggering event now. Select option 4:

 Available application triggering event:

0: Skip this step 1: cisco.uc.cuae.legacy.JTapi.JTapiIncomingCall 2: cisco.uc.cuae.legacy.JTapi.JTapiCallInitiated 3: cisco.uc.cuae.legacy.JTapi.JTapiCallEstablished 4: cisco.uc.cuae.legacy.CallControl.IncomingCall 5: cisco.uc.cuae.legacy.Http.GotRequest 6: cisco.uc.cuae.legacy.Presence.SubscriptionTerminated 7: cisco.uc.cuae.legacy.Presence.Notify 8: cisco.uc.cuae.legacy.TimerFacility.TimerFire Triggering event? [0-8] 4}}}

The tool now has enough information to generate the project template.

   Generating:

• application named "JeevesTheVoiceRecRobot_CSharp"
• with namespace "jeevesthevoicerecrobot_csharp"
• with laguage "csharp"
• with trigger event "cisco.uc.cuae.legacy.CallControl.IncomingCall"
• in location C:\workspace\

Created project "JeevesTheVoiceRecRobot_CSharp" in directory "C:\workspace\JeevesTheVoiceRecRobot_CSharp\"}}}

Here is the whole sequence again with all of the steps together:

c:/workspace> cuae create JeevesTheVoiceRecRobot_CSharp

Project type? [application or plugin] application Programming language? [java or csharp] csharp Project namespace? [default: jeevesthevoicerecrobot_csharp] Available application triggering event: 0: Skip this step 1: cisco.uc.cuae.legacy.JTapi.JTapiIncomingCall 2: cisco.uc.cuae.legacy.JTapi.JTapiCallInitiated 3: cisco.uc.cuae.legacy.JTapi.JTapiCallEstablished 4: cisco.uc.cuae.legacy.CallControl.IncomingCall 5: cisco.uc.cuae.legacy.Http.GotRequest 6: cisco.uc.cuae.legacy.Presence.SubscriptionTerminated 7: cisco.uc.cuae.legacy.Presence.Notify 8: cisco.uc.cuae.legacy.TimerFacility.TimerFire Triggering event? [0-8] 4 Generating:

• application named "JeevesTheVoiceRecRobot_CSharp"
• with namespace "jeevesthevoicerecrobot_csharp"
• with laguage "csharp"
• with trigger event "cisco.uc.cuae.legacy.CallControl.IncomingCall"
• in location C:\workspace\

Created project "JeevesTheVoiceRecRobot_CSharp" in directory "C:\workspace\JeevesTheVoiceRecRobot_CSharp\"}}}}

Inspecting the Generated Project#

Let's inspect the files that were generated by the CUAE command-line tool. It created a JeevesTheVoiceRecRobot_CSharp directory in the directory from which you ran the cuae create command. The JeevesTheVoiceRecRobot_CSharp directory contains the following files and directories:

• JeevesTheVoiceRecRobot_CSharp.etch
• JeevesTheVoiceRecRobot_CSharp.properties
• build.xml
• cuae-resources/
• README.txt
• src/

The most important of which, for your purposes, are:

• JeevesTheVoiceRecRobot_CSharp.etch--CUAE application Etch service definition. Edit this file to use additional CUAE services in your project.
• build.xml--msbuild script file with predefined targets for managing the lifecycle of your CUAE project.
• cuae-resources/--CUAE application resource directory.
• src/--Generated application source files.

Declaring Services#

The first step in building an Etch-based application is identifying which Cisco Unified Application Environment hosted services the application requires and then editing the .etch file to declare the names of those services into the application.

Note: Once you identify the services you need, you can familiarize yourself with them by visiting the API reference for the version of the Unified Application Environment you are using.

The following snippet is the default content of the .etch file that the CUAE command-line tool generates. We use the mixin command to declare the appropriate services.

// CUAE Application Etch Service Definition

This service defines your application and the CUAE services that you use in your application.

The service module namespace, this will be translated to the namespace of the generated source code. module JeevesTheVoiceRecRobot_CSharp

The name of your service.service JeevesTheVoiceRecRobot_CSharp{ By default, you must always use the EtchBridge service. Do not remove this mixin, otherwise your application won't work.mixin cisco.uc.cuae.EtchBridge

You may add any additional service mixins that you require. For example, if you'd like to make and receive phone calls, add the following line: mixin cisco.uc.cuae.legacy.CallControl mixin cisco.uc.cuae.legacy.CallControl } }}}

Because this application will answer an incoming phone call and play a media stream back to the caller, we need to utilize the CallControl and MediaControl services. The default etch file already has a mixin for Call Control because of the triggering event you selected when creating the application project.

mixin cisco.uc.cuae.legacy.CallControl

We need to add a declaration for the MediaControl service, using the full namespace. Add the following line right after the mixin for CallControl but before the final "}":

mixin cisco.uc.cuae.legacy.MediaControl

The new JeevesTheVoiceRecRobot_CSharp.etch file should look like this:

// CUAE Application Etch Service Definition

This service defines your application and the CUAE services that you use in your application.

The service module namespace, this will be translated to the namespace of the generated source code. module JeevesTheVoiceRecRobot_CSharp

The name of your service.service JeevesTheVoiceRecRobot_CSharp{ By default, you must always use the EtchBridge service. Do not remove this mixin, otherwise your application won't work.mixin cisco.uc.cuae.EtchBridge

You may add any additional service mixins that you require. For example, if you'd like to make and receive phone calls, add the following line: mixin cisco.uc.cuae.legacy.CallControl mixin cisco.uc.cuae.legacy.CallControl mixin cisco.uc.cuae.legacy.MediaControl } }}}

Building the Application#

After declaring the services you need, you must build the application to generate source files.

1. Open a Command Prompt and navigate to the application directory.

2. Run the msbuild command to generate source files.

c:\workspace\JeevesTheVoiceRecRobot_CSharp>msbuild

The following source file templates are then created in the directory src\ jeevesthevoicerecrobo_csharp:

• MainHJeevesTheVoiceRecRobot_CSharpClient.cs
• ImplJeevesTheVoiceRecRobot_CSharpClient.cs

Writing Application Code#

This section provides instructions and code samples for writing the application logic.

Import the Project into your IDE#

1. Open Visual Studio (or another IDE of your preference).

2. Create a new CSharp project from the existing project file by selecting File -> Open -> Project/Solution and selecting theJeevesTheVoiceRecRobot_CSharp.csproj file from theJeevesTheVoiceRecRobot_CSharp directory.

First example code snippet#

In the file ImplJeevesTheVoiceRecRobot_CsharpClient.cs, we need to override our triggering method onIncomingCall. The call needs to be answered, and then we need to begin voice recognition and prompt the user to say something.

Code Sample#

You will need to include the following import statement at the beginning of the class:

using cisco.uc.cuae.legacy.types.CuaeCommon;

string callId = "";

string connId = ""; public override void incomingCall(string sessionId, IncomingCallOptions options) { AnswerCallResult acr = server.answerCall(sessionId, options.callId, "Etch", null); if (!acr.returnValue.Equals(CuaeResult.SUCCESS)) { Console.WriteLine("AnswerCall failed."); server.hangup(sessionId, options.callId, null); server.removeCuaeSession(sessionId); return; }

callId = acr.callId; connId = acr.connectionId; if (!server.beginVoiceRecognition(sessionId, connId, "static:jeeves.grxml", "Please say hi, how are you, or bye and wait for response.", false, false, null, acr).returnValue.Equals(CuaeResult.SUCCESS)) { server.play(sessionId, "The server is unable to provide voice recognition service, please try again later.", connId, null, null); server.hangup(sessionId, callId, null); server.removeCuaeSession(sessionId); } } }}}

Second example code snippet#

In the method onIncomingCall we ran voice recognition. Now we need to override the onVoiceRecognition_Complete method, so that we can respond appropriately and play a message back to the user. We also need to implement remoteHangup, startRx, and startTx.

Code Sample#

public override void onVoiceRecognitionComplete(string sessionId, VoiceRecognitionResult results, object state)

{ if (!results.returnValue.Equals(CuaeResult.SUCCESS)) { server.play(sessionId, "Voice Recognition action failed, please try again later.", connId, null, null); server.hangup(sessionId, callId, null); server.removeCuaeSession(sessionId); return; }

Console.WriteLine("Voice Recognition result, top meaning = {0}, top score = {1}", results.meaning, results.score);

switch (results.meaning) { case "hi": server.play(sessionId, "Hey there, tex!", connId, null, null); break;

case "how are you": server.play(sessionId, "I'm dandy, how are you?", connId, null, null); break;

case "bye": server.play(sessionId, "See ya, don't let spleeny the evil spleen get you on the way out.", connId, null, null); break;

default: server.play(sessionId, "Sorry, you are not saying one of the key words.", connId, null, null); break; }

server.hangup(sessionId, callId, null); server.removeCuaeSession(sessionId); }

public override void remoteHangup(string sessionId, RemoteHangupOptions options) { server.removeCuaeSession(sessionId); }

public override void startRx(string sessionId, StartRxOptions options) { }

public override void startTx(string sessionId, StartTxOptions options) { } }}}

Registering the Application#

The previous steps completed the core logic of the example applications, but before any Etch-based API calls can actually be made, we must register the application with the Cisco Unified Application Server. To register your application, follow these steps:

1. Open the MainJeevesTheVoiceRecRobot_CSharpClient file in the /src directory. It contains the following content by default:

// This file automatically generated by:

0.96.0 (ETCH-TRUNK-906) / csharp 0.96.0 (ETCH-TRUNK-906) Fri Aug 08 17:20:12 CDT 2008

using System;

using jeevesthevoicerecrobot_csharp.types.JeevesTheVoiceRecRobot_CSharp;

namespace jeevesthevoicerecrobot_csharp { /<summary>Main implementation for JeevesTheVoiceRecRobot_CSharpClient.</summary>public class MainJeevesTheVoiceRecRobot_CSharpClient : JeevesTheVoiceRecRobot_CSharpHelper.JeevesTheVoiceRecRobot_CSharpClientFactory{/<summary>Main for JeevesTheVoiceRecRobot_CSharpClient</summary> /<param name="args">Command Line Arguments</param>public static void Main(String[] args){ TODO: Change to correct URI string uri = "tcp://localhost:4001";

RemoteJeevesTheVoiceRecRobot_CSharpServer server = JeevesTheVoiceRecRobot_CSharpHelper.NewServer( uri, null, new MainJeevesTheVoiceRecRobot_CSharpClient());

Connect to the serviceserver._StartAndWaitUp( 4000 );

TODO: Insert Your Code Here

Disconnect from the serviceserver._StopAndWaitDown( 4000 ); }

/<summary>Return a new instance of JeevesTheVoiceRecRobot_CSharpClient.</summary>/<param name="server">Reference to remote service</param> /<returns>Client Implementation</returns>public JeevesTheVoiceRecRobot_CSharpClient NewJeevesTheVoiceRecRobot_CSharpClient( RemoteJeevesTheVoiceRecRobot_CSharpServer server ){return new ImplJeevesTheVoiceRecRobot_CSharpClient( server );}} } }}}

2. To make a connection to the listener, add a server.registerApplication() request.

string key = server.registerApplication("JeevesTheVoiceRecRobot_CSharp", "Default", "<username>", "<password>");

Console.WriteLine("JeevesTheVoiceRecRobot_CSharp registered with key: " +key);

Console.ReadLine(); }}}

3. Modify the String URI to match the IP address and port of the Cisco Unified Application Server.

URI settings vary slightly between 2.5(1) Beta 1 and more recent versions of 2.5(1), as follows:

2.5(1) and 2.5(1) Beta 2, Beta 3, Beta 4 & later releases#

// TODO Change to correct URI

String uri = "tls://appserver_ipaddress:9000?TlsConnection.authReqd=false&filter=KeepAlive &KeepAlive.Count=5&Packetizer.maxPktSize=102400&TcpTransport.reconnectDelay=4000";}}}

Note: In Beta 2, the Etch Bridge was updated to use Transport Layer Securityfor encryption by default. For your applications to work, you must specify TLS as the protocol in the URI and set the authReqd parameter to false. In the example above, the KeepAlive filter and Max Packet Size and Reconnect Delay parameters have also been set.

2.5(1) Beta 1#

// TODO Change to correct URI

String uri = "tcp://appserver_ipaddress:9000?&TcpConnection.reconnect_delay=4000";}}}

Note: In addition to setting the correct IP address and port for the Cisco Unfied Application Server, the Reconnect Delay parameter should be set on all connection URIs.

Adding the Grammer File#

1 When we called the action VoiceRecognition, we passed in a file called jeeves.grxml, which will allow voice recognition to interpret what the user said. We need to create this file and add it into our CSharp project. Open a notepad and save the file under subdirectory grammar of cuae-resources as jeeves.grxml

2. Copy the following text into the file.

<?xml version="1.0"?>

<grammar xml:lang="en-us" version="1.0" xmlns="http://www.w3.org/2001/06/grammar" root="JEEVES">

<meta name="maxspeechtimeout" content="4000"/> <meta name="incompletetimeout" content="2000"/>

<rule id="JEEVES" scope="public"> <one-of> <item> <ruleref uri='#utterance' /> hi <tag>SWI_meaning='hi';</tag></item> <item> <ruleref uri='#utterance' /> how are you <tag>SWI_meaning='how are you';</tag></item> <item> <ruleref uri='#utterance' /> bye <tag>SWI_meaning='bye';</tag></item> </one-of> </rule>

<rule id="utterance"> <one-of> <item repeat="0-3">uh</item> <item repeat="0-3">um</item> <item repeat="0-3">hum</item> <item repeat="0-3">eh</item> </one-of> </rule>

</grammar>}}}

Packaging The Test Application#

1. Execute a successful build request for your test application within your IDE.

2. To package the application, execute the "cuae package" command from a DOS command shell in the parent directory of the test application.

C:\workspace\JeevesTheVoiceRecRobot_CSharp>cuae package

Created package file "C:\workspace\JeevesTheVoiceRecRobot_CSharp\bin\JeevesTheVoiceRecRobot_CSharp.mca"}}}

The following files will be added to the "\bin" sub-directory:

• JeevesTheVoiceRecRobot_CSharp.mca (application bundle to be uploaded into the application server)
• INSTALLER.xml - (contains the config items in config.yaml)
• MANIFEST.xml - (bundle details for the package comamnd)

Installing The Test Application

• To install the test application on a CUAE server, execute the cuae install command from a DOS command shell in test application parent directory of the test application. The cuae install command varies slightly between 2.5(1) Beta 1 and Beta 2.

2.5(1) Beta 2#

You are prompted to enter an IP address, username, and password (to view the help, run the cuae install -h command). When prompted, enter Y or N to save management settings. This will save the answers to the above three questions in the properties file and remember them the next time you go to install.

Note: You are also prompted for the communications protocol (TCP or TLS). Select the protocol that is set on the Management Service. TLS is the default supported protocol. If you want to use TCP, follow the instructions in Management Service Transport Layer Security (TLS) to change the default URI of the Management Service before running these commands.

C:\workspace\JeevesTheVoiceRecRobot_CSharp>cuae package

Created package file "C:\workspace\JeevesTheVoiceRecRobot_CSharp\bin\JeevesTheVoiceRecRobot_CSharp.mca"

C:\workspace\JeevesTheVoiceRecRobot_CSharp>cuae install Enter the hostname or IP address of the management service (for example: localhost, 1.1.1.1): localhost Protocol: tls Generated mgmt-service uri: tls://localhost:9001?TlsConnection.authReqd=false Enter management service login username: Entermanagement service login password: Save the amanagement settings with the project? [yes or no] n Application : C:\workspace\JeevesTheVoiceRecRobot_CSharp\bin\JeevesTheVoiceRecRobot_CSharp.mca Uploading : ===========================> 100% Application has been installed successfully}}}

2.5(1) Beta 1#

You are prompted to enter an IP address, username, and password (to view the help, run the cuae install -h command). When prompted, enter Y or N to save management settings. This will save the answers to the above three questions in the properties file and remember them the next time you go to install.

C:\workspace\JeevesTheVoiceRecRobot_CSharp>cuae package

Created package file "C:\workspace\JeevesTheVoiceRecRobot_CSharp\bin\JeevesTheVoiceRecRobot_CSharp.mca"

C:\workspace\JeevesTheVoiceRecRobot_CSharp>cuae install Enter management service uri or host/IP <for example: localhost, tcp://1.1.1.1.:4001>: Enter management service login username: Entermanagement service login password: Save the amanagement settings with the project? [YyNn] n Application : C:\workspace\JeevesTheVoiceRecRobot_CSharp\bin\JeevesTheVoiceRecRobot_CSharp.mca Uploading : ===========================> 100% Application has been installed successfully}}}

Configuring the Application in the Administration Interface#

Adding a trigger#

1. Log in to the Administration interface.

2. Click Applications>Find/List Triggers to generate a list of applications and their associated triggers.

3. Select the application JeevesTheVoiceRecRobot_CSharp in the list.

4. Enter "to" and the number that will be used to trigger the application.

5. Click Add Parameter.

Add Speech Recognition Server to CUAE#

1. Login to the CUAE Admin console. Go to Connections > List Connections.

2. Select Add. Specify the type Nuance and click Next.

3. Enter the value for the Host and Port. Select Save.

Add Speech Recognition License Servers to CUAE.#

1. Login to the CUAE Admin console. Go to Connections > List Connections.

2. Select Add. Specify the type Nuance License Server and click Next.

Running the Application#

1. Run the class JeevesTheVoiceRecRobot_CSharp.MainJeevesTheVoiceRecRobot_CSharpClient to register the application.

At this point the application will remain registered and running until either you stop your application or the application loses connectivity to the Unified Application server.

Triggering the Application#

1. Call the specified trigger. A prompt "Please say hi,how are you or bye and wait for response" will be played for you.

• If you say "Hi." you will get the response "Hey there, tex".
• If you say "How are you?" you will get the response "I'm dandy, how are you?".
• If you say "Bye" you will get the response "See ya, don't let spleeny the evil spleen get you on the way out". The application will then terminate.