Using Etch and the CUAE Command-line Tool
Etch is a network service description language, a compiler, and a set of libraries that actually implement communication between etch-capable services over the network. Etch provides a framework for building, exposing, and consuming network services in a language- and platform-neutral way.
The legacy Cisco Unified Application Server services, such as CallControl and MediaControl, are exposed as Etch services.
Developers use the CUAE command-line tool to build the etch-based application template and structure.
This chapter describes the Etch framework and the CUAE command-line tool. It also illustrates the basic steps involved in developing etch-based applications to run on the Cisco Unified Application Environment. It contains the following sections:
•Understanding Etch-Based Application Development
•Using the CUAE Command-line Tool
•Modifying Generated Files and Directories
•Using Etch Service Providers
•Registering Your Application
Note For a step-by-step tutorial including code snippets in Java and C# illustrating the concepts in this chapter, see the Chapter 6, "Building Etch-Based Applications."
Understanding Etch-Based Application Development
The following information describes the high-level workflow when building etch-based Cisco Unified Communications applications:
1. To develop etch-based applications, you first use the CUAE command-line tool to create a skeleton project appropriate for the etch-supported language you choose. For example, if you select Java, it creates a project you can build with ant or maven, which is consumable by certain IDEs, such as Eclipse.
2. In addition to selecting your language, you must name the project and optionally select from a list of preconfigured triggering events. The name is used to customize the generated file names and directory structure. The triggering event is what indicates to the Etch-based application that the Cisco Unified Application Environment has initiated a session between the plugin sending the event and your application. The CUAE command-line tool creates a stub handler function for the event you select. You can opt not to select a triggering event or to modify your selection later, but you must write code to handle a triggering event at some point in the process.
3. Once the skeleton project is generated and built, you can import it into your IDE. Depending on what you want your application to do, you must name references to the APIs you want to call and then write your application logic using methods from the APIs.
4. When your application is complete, or when you are ready to test some part of it, you create the application package using the CUAE command-line tool and then install it to the application server, either using the CUAE command-line tool or by importing it via the Cisco Unified Application Server Administration. Once it is installed, you can run and test your application.
Applications created with Etch can include many of the same components as applications created with the Cisco Unified Application Designer, such as audio files and configurable items; however, since you write your applications with the language of your choice, applications created with Etch are only required to meet the following guidelines:
•Must have an installed package definition on the application server. For more information on creating and installing the package definition, see the "cuae install" section.
•Once your application begins running, it has to register with the application server. For more information on registering your application, see the "Registering Your Application" section.
•Use the etch-based APIs from within your application.
Using the CUAE Command-line Tool
The CUAE command-line tool is a simple, yet powerful set of commands that drastically reduce the work involved in developing etch-based applications to run on the Cisco Unified Application Server. For example, you could create the build files and libraries and put them into the correct directory structure yourself, but the cuae create command does it all for you.
This section contains the following topics:
•Getting Help for Commands
•Understanding the CUAE Command-line Tool Commands
The CUAE command-line tool gives you the option of entering only the command or the command and any parameters the command accepts. If you enter the short form, you are prompted to supply any required arguments.
For example, when using the create command to create a new application, you can enter:
This causes you to be prompted for the project type, the programming language, the build format, the project namespace, and the triggering event for the MakeCall application.
Project type? [application or plugin] application
Programming language? [java or csharp] java
Build Format? [ant or maven] ant
Project namespace? [default: makecall] makecall
Available application triggering event:
Triggering event? [0-8] 5
After you are more familiar with the options, you can enter the full command. For example:
cuae create MakeCall -t app -l java -m makecall -e cisco.uc.cuae.legacy.Http.GotRequest
Getting Help for Commands
CUAE command-line tool commands are fully documented. To access documentation from the command line, including definitions of all arguments, enter the following, replacing command with the name of the command for which you want help:
Understanding the CUAE Command-line Tool Commands
The CUAE command-line tool has five commands: create, package, install, remove, and update. This section provides high-level descriptions of each command. For information about command options, use the command-line help.
The create command generates a skeleton of your application project.
cuae create -l language -m module -t string [options] projectname
It generates a top-level directory with the name of the project you supply. This directory contains the basic project directories and files. For more information about the individual files, see Modifying Generated Files and Directories.
In order for applications to run properly, you must make all application names unique, whether they are created using the Cisco Unified Application Designer or Etch and the CUAE command-line tool.
The package command creates a package definition file, projectname.mca and bundles the metadata and static resources from your project that the Cisco Unified Application Server needs to run it.
Note Your application code is not bundled in the package.
The install command provisions the package and installs application metadata to the application server. The application then enters the Enabled Stopped state. For the application to enter the Enabled Running state, you must execute the application.
Note This step can also be completed manually from the Cisco Unified Application Server Administration interface.
The remove command uninstalls the application metadata from the application server.
The application may be in any state when you execute the cuae remove command. The cuae tool will first check the state, disable it if needed, then uninstall it.
Note Uninstalling the application metadata causes all running sessions on the Cisco Unified Application Server to stop. If this is a production environment or otherwise in use, consider removing the application during a maintenance window.
The update command reinstalls the package to the application server. Use this command when you have made a change to an application's metadata, such as declaring additional services in the projectname.etch file or adding media resource files.
Tip You must run the package command after any change before updating.
Modifying Generated Files and Directories
When you create a new application, multiple files are generated for you. Many of them are code to handle messages and network communication, which you do not need to modify or even open. There is a small set of files with which you should be familiar, however, because you need to make modifications to them in order to customize the project template and to add your application logic.
The projectname.etch file contains the Cisco Unified Application Server Etch service definition. You must edit this file to declare which services you want to consume in your application. For more information about declaring services, see Using Etch Service Providers.
build.xml, pom.xml, or projectname.csproj
One of the files the create command generates is a build file appropriate to the language you selected. For example, for a Java project for which ant was selected as the build format, the build file is build.xml and you can use ant to build your project files. For C# the build file might be named projectname.csproj and you might use msbuild to build your project files.
You must run the appropriate build command (ant, maven, or msbuild) from the project directory.
Contains the following directories and files:
•project.yaml—Contains metadata about the project, such as the project name, version of the application, locales the application supports, and triggering event parameters.
•config.yaml—Contains configurable items, such as strings and numbers, that can be modified by administrators in the Cisco Unified Application Server Administration.
•media directory—Allows you to store audio files for your application to use.
•grammar directory—Allows you to store grXML grammar files for your application to use.
•web directory—A Web-accessible folder you can use to store images and other files your application needs to make HTTP-accessible.
YAML is the file format for Unified Application Environment application configuration (config.yaml), and metadata definitions (project.yaml).
Application configuration items are written in the config.yaml file, which is located in the cuae-resources directory.
All configuration items follow a specific syntax, as follows.
Note Optional items are enclosed in square brackets  in the sample above. The config.yaml file contains detailed descriptions of each element of a configuration item, including acceptable values.
When you build your project, the following application-specific files are created in the src directory.
•ImplProjectNameClient—The ImplProjectNameClient file is where you write your application logic.
•MainProjectNameClient—The MainProjectNameClient file contains helpful boilerplate code. It defines the entry point of your code.
Using Etch Service Providers
The first step in building an Etch-based application is identifying which services the application requires and updating the ProjectName.etch file to declare their corresponding namespaces. For example, if you want to use the MakeCall method, since it is contained in the cisco.uc.cuae.legacy.CallControl namespace, you must declare that namespace in the .etch file.
The following code snippet shows the default content of the .etch file related to providers:
// You may add any additional service mixins that you require. For
// example, if you'd like to make and receive phone calls, add the
// mixin cisco.uc.cuae.legacy.CallControl
To declare services you know your application will use, use the following syntax:
Note If you select a triggering event when using the cuae create command, the namespace corresponding to that event will be added automatically to your projectname.etch file.
The following namespaces can be declared:
Note To determine which services you need for your application, refer to the API reference for the version of the Cisco Unified Application Server you are using.
After you declare services in the .etch file and rebuild your project, the method calls from that namespace become available in your IDE.
Registering Your Application
Containerless applications—those created with the language of your choice using the Etch framework— do not need to be physically installed onto the application server; they can run from any machine that has network connectivity with the Cisco Unified Application Server. However, before your application can run properly, it must register itself, in effect notifying the Unified Application Environment that it is running and ready to handle triggering events and establishing the etch connection.
To ensure that your application registers when you execute it, modify the src/ProjectName/MainProjectNameClient.java or .cs file. By default, it contains the following stub content:
// TODO Change to correct URI
String uri = "tcp://localhost:4001";
You must modify the URI string to be the IP address of the Cisco Unified Application Server and the port number on which the Etch Plugin Manager is listening. By default, the port used is 9000.
Note If you are unsure of the Etch Plugin Manager port for your environment, log in to the Cisco Unified Application Environment Administration interface and choose System > Global Parameters.
RemoteMakeCallServer server = MakeCallHelper.newServer( uri, null,
new MainMakeCallClient() );
// Connect to the service
server._startAndWaitUp( 4000 );
// TODO Insert Your Code Here
Here you must add the server.registerApplication method. Include the name of your application, the partition the application should run on, and the username and password of the Cisco Unified Application Server Administration:
String key = server.registerApplication("MakeCall", "default", "administrator",
System.out.println("MakeCallApplication is registered: " + key);
Note System.in.read() puts the application in a wait state. The application remains in a running state until you stop the application or it loses connectivity to the Cisco Unified Application Server.
Setting Application Configurations
After you install your application and before you run it, you must set values for application configurations, such as trigger parameters, the call route group, and locale. In a production environment, this step is typically performed by a Cisco Unified Application Environment administrator, but in a development and test environment, you might need to set the values yourself.
For an example of setting a trigger parameter, see the "Configuring the Application in the Cisco Unified Application Environment Administration" section on page 6-14. For an example of setting a call route group, see the "Configure the Application Partition Call Route Group" section on page 5-16.
For more information about configuring applications and partitions in the Cisco Unified Application Environment Administration, see the Cisco Unified Application Environment Administration Guide.