About the Application#

The application triggers on http got request, queries the CUCM for the Ip address of the Iphone using device name. Create and send a command to be executed by the Ip phone. The command Dial:<phonenumber> i.e. "Dial:101064" when executed by the Ip phone makes a call to the Ip phone with phone number <phonenumber> i.e. 101064 mentioned in the command.

Note:The Ip phone that executes the command has to be associated with an end user in the call manager. The UserName and Password used in SendExecute are that of the end user.

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 SimpleIpPhoneExecute_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.simpleipphoneexecute_csharp or something simple like simpleipphoneexecute_csharp. The tool offers you a simple namespace based on the project name. Let's accept the tool's suggestion for now and use simpleipphoneexecute_csharp

Project namespace? [default: simpleipphoneexecute_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 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 "SimpleIpPhoneExecute_csharp"
• with namespace "simpleipphoneexecute_csharp"
• with laguage "csharp"
• with trigger event "cisco.uc.cuae.legacy.Http.GotRequest"
• in location C:\workspace\

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

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

c:/workspace> cuae create SimpleIpPhoneExecute_csharp

Project type? [application or plugin] application Programming language? [java or csharp] csharp Project namespace? [default: simpleipphoneexecute_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] 5 Generating:

• application named "SimpleIpPhoneExecute_csharp"
• with namespace "simpleipphoneexecute_csharp"
• with laguage "csharp"
• with trigger event "cisco.uc.cuae.legacy.Http.GotRequest"
• in location C:\workspace\

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

Inspecting the Generated Project#

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

• SimpleIpPhoneExecute_csharp.etch
• SimpleIpPhoneExecute_csharp.properties
• SimpleIpPhoneExecute_csharp.csproj
• cuae-resources/
• README.txt
• src/

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

• SimpleIpPhoneExecute_csharp.etch -- CUAE application Etch service definition. Edit this file to use additional CUAE services in your project.
• SimpleIpPhoneExecute_csharp.csproj -- CSharp project file
• 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 SimpleIpPhoneExecute_csharp

The name of your service.service SimpleIpPhoneExecute_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.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. It also looks up a device by the device name, which is a CiscoDeviceList service. 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 and CiscoDeviceList services, using the full namespaces. Add the following lines right after the mixin for Http but before the final "}":

  mixin cisco.uc.cuae.legacy.CiscoIpPhone

mixin cisco.uc.cuae.legacy.CiscoDeviceList}}}

The new SimpleIpPhoneExecute_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 SimpleIpPhoneExecute_csharp

The name of your service.service SimpleIpPhoneExecute_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.Http mixin cisco.uc.cuae.legacy.CiscoIpPhone mixin cisco.uc.cuae.legacy.CiscoDeviceList } }}}

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\SimpleIpPhoneExecute_csharp>msbuild

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

• MainSimpleIpPhoneExecute_csharpClient.cs
• ImplSimpleIpPhoneExecute_csharpClient.cs

Creating Configuration Items#

YAML is the file format for Unified Application Environment application configuration (config.yaml) and metadata definitions (project_name.yaml).

All application configuration items are written in the config.yaml file, which is located in the cuae-resources directory.

Configuration items follow a specific syntax, as follows.

-name:

[display name:] format: [description:] [minvalue:] [maxvalue:] [defaultvalue:] [readonly:] [required] }}}

• Items in square brackets [] are optional

The default config.yaml file contains the following information:

# CUAE Application Configuration Definition

2. You only need to edit this file if you want to expose configuration to
3. the administrator through cuaeadmin.
5. This file was auto-generated from a template but will never be
6. overwritten. You should edit this file directly if required.

configuration:

1. Indicates the name of your configuration item. It will be how you
2. reference this configuration item from code.
3. - name: myConfValue

1. Controls how the visible label of the configuration value. For
2. example, if 'name' was defined as: myConfValue, you may choose to
3. define 'displayName' as: My Config Value. Think of it as a friendly
4. name. This field is optional.
5. displayName: My Config Value

1. Defines the format of the configuration item's value. This will
2. control how cuaeadmin renders and validates the value. Possible
3. values for the 'format' field are: String, Bool, Number, IP_Address,
4. Array, HashTable, Password.
5. format: String

1. A description of the configuration item that will be displayed to
2. the administrator in cuadmin. This field is optional.
3. description: Some description here.

1. For configuration items that are formatted as numbers, the
2. 'minValue' and 'maxValue' configuration items define the acceptable
3. range of input for the item. These fields are optional.
4. minValue:
5. maxValue:

1. Defines the default value of the configuration. This field is
2. optional.
3. defaultValue:

1. Inidicates whether the configuration item is editable. If
2. 'readOnly' is set to true, the administrator will not be able to
3. edit it in cuaeadmin, but will be able to view it. The default is
4. false, and this field is optional.
5. readOnly:

1. Indicates whether the configuration item is required. If required,
2. the administrator will have to set a value before the application
3. will run. The default is false, and this field is optional.
4. required: false }}}

In this example, the application has nine configuration items. Add the following block to the config.yaml file in the configuration section:

Code Sample#

  - name: DeviceName

format: String displayName: DeviceName

- name: Priority1 format: String displayName: Priority1

- name: Priority2 format: String displayName: Priority2

- name: Priority3 format: String displayName: Priority3

- name: URL1 format: String displayName: URL1

- name: URL2 format: String displayName: URL2

- name: URL3 format: String displayName: URL3

- name: UserName format: String displayName: UserName

- name: Password format: String displayName: Password }}}

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 the SimpleIpPhoneExecute_csharp.csproj file from the SimpleIpPhoneExecute_csharp directory.

First example code snippet#

We need to handle the Http request and query the CUCM for IP address an Ip phone using the name of the phone specified in the application configuration on CUAE. We also need to create a Metreos.Types.CiscoIpPhone.CiscoIPPhoneExecuteType object using createExecute, this object contains a commands to be executed by the IP phone. These commands are set while configuring application on CUAE. Finally send the command to the IPphone using sendExecute. The user name and password of the application user needed. The IP phone that executes the command is registered to this application user in CUCM. The UserName and Password are set while configuring application on CUAE.

Code Sample#

You need to import Collection package to use Dictinary class

using System.Collections.Generic;

private Dictionary<String, ConfigEntry> conf;

public override void gotRequest(string sessionId, GotRequestOptions options) { Retrieve application partition configuration ConfigEntry[] configs = null; try { configs = server.getConfig("Default"); }catch (Exception e) { Console.WriteLine("Failed to get config entries for partition Default"); server.removeCuaeSession(sessionId); return; }

conf = new Dictionary<string, ConfigEntry>(); for (int i = 0; i < configs.Length; i++) { conf.Add(configs[i].name.ToString(), configs[i]); }

Query ConfigEntry config = null;config = conf["DeviceName"];QueryOptions qo = new QueryOptions();qo.name = config.configValue.ToString();QueryResult qr = server.query(sessionId, qo);if (qr.count == 0 || qr.resultData == null){server.sendResponse(sessionId, options.remoteHost, 200, "text/plain", "No device found!", "OK", null);server.removeCuaeSession(sessionId);return;} Find the calling device by name Device callingDevice = null; for (int i = 0; i < qr.resultData.devices.Length; i++) { Device d = qr.resultData.devices[i]; if (d.name != null && d.name == config.configValue.ToString()) { callingDevice = d; break; } } if (callingDevice == null) { string msg = "Device " + config.ToString() + " not found!"; server.sendResponse(sessionId, options.remoteHost, 200, "text/plain", msg, "OK", null); server.removeCuaeSession(sessionId); return; } Create execute config = null;config = conf["URL1"];CreateExecuteOptions ceo = new CreateExecuteOptions();ceo.url1 = config.configValue.ToString();CreateExecuteResult cer = server.createExecute(sessionId, ceo);if (!cer.returnValue.Equals("success", StringComparison.CurrentCultureIgnoreCase)){server.sendResponse(sessionId, options.remoteHost, 200, "text/plain", "createExecute failed!", "OK", null);server.removeCuaeSession(sessionId);return;} Send execute config = null; config = conf["UserName"]; SendExecuteOptions seo = new SendExecuteOptions(); seo.username = config.configValue.ToString();

config = null; config = conf["Password"]; seo.password = config.configValue.ToString(); SendExecuteResult ser = server.sendExecute(sessionId, cer.xmlObject, callingDevice.deviceIp, seo); if (!ser.returnValue.Equals("success", StringComparison.CurrentCultureIgnoreCase)) server.sendResponse(sessionId, options.remoteHost, 200, "text/plain", "SendExecute failed!", "OK", null); else server.sendResponse(sessionId, options.remoteHost, 200, "text/plain", "Done!", "OK", null);

server.removeCuaeSession(sessionId); } }}}

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

public static void Main(String[] args)

{ TODO: Change to correct URIstring uri = "tcp://localhost:9000"; RemoteSimpleIpPhoneExecute_csharpServer server = SimpleIpPhoneExecute_csharpHelper.NewServer( uri, null, new MainSimpleIpPhoneExecute_csharpClient());

Connect to the serviceserver._StartAndWaitUp( 4000 );

TODO: Insert Your Code Here Disconnect from the serviceserver._StopAndWaitDown( 4000 ); } }}}

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

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

Console.WriteLine( "CUAE application registered with key : " + key ); Console.WriteLine( "Hit any key to exit. " ); 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 and 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 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";}}}

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\SimpleIpPhoneExecute_csharp>cuae package

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

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

• SimpleIpPhoneExecute_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\SimpleIpPhoneExecute>cuae package

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

C:\workspace\SimpleIpPhoneExecute>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\SimpleIpPhoneExecute\bin\SimpleIpPhoneExecute.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\SimpleIpPhoneExecute>cuae package

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

C:\workspace\SimpleIpPhoneExecute>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\SimpleIpPhoneExecute\bin\SimpleIpPhoneExecute.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>Find/List Triggers to generate a list of applications and their associated triggers.

3. Select the application SimpleIpPhoneExecute_csharp in the list.

4. Enter "url" and "/SimpleIpPhoneExecute_csharp".

5. Click Add Parameter.

Initializing the Config Items#

1. Log in to the Administrattion interface.

2. Click Application>List Applictions to generate a list of applications.

3. Select the application SimpleIpPhoneExecute_csharp in the list.

4. Specify the DeviceName (the MAC address beginning with "SEP"), URL1 (set to "Dial:Phone#"), and the username and password (associated with the end user for the phone).

Running the Application#

1. Run the class SimpleIpPhoneExecute_csharp.MainSimpleIpPhoneExecute_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.

2. Run the program by accessing http://localhost:8000/SimpleIpPhoneExecute_csharp in a web browser.