SimpleIpPhoneMenuTree-Java - Wiki

Wiki

« Back to SimpleIpPhoneMenu...

SimpleIpPhoneMenuTree-Java

Details

About the Application#

This application implements a simple food ordering form through a phone service.

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 SimpleIpPhoneMenuTree

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

Programming language? [java or csharp] java

5. The tool prompts you to choose the build format you prefer. In this example we are using ant.

Build format? [ant or maven2] ant

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

Project namespace? [default: simpleipphonemenutree] <Return>

7. 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 http request, let's go ahead and specify the triggering event now. Select option 5:

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

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

   Generating:
   * application named "SimpleIpPhoneMenuTree"
   * with namespace "simpleipphonemenutree"
   * with laguage "java"
   * with trigger event "cisco.uc.cuae.legacy.Http.GotRequest"
   * in location C:\workspace\
Created project "SimpleIpPhoneMenuTree" in directory
 "C:\workspace\SimpleIpPhoneMenuTree\"

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

c:/workspace> cuae create SimpleIpPhoneMenuTree
Project type? [application or plugin] application
Programming language? [java or csharp] java
Build format? [ant or maven2] ant
Project namespace? [default: simpleipphonemenutree]
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] 5
Generating:
   * application named "SimpleIpPhoneMenuTree"
   * with namespace "simpleipphonemenutree"
   * with laguage "java"
   * with trigger event "cisco.uc.cuae.legacy.Http.GotRequest"
   * in location C:\workspace\
Created project "SimpleIpPhoneMenuTree" in directory
 "C:\workspace\SimpleIpPhoneMenuTree\"

Inspecting the Generated Project#

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

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

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

SimpleIpPhoneMenuTree.etch--CUAE application Etch service definition. Edit this file to use additional CUAE services in your project.
build.xml--Ant build 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 SimpleIpPhoneMenuTree

// The name of your service.
service SimpleIpPhoneMenuTree
{
    // 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.Http

}

Because this application will answer an push objects to a phone on an http request, we need to utilize the Http and CiscoIpPhone services. The default etch file already has a mixin for Http because of the triggering event you selected when creating the application project.

mixin cisco.uc.cuae.legacy.Http

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

mixin cisco.uc.cuae.legacy.CiscoIpPhone

The new SimpleIpPhoneMenuTree.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 SimpleIpPhoneMenuTree

// The name of your service.
service SimpleIpPhoneMenuTree
{
    // 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.Http
    mixin cisco.uc.cuae.legacy.CiscoIpPhone

}

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 ant command to generate source files.

c:\workspace\SimpleIpPhoneMenuTree>ant

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

MainSimpleIpPhoneMenuTreeClient.java
ImplSimpleIpPhoneMenuTreeClient.java

Writing Application Code#

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

Import the Project into your IDE#

1. Open Eclipse (or another IDE of your preference). 2. Create a new Java project from an existing Ant buildfile by selecting File -> New -> Other -> Java Project from an existing Ant buildfile and selecting the build.xml file from the SimpleIpPhoneMenuTree directory.

3. Click Next.

4. Browse to C:\workspace\SimpleIpPhoneMenuTree\ and select the build.xml file.

5. Click Open.

6. Select "javac" task found in target "build[default]".

First example code snippet#

We need to call a specific function to service incoming gotRequest event. This is achieved by calling gotRequest() function. Inside this function, parse options.url object to access the incoming parameters and perform various actions accordingly. Idea is to format an xml object based on end user choices and pass it back to the phone that activated the service.

To Service incoming request implement the methods as shown below. Start below shown code after the lines " // TODO insert methods here to provide implementations of SimpleIpPhoneMenuTreeClient messages from the server."

Code Sample#

@Override
public void gotRequest(String sessionId, GotRequestOptions options)
{
    // check the url in order for proper switching
    //
    if (options.url.startsWith("/showMenu"))
    {
           // extract whether requested value is "Breakfast" or "Lunch"
            String queryValue = options.query.substring(options.query.indexOf("value=") + 6);

            // create menu
            CreateMenuOptions cmo = new CreateMenuOptions();
            cmo.prompt = "Please make a selection";
            cmo.title = queryValue + "Menu";

            CreateMenuResult cmr = server.createMenu(sessionId, cmo);
            AddMenuItemResult amir2 = new AddMenuItemResult();

            if (queryValue.equals("Breakfast"))
            {
                AddMenuItemOptions amio1 = new AddMenuItemOptions();
                amio1.xmlObject = cmr.xmlObject;
                amio1.name = "Pancakes";
                amio1.uRL = "http://" + options.host + "/menuSelection?metreosSessionId=" + sessionId + "&value=Pancakes";
                AddMenuItemResult amir1 = server.addMenuItemToMenu(sessionId, amio1);

                AddMenuItemOptions amio2 = new AddMenuItemOptions();
                amio2.xmlObject = amir1.xmlObject;
                amio2.name = "Eggs";
                amio2.uRL = "http://" + options.host + "/menuSelection?metreosSessionId=" + sessionId + "&value=Eggs";

                amir2 = server.addMenuItemToMenu(sessionId, amio2);
            }
            else if (queryValue.equals("Lunch"))
            {
                AddMenuItemOptions amio1 = new AddMenuItemOptions();
                amio1.xmlObject = cmr.xmlObject;
                amio1.name = "Pizza";
                amio1.uRL = "http://" + options.host + "/menuSelection?metreosSessionId=" + sessionId + "&value=Pizza";

                AddMenuItemResult amir1 = server.addMenuItemToMenu(sessionId, amio1);
                AddMenuItemOptions amio2 = new AddMenuItemOptions();
                amio2.xmlObject = amir1.xmlObject;
                amio2.name = "Burger";
                amio2.uRL = "http://" + options.host + "/menuSelection?metreosSessionId=" + sessionId + "&value=Burger";

                amir2 = server.addMenuItemToMenu(sessionId, amio2);
            }

            // http sendresponse
            server.sendResponse(sessionId, options.remoteHost, 200, "text/xml", amir2.xmlObject, "OK", null);
        }
        else if (options.url.startsWith("/menuSelection"))
        {
            // add menu item
            String queryValue = options.query.substring(options.query.indexOf("value=") + 6);

            AddMenuItemOptions amio = new AddMenuItemOptions();
            amio.name = "Thanks! Your " + queryValue.toLowerCase() + " will be ready shortly.";

            AddMenuItemResult amir = server.addMenuItemToMenu(sessionId, amio);

            // http send response
            server.sendResponse(sessionId, options.remoteHost, 200, "text/xml", amir.xmlObject, "OK", null);

            // end script
            server.removeCuaeSession(sessionId);
        }
        else
        {
            // first create text
            CreateTextOptions cto = new CreateTextOptions();
            cto.prompt = "Choose an option";
            cto.text = "Welcome to the deli";
            cto.title = "Lunch Menu";

            CreateTextResult ctr = server.createText(sessionId, cto);

            // add a soft key
            AddSoftKeyItemOptions askio1 = new AddSoftKeyItemOptions();
            askio1.name = "Breakfast";
            askio1.position = 2;
            askio1.xmlObject = ctr.xmlObject;
            askio1.uRL = "http://" + options.host + "/showMenu?metreosSessionId=" + sessionId + "&value=Breakfast";

            AddSoftKeyItemResult askir1 = server.addSoftKeyItemToText(sessionId, askio1);

            // add another soft key
            AddSoftKeyItemOptions askio2 = new AddSoftKeyItemOptions();
            askio2.name = "Lunch";
            askio2.position = 3;
            askio2.xmlObject = askir1.xmlObject;
            askio2.uRL = "http://" + options.host + "/showMenu?metreosSessionId=" + sessionId + "&value=Lunch";

            AddSoftKeyItemResult askir2 = server.addSoftKeyItemToText(sessionId, askio2);

            // Http SendResponse
            server.sendResponse(sessionId, options.remoteHost, 200, "text/xml", askir2.xmlObject, "OK", null);
      }
 }

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 MainSimpleIpPhoneMenuTreeClient file in the /src directory. It contains the following content by default:

public static void main( String[] args ) throws Exception
{
	// TODO Change to correct URI
	String uri = "tcp://localhost:9000";
		
	RemoteSimpleIpPhoneMenuTreeServer server = SimpleIpPhoneMenuTreeHelper.newServer( uri, null,
		new MainSimpleIpPhoneMenuTreeClient() );

	// Connect to the service
	server._startAndWaitUp( 4000 );

	// TODO Insert Your Code Here

	// Disconnect from the service
	server._stopAndWaitDown( 4000 );
}

2. To make a connection to the listener, add a server.registerApplication() request after the line " TODO Insert Your Code Here"

String key = server.registerApplication("SimpleIpPhoneMenuTree", "Default", "<username>", "<password>");
System.out.println("SimpleIpPhoneMenuTree registered: " + key);
System.in.read();

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 Security for 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 Keep Alive filter and MaxPacketSize and Reconnect Delayparameters 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.

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\SimpleIpPhoneMenuTree>cuae package
Created package file
"C:\workspace\SimpleIpPhoneMenuTree\bin\SimpleIpPhoneMenuTree.mca"

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

SimpleIpPhoneMenuTree.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#

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

Tip: 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\SimpleIpPhoneMenuTree>cuae package Created package file "C:\Development\CSHARP\workspace\SimpleIpPhoneMenuTree_JAVA\bin\SimpleIpPhoneMenuTree.mca"

C:\workspace\SimpleIpPhoneMenuTree>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] no
Application : C:\workspace\SimpleIpPhoneMenuTree\bin\SimpleIpPhoneMenuTree.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\SimpleIpPhoneMenuTree>cuae package
Created package file
"C:\Development\CSHARP\workspace\SimpleIpPhoneMenuTree_JAVA\bin\SimpleIpPhoneMenuTree.mca"

C:\workspace\SimpleIpPhoneMenuTree>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\SimpleIpPhoneMenuTree\bin\SimpleIpPhoneMenuTree.mca
Uploading :  ===========================> 100%
Application ahas been installed successfully

Configuring the Application in the Administration Interface#

Adding a trigger#

1. Log in to the Administration interface.

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

3. Select the application SimpleIpPhoneMenuTree in the list.

4. Enter "url" and "/lunchOrder".

5. Click Add Parameter.

Running the Application#

Adding the Phone Service#

1. We want to add this application as a phone service. To do this, first login to the call manager of your phone. Go to Device> Device Settings> Phone Services. Click Find and then Add New. Set both the Service Name and ASCII Service Name to "Lunch Order". Set the service URL to

http://<cuae-server-ip>:8000/lunchOrder

. Save the changes.

2. To add the service to your particular IP Phone, lookup your phone under Device>Phone. Under the Related Links drop-down list at the top, select Subscribe/Unsubscribe Services and Go. Select Lunch Order from the drop-down and select Next and then Subscribe. You will have to reset your phone now for the changes to take effect.

Registering the Application#

1. Run the class SimpleIpPhoneMenuTree.MainSimpleIpPhoneMenuTreeClient 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.

Executing the Application#

Now that the service has been applied to the phone, you can access the lunch menu by pressing the Services key on your phone. Select the Lunch Order softkey and the menu should load.

0 Attachments

1245 Views

Average (0 Votes)

Comments

Developer Network

SimpleIpPhoneMenuTree-Java - Wiki

CUAE Wiki

Wiki

SimpleIpPhoneMenuTree-Java

About the Application#

Creating the Application Project#

Inspecting the Generated Project#

Declaring Services#

Building the Application#

Writing Application Code#

Import the Project into your IDE#

First example code snippet#

Code Sample#

Registering the Application#

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

2.5(1) Beta 1#

Packaging The Test Application#

2.5(1) Beta 2#

2.5(1) Beta 1 #

Configuring the Application in the Administration Interface#

Adding a trigger#

Running the Application#

Adding the Phone Service#

Registering the Application#

Executing the Application#

Log In

Developer Network

SimpleIpPhoneMenuTree-Java - Wiki

SimpleIpPhoneMenuTree-Java

About the Application#

Creating the Application Project#

Inspecting the Generated Project#

Declaring Services#

Building the Application#

Writing Application Code#

Import the Project into your IDE#

First example code snippet#

Code Sample#

Registering the Application#

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

2.5(1) Beta 1#

Packaging The Test Application#

2.5(1) Beta 2#

2.5(1) Beta 1 #

Configuring the Application in the Administration Interface#

Adding a trigger#

Running the Application#

Adding the Phone Service#

Registering the Application#

Executing the Application#