About the Application#

This application is triggered by an inbound HTTP request to the Cisco Unified Application Environment (CUAE) server, which then places an outbound call to a configurable IP Phone directory number. Upon receiving the acknowledgment that the call has been answered, the application plays a text message. The call remains active until the destination (called party) phone hangs up.

Creating the Application Project#

1. Open a command shell

2. CUAE requires at a minimum the name of the application project, the implementation language and the module name to get started. If the language and/or the module name are omitted, the tool prompts you to provide them. Let's use the CUAAE tool to create a new application.

c:\> cd Development\CSHARP\workspace

c:\Development\CSHARP\workspace> cuae create HttpMakeCall}}}

3. First the tool asks if you are building an application or a plugin. In this case, the correct choice is application:

Project Type? [application or plugin] application

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

Programming language? [java or csharp] csharp

5. The tool prompts you for the namespace for the application. A Csharp program might use a fully qualified namespace like com.company.HttpMakeCall, or something simple like HttpMakeCall. The tool offers you a simple namespace based on the project name. Let's use cisco.uc.cuae.samples for now:

Project namespace? [default: httpmakecall] cisco.uc.cuae.samples <Return>

6. Finally the tool asks if you would like to specify a triggering event. All CUAE applications need to register against at least one triggering event. You can specify the triggering event now or wait and specify it 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 5, cisco.uc.cuae.legacy.Http.GotRequest:

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 "MakeCall"
• with namespace "MakeCall"
• with laguage "csharp"
• with trigger event "cisco.uc.cuae.legacy.CallControl.Http.GotRequest"
• in location c:\Development\CSHARP\workspace\

Created project "HttpMakeCall" in directory "c:\Development\CSHARP\workspace\HttpMakeCall\"}}}

Inspecting the Generated Project#

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

• HttpMakeCall.etch
• HttpMakeCall.properties
• cuae-resources/
• README.txt
• src/

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

• HttpMakeCall.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.

Tip: 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 HttpMakeCall

The name of your service.service HttpMakeCall{ 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 } }}}

For this application we will want to answer an incoming HTTP request, make a call and play a media stream back to the caller. This means that we will need to build an application capable of both CallControl and MediaControl.

The default etch file already has a mixin for HTTP:

 mixin cisco.uc.cuae.legacy.Http

So we need to add a mixin declaration for MediaControl and CallControl. Add the following lines right after the mixin for Http but before the final "}":

  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:\Development\CSHARP\workspace\HttpMakeCall\>msbuild

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

• MainHttpMakeCallClient.cs
• ImplHttpMakeCallClient.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 one configuration item, the content of the rendering text. Add the following block to the config.yaml file in the configuration section:

Code Sample#

configuration:
  - name: UseTTS
    format: Bool
    displayName: UseTTS
    defaultValue: True

  - name: TTSMessage
    format: String
    displayName: TTSMessage
    defaultValue: Hello, welcome to answer and play demo application

  - name: To
    format: String
    displayName: To
    defaultValue:

Writing the Application Code#

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

Importing the Project into Your IDE#

The MainHttpMakeCallClient.cs template is created as follows:

// This file automatically generated by:
//   0.96.0 (ETCH-TRUNK-906) / csharp 0.96.0 (ETCH-TRUNK-906)
//   Wed Aug 13 23:19:21 IST 2008

using System;

using cisco.uc.cuae.samples.types.HttpMakeCall;

namespace cisco.uc.cuae.samples
{
	///<summary>Main implementation for HttpMakeCallClient.</summary>
	public class MainHttpMakeCallClient : HttpMakeCallHelper.HttpMakeCallClientFactory
	{
		///<summary>Main for HttpMakeCallClient</summary>
		///<param name="args">Command Line Arguments</param>
		public static void Main(String[] args)
		{
			// TODO: Change to correct URI
			string uri = "tcp://localhost:4001";

			RemoteHttpMakeCallServer server = HttpMakeCallHelper.NewServer( uri, null, new MainHttpMakeCallClient());

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

			// TODO: Insert Your Code Here

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

		///<summary>Return a new instance of HttpMakeCallClient.</summary>
		///<param name="server">Reference to remote service</param>
		///<returns>Client Implementation</returns>
		public HttpMakeCallClient NewHttpMakeCallClient( RemoteHttpMakeCallServer server )
		{
			return new ImplHttpMakeCallClient( server );
		}
	}
}

. The ImplHttpMakeCallClient.cs template is created as follows:

// This file automatically generated by:
//   0.96.0 (ETCH-TRUNK-906) / csharp 0.96.0 (ETCH-TRUNK-906)
//   Wed Aug 13 23:19:21 IST 2008

using System;


using cisco.uc.cuae.types.EtchBridge;
using cisco.uc.cuae.legacy.types.Http;

using cisco.uc.cuae.samples.types.HttpMakeCall;

///<summary>Your custom implementation of BaseHttpMakeCallClient. Add methods here to provide
///implementation of messages from the server. </summary>
namespace cisco.uc.cuae.samples
{
	///<summary>Implementation for ImplHttpMakeCallClient</summary>
	public class ImplHttpMakeCallClient : BaseHttpMakeCallClient
	{
		/// <summary>Constructs the ImplHttpMakeCallClient.</summary>
 		/// <param name="server">a connection to the server session. Use this to
 		/// send a message to the server.</param>
		public ImplHttpMakeCallClient(RemoteHttpMakeCallServer server)
		{
			this.server = server;
		}

		/// <summary>A connection to the server session. Use this to
 		/// send a message to the server.</summary>
		private readonly RemoteHttpMakeCallServer server;

		// TODO: Implement delegates or provide implementation of HttpMakeCallClient
		// messages from the server
	}
}

. You will need to add the following declaration to ImplHttpMakeCall.cs:

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

As the application handling both CallControl and MediaControl import those packages

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

using cisco.uc.cuae.legacy.types.MediaControl;}}}

Reading Application Configurations#

To receive configurations from current application the developer can walk through the configurations array and parse the configuration item based on its type. Once the script is triggered by the incomming HTTP request, you can send a response back to the browser and then make the outbound call using the "server.sendResponse" and "server.beginMakeCall" actions as follows:

  private Boolean bUseTTS = false;
	    private String sTTSMessage = "This is a TTS message";
	    private String sTo = "100265";


        public override void gotRequest(string sessionId, GotRequestOptions options)
        {
            // Get the application's partition from server with that partition get config array
            // associated with this partition
            ConfigEntry[] configs = null;
            try
            {
                configs = server.getConfig("Default");
            }
            catch (Exception e)
            {
                Console.WriteLine(e.StackTrace);
            }

            // Capture application's configuration
            if (configs == null || configs.Length == 0)
            {
                Console.WriteLine("config is null");
                return;
            }

            try
            {
                for (int i = 0; i < configs.Length; i++)
                {
                    if (configs[i].name.Equals("UseTTS"))
                        bUseTTS = Boolean.Parse(configs[i].configValue.ToString());
                    else if (configs[i].name.Equals("TTSMessage"))
                        sTTSMessage = configs[i].configValue.ToString();
                    else if (configs[i].name.Equals("To"))
                        sTo = configs[i].configValue.ToString();
                }
            }
            catch (Exception e)
            {
                Console.WriteLine("Error reading application configs: " + e.GetBaseException());
            }

            string body = "Placing a call...";
            SendResponseResult srr = server.sendResponse(sessionId, options.remoteHost, 200,
                    "text/plain", body, "OK", null);

            if (srr.returnValue != CuaeResult.SUCCESS)
            {
                Console.WriteLine("SendResponse Failed");
                server.hangup(sessionId, "", null);
                server.removeCuaeSession(sessionId);
                return;
            }

            //Make A Call
            MakeCallResult smcr = server.beginMakeCall(sessionId, sTo, " ", "HttpMakeCall", null, null);

            if (smcr.returnValue != CuaeResult.SUCCESS)
            {
                Console.WriteLine("MakeCall Failed");
                server.hangup(sessionId, smcr.callId, null);
                server.removeCuaeSession(sessionId);
                return;
            }
        }

Note: The collected configurations are always the latest from CUAE server forregistered application's name and partition.

Tip: In the sample code above we use the "Console.WriteLine" function to print output to the console. To print the output to the application server log file, you can use the "server.logWrite" function:server.logWrite(LogLevel.VERBOSE, "DEBUG:", "beginCuaeScript Configs.length " + configs.length);

Code Samples: onMakeCallComplete, beginPlay#

When using the "beginMakeCall" action, you should follow up with the "onMakeCallComplete" function. And, the next transition is to the "beginPlay" action:

public override void onMakeCallComplete(String sessionId, MakeCallResult results, Object state)

{ Console.WriteLine("\nMakeCall completed..");

Console.WriteLine("\nBegin play.."); Play prompt in non-blocking fashion, pass in AnswerCallResult as state infoif (server.beginPlay(sessionId, sTTSMessage, results.connectionId, null, null, results.callId).returnValue != CuaeResult.SUCCESS){Console.WriteLine("beginPlay failed");server.hangup(sessionId, results.callId, null);server.removeCuaeSession(sessionId);}else{/server.sendResponse(sessionId, options.remoteHost, 200, "text/plain", "play success!", "OK", null); } } }}}

Code Sample: onPlayComplete#

When using the "beginPlay" action, you should follow-up with the "onPlayComplete" function:

public override void onPlayComplete(String sessionId, PlayResult results, Object state)

{ Console.WriteLine("\nPlay completed..");

String callId = (String)state;

Console.WriteLine("\nHangup.."); if (server.hangup(sessionId, callId, null).returnValue != CuaeResult.SUCCESS) Console.WriteLine("Hangup failed");

Console.WriteLine("\nEndScript");

server.removeCuaeSession(sessionId); } }}}

Code Samples: Call Control Events: startTx, stopTx, startRx, remoteHangup and sessionExpired#

During the design of this applications you will need to account for the following Call Control Events by adding a stub to your Impl src file:

public override void startTx(

String sessionId, StartTxOptions options) { }

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

public override void stopTx( String sessionId, StopTxOptions options) { }

public override void remoteHangup( String sessionId, RemoteHangupOptions options) { }

public override void sessionExpired(string sessionId, SessionExpiredOptions options) { server.removeCuaeSession(sessionId); } }}}

Registering the Application#

You need to change the URI as per the note below in "MainHttpMakeCallClient.cs"

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 & other 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";

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.

• In order to register application you will need to execute a "server.registerApplication()" request from within the "MainHttpMakeCallClient.cs" file.

Code Sample#

String key = server.registerApplication("HttpMakeCall", "Default", "<username>", "<password>");

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

Console.WriteLine( "Hit any key to exit." ); Console.ReadLine();

Stop the Serverserver._StopAndWaitDown(4000);}}}

Packaging the Test Application#

1. Execute a successful build request for your test application within your IDE. 2. To package the Csharp application, execute the cuae package command from a DOS command shell in test application parent directory of the test application.

C:\Development\CSHARP\workspace\HttpMakeCall>cuae package

Created package file "C:\Development\CSHARP\workspace\HttpMakeCall\bin\HttpMakeCall.mca" }}}

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

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

C:\Development\CSHARP\workspace\HttpMakeCall>dir bin

HttpMakeCall.mca INSTALLER.xml MANIFEST.xml}}}

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

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

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

Running the Application#

In the Microsoft Visual Studio IDE, please run the application by clicking the Run button.

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

Configuring the Test Application in the Administration Interface#

1. Log into the CUAE server, click on the Applications tab and select the test application HttpmakeCall from the list of applications. You will see that the config.yaml file defaults have been populated into the application configuration form. You can now use this form to update the values as necessary between executions.

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

3. Select the "HttpMakeCall" application in the list and add the URL trigger used to launch this application from a web browser.

Launching the Application from a Web Browser#

• Open a web browser and launch the application using the URL trigger you assgned to the application in the "Configuring the Test Application in the Administration Interface" section above.

• The image below represents the output for both the Web Browser request and the output to the IDE console for a successful test execution.