Cisco Unified Application Environment Application Developer Getting Started Guide
Preparing Your Development Environment
Downloads: This chapterpdf (PDF - 209.0KB) The complete bookPDF (PDF - 2.93MB) | Feedback

Preparing Your Development Environment

Table Of Contents

Preparing Your Development Environment

Identifying and Understanding Developer Network Components and Requirements

Installing the Cisco Unified Application Environment and Network Components

Installing the Cisco Unified Application Environment

Installing the Cisco Unified Communications Manager

Installing Cisco Unified IP Phones

Setting Up an Example Deployment

Required Tasks

Before You Begin

Task 1: Logging in to the Cisco Unified Application Environment Administration

Task 2: Creating a Cisco Unified Media Engine Connection

Task 3: Creating a SIP-Enabled Cisco Unified Communications Manager Cluster

Task 4: Creating a SIP Trunk in Cisco Unified Communications Manager

Create the SIP Trunk Security Profile

Create a SIP Profile

Create the SIP Trunk

Task 5: Setting Up a Route Pattern

Task 6: Defining Cisco Unified IP Phones in Cisco Unified Communications Manager

Task 7: Configuring a Phone to Connect to the Cisco Unified Communications Server

Task 8: Configuring the SIP Provider Plugin


Preparing Your Development Environment


This chapter describes when and how to use specific Cisco Unified Communications products or services for developing and testing, identifies which APIs require installation of specific products, and provides references to installation materials. It also guides you through configuring a test environment suitable to run the example applications described in Chapter 5, "Building the MakeCall Application with the Cisco Unified Application Designer," and Chapter 6, "Building Etch-Based Applications."

This chapter contains the following sections:

Identifying and Understanding Developer Network Components and Requirements

Installing the Cisco Unified Application Environment and Network Components

Setting Up an Example Deployment

Identifying and Understanding Developer Network Components and Requirements

Unlike typical development environments which usually consist of an operating system, an SDK, and dependent libraries, you also need access to network services when developing and testing Cisco Unified Communications applications. You may only need the Cisco Unified Application Designer or Etch libraries to write the actual applications; however, when you want to test your application or run it in production, you will also need properly installed and configured Cisco services.

Not every Cisco Unified Communications customer will deploy all of the Cisco Unified Communications family of products described in Chapter 1, "Getting Started," but many do. It is possible that your application may be the impetus for a customer to first purchase a Cisco Unified Application Environment or another of the Cisco Unified Communications family of products, or just as possible that the customer has already invested in the Cisco Unified Application Environment and can install your application(s) on top of that infrastructure.

Table 2-1 shows which Cisco Unified Application Environment APIs require you to install and run specific Cisco Unified Communications products.

Table 2-1 API/Product Requirements for Test Environments

API
Product

cisco.uc.cuae.legacy.CallControl

cisco.uc.cuae.legacy.MediaControl

cisco.uc.cuae.legacy.JTapi

Require both the Cisco Unified Communications Manager as the signaling backend and at least one Cisco Unified IP Phone

cisco.uc.cuae.legacy.AxlSoap

cisco.uc.cuae.legacy.ExtensionMobility

cisco.uc.cuae.legacy.CiscoDeviceList

Require the Cisco Unified Communications Manager as the signaling backend

cisco.uc.cuae.legacy.CiscoIpPhone

Requires a Cisco Unified IP Phone for testing purposes

cisco.uc.cuae.legacy.Presence

Requires Cisco Unified Presence as the signaling backend

cisco.uc.cuae.messaging

Requires Cisco Unity or Cisco Unity Connection as the signaling backend



Note Cisco Unified Communications Manager and Cisco Unified IP Phones will be present in your potential deployments. If you want to incorporate other Cisco Unified Communications Solution services, such as Cisco Unity or Cisco Unified Presence, to add interesting features to your applications, then you should consider having graceful fallback behavior in the case that one or more of these services do not exist at a particular customer site.


Installing the Cisco Unified Application Environment and Network Components

Depending on what your applications will do, certain components may be optional. This section focuses on the minimum environment needed to deploy and run the MakeCall example application described in Chapter 5, "Building the MakeCall Application with the Cisco Unified Application Designer," and Chapter 6, "Building Etch-Based Applications."

This section contains the following topics:

Installing the Cisco Unified Application Environment

Installing the Cisco Unified Communications Manager

Installing Cisco Unified IP Phones

Installing the Cisco Unified Application Environment

You can deploy either of these two versions of the Cisco Unified Application Environment in your development environment:

Free Installation Version—You can download and install a free, non-production version to use for development and testing. Installation instructions can be found at the following location: http://developer.cisco.com/web/cuae/downloads.

This version differs from the Production Installation version in these ways:

You must install all 3rd-party software manually and the versions available to you might be different than those included in the Production Installation version.

You install the Free Installation version on your own hardware.

The Free Installation Version includes a free SDK license, which provides a limited amount of licensing to allow for functional testing of your application. For more information about licensing, see the "Understanding Licensing" section on page 1-5.


Note There is no pre-build VMWare machine available for the Cisco Unified Application Environment. It is recommended that you avoid installation of the Cisco Unified Application Server and Cisco Unified Media Engine on VMWare machines because it is possible that the audio quality of the Cisco Unified Media Engine will be compromised, making it difficult to verify that your application is working correctly.


Production Installation Version—The production installation version is provided to licensed Cisco customers.

This version differs from the Free Installation version in the following ways:

The Production Installation version is installed on a special version of Microsoft Windows 2003 Server, which is preconfigured by Cisco and may differ from your development operating system.

The Production Installation version runs on Cisco MCS hardware, which is hardware tested and supported for hosting Cisco Unified Communications Manager software.

Installing the Cisco Unified Communications Manager

You can deploy either of these two versions of the Cisco Unified Communications Manager in your development environment:

Cisco Unified Communications Manager 6.0 SDK Version—Most developers will start with the SDK installation because it is cost-effective and can be quickly installed on VMWare. You can download the Cisco Unified Communications Manager 6.0 SDK from the Cisco MarketPlace: http://www.cisco.com/web/developer/cucm/content/download.html.

Production Installation Version—As with the Cisco Unified Application Environment, the production installation is what Cisco customers receive when they purchase Cisco Unified Communications Manager.

The main differences between the SDK and Production Installation versions are as follows:

The Cisco Unified Communications Manager SDK version has a small, auto-generated license that is limited to 50 Device License Units, or DLUs. You cannot increase this license, and due to this licensing limitation, certain types of stress tests are not possible with this version of the Cisco Unified Communications Manager.

The Cisco Unified Communications Manager SDK version is available for release 6.0 only; however, there are Cisco Unified Communications Manager customers using versions 3.x, 4.x, 5.x, and 7.x. Because there are significant differences between these versions, you might not be able to satisfactorily test Cisco Unified Communications Manager versions other than release 6.0.

Installing Cisco Unified IP Phones

One or more Cisco Unified IP Phones are typically required to test and develop applications. You will need Cisco Unified IP Phones to build applications that call user's phones, are called by user's phones, or monitor and control these phones to fulfill business process requirements. Cisco Unified IP Phones also support an XML-based API that allows you to control their large screen, providing an alternate avenue for an application's UI other than the desktop.

Cisco Unified IP Phones are distinguished as either hardware or software. The easiest phone to obtain is the software-based, Cisco Unified IP Communicator. However, the limitation for development is that you can only have one instance running and installed at a time. Therefore, if you want to test two phones using the Cisco Unified IP Communicator, you must install it on two machines.

In general, it is important for you to obtain and use different Cisco Unified IP Phone modes for testing. The behaviors and capabilities of varying phone models differ as they relate to Cisco Unified IP Phone Services. For example, the Cisco Unified IP 7920G and 7921G (hand-held wireless IP phones) support an internal command (Vibrate) that is unsupported on other phone models. In this case, it is possible that you could build an IP Phone Service that works very well on one phone and not others. Therefore, it is critical to have many hardware models available for testing and developing.

For development and test purposes, you must purchase Cisco Unified IP Phones or IP Communicator. For information about ordering and support, see one of the following pages on Cisco.com:

Cisco Unified IP Phones: http://cisco.com/en/US/products/hw/phones/ps379/index.html

IP Communicator: http://cisco.com/en/US/products/sw/voicesw/ps5475/index.html

Setting Up an Example Deployment

This section describes how to set up and configure an example environment with the following properties:


Note Actual IP addresses will differ in your own test environment.


One Cisco Unified Application Server and one Cisco Unified Media Engine co-located on the same physical server

SIP used for telephony integration

One Cisco Unified Communications Manager cluster

One instance of IP Communicator

Required Tasks

The required tasks for setting up the Cisco Unified Application Environment vary according to these factors:

Number of application servers and media engines

Number of Cisco Unified Communications Manager clusters

Type of telephony protocol

Types of applications used

In this example deployment, you must perform these tasks:

Task 1: Logging in to the Cisco Unified Application Environment Administration

Task 2: Creating a Cisco Unified Media Engine Connection

Task 3: Creating a SIP-Enabled Cisco Unified Communications Manager Cluster

Task 4: Creating a SIP Trunk in Cisco Unified Communications Manager

Task 5: Setting Up a Route Pattern

Task 6: Defining Cisco Unified IP Phones in Cisco Unified Communications Manager

Task 7: Configuring a Phone to Connect to the Cisco Unified Communications Server

Task 8: Configuring the SIP Provider Plugin

Before You Begin

This section assumes you have successfully installed:

Cisco Unified Application Environment 2.5

Cisco Unified Communications Manager 6.0

Two Cisco Unified IP Phones

For information about how to download and install these required components, see the "Installing the Cisco Unified Application Environment and Network Components" section.

Task 1: Logging in to the Cisco Unified Application Environment Administration

In this task, you will log in to the Cisco Unified Application Environment Administration for the first time to perform various tasks related to the environment, system, components, and logs.

To log in to the Cisco Unified Application Environment Administration, follow these steps:

Procedure


Step 1 Open the Cisco Unified Application Environment Administration URL by entering: http://<serverIPaddress>/cuaeadmin.

The Cisco Unified Application Environment Administration Login Screen opens.

Step 2 Enter the username and the password, and click Log In.


Note If this is the first time you have logged in to the Cisco Unified Application Environment Administration, you are prompted to set the Administrator and Media Engine passwords.



Task 2: Creating a Cisco Unified Media Engine Connection

In this task, you will create a media engine connection.

The example applications in this guide use media capabilities. Therefore, you must identify at least one server that has Cisco Unified Media Engine software activated and licensed on it.


Note It is necessary to assign a media engine to support media applications even if the Cisco Unified Application Server and Cisco Unified Media Engine are on the same hardware platform.


To assign a Cisco Unified Media Engine, follow these steps:

Procedure


Step 1 Choose Connections > Add Connections in the global navigation.

The Connection Wizard appears.

Step 2 Select Media Engine under Unified Application Environment Connections.

Step 3 Click Next.

The Adding Media Engine page appears.

Step 4 Enter the values as described in Table 2-2.

Table 2-2 Media Engine Fields

Field
Description/Recommendation

Media Engine Name

Name for Cisco Unified Media Engine.

IP Address

IP address of the server that hosts the Cisco Unified Media Engine.

Password/Verify Password

Password for access to the Cisco Unified Media Engine.


Step 5 Click Save.


Task 3: Creating a SIP-Enabled Cisco Unified Communications Manager Cluster

In this task, you will create a SIP-enabled Cisco Unified Communications Manager cluster that will contain at least one node corresponding to the IP address of a Cisco Unified Communications Manager server. By making this association, you dictate which Cisco Unified Communications Managers are signaled via SIP when an application makes a call.

To create a Unified Communications Manager Cluster, follow these steps:

Procedure


Step 1 Log in to Cisco Unified Application Environment Administration.

Step 2 Choose Connections > Add Connection.

The Connection Wizard appears.

Step 3 Select the Cisco Unified Communication Manager Cluster option under Unified Communication System Connections.

Step 4 Click Next.

The Add Unified Communication Manager Cluster page appears.

Step 5 Enter the cluster configuration information. Table 2-3 lists key fields and suggested settings.

Table 2-3 Cisco Unified Communications Manager Cluster Fields 

Field
Description/Recommendation

Name

Enter a unique name that will be meaningful in your environment.

Version

Choose the version of Cisco Unified Communications Manager you have installed.

Publisher Username

Username of the first node (publisher). The correct Publisher Username depends on the version of Cisco Unified Communications Manager you have installed:

If 3.x, or 4.x, enter the username and password you use to log in to the Cisco Unified Communications Manager DeviceListX.asp report page.

If 5.x, 6.x, or 7.x, enter the user name and password of a Cisco Unified Communications Application User with the Standard AXL API Access role.

Note For more information about the Cisco Unified Communications Manager DeviceListX.asp report page or Cisco Unified Communications Manager Application Users, see the documentation provided with the version of Cisco Unified Communications Manager you have installed.

Publisher Password/ Verify Password

Enter the password for the username entered into the Publisher Username field.

SNMP Community

Use the SNMP community string you have configured on the Cisco Unified Communications Cluster (accessed via Cisco Unified Serviceability).

Note The SNMP Community string is only required if you are using Cisco Unified Communications Manager 5.x, 6.x, or 7.x and you are using DeviceListX API calls. For more information about DeviceListX, see the Cisco Unified Application Environment API reference documentation.

Description

Enter any description that will be meaningful in your environment.


Step 6 Add nodes to replicate the structure of your Cisco Unified Communications cluster in the Unified Communications Manager Cluster Nodes section:

For each Cisco Unified Communications Manager node, enter a name and IP address.

For all nodes that run the Cisco CallManager service and that you want the Cisco Unified Application Environment to communicate with via SIP, select the Call Control check box. Each node for which you select the Call Control check box is automatically placed into the Default SIP Call Route Group.

Step 7 Click Save.


Task 4: Creating a SIP Trunk in Cisco Unified Communications Manager

In this task, you will create a SIP Trunk using the Cisco Unified Communications Manager administrative interface. You must also verify that the SIP trunk device name corresponds to the IP address or Domain Name System (DNS) name of the primary IP address of the Cisco Unified Application Server.

The Cisco Unified Communications Manager has no device corresponding to the Cisco Unified Application Server. Instead, the Cisco Unified Application Server appears as a specific device type based solely on the protocol used for communication between the Cisco Unified Communications Manager and the Cisco Unified Application Server. In the case of SIP, the Cisco Unified Application Server appears as a SIP trunk connection to the Cisco Unified Communications Manager.

This section describes these three subtasks:

Create the SIP Trunk Security Profile

Create a SIP Profile

Create the SIP Trunk

Create the SIP Trunk Security Profile

In this subtask, you will create a SIP Trunk Security Profile for use solely by the SIP Trunk you will later create for the Cisco Unified Application Server.

By creating this isolated SIP Trunk Security Profile, the administrator of the Cisco Unified Communications Manager can make a change to this profile safely and with confidence that the impact of the change only affects the integration between Cisco Unified Communications Manager and the Cisco Unified Application Server, in the case that the requirements of the integration change over time.

To create the SIP Trunk Security Profile that you will later select when you configure the SIP Trunk parameters, follow these steps:

Procedure


Step 1 Open the Cisco Unified Communications Manager administrative web interface.

Step 2 Choose System > Security Profile > SIP Trunk Security Profile.

Step 3 Click Add New.

The SIP Trunk Security Profile Configuration page appears.

Step 4 Enter the SIP Trunk Security Profile information. Table 2-4 lists suggested settings for key fields.


Note If you are using the Cisco Unified Communications Manager 6.0 SDK Version, you can typically select the default for fields not specified in the table below. If you are using a production environment, see your Cisco Unified Communications Manager administrator for assistance configuring devices.

For descriptions of each field, refer to the Cisco Unified Communications Manager online help, by choosing Help > This Page in the global navigation.


Table 2-4 SIP Trunk Security Profile Options

Field
Description/Recommendation

Name

Enter a name that indicates that this SIP Trunk Security Profile is for use by the Cisco Unified Application Environment SIP Trunk.

Description

Enter a description that indicates that this SIP Trunk Security Profile is for use by the Cisco Unified Application Environment SIP Trunk.

Device Security Mode

Non Secure

Incoming Transport Type

TCP+UDP

Outgoing Transport Type

TCP

Enable Digest Authentication

Do not select this check box.

X.509 Subject Name

Leave blank.

Incoming Port

5060

Enable Application Level Authorization

Do not select this check box.

Accept Presence Subscription

Do not select this check box.

Accept Out-of-Dialog Refer

Do not select this check box.

Accept Unsolicited Notification

Do not select this check box.

Accept Replaces Header

Do not select this check box.


Step 5 Click Save.


Create a SIP Profile

In this subtask, you will create a SIP Profile to use in the integration between Cisco Unified Communications Manager and the Cisco Unified Application Server.

To create a SIP Profile for use when configuring the SIP Trunk parameters, follow these steps:

Procedure


Step 1 Open the Cisco Unified Communications Manager administrative web interface.

Step 2 Choose Device > Device Settings> SIP Profile.

Step 3 Click Add New.

The SIP Profile Configuration page appears.

Step 4 Enter the SIP Profile information. Table 2-5 lists suggested settings for key fields.


Note If you are using the Cisco Unified Communications Manager 6.0 SDK Version, you can typically select the default for fields not specified in Table 2-5. If you are using a production environment, see your Cisco Unified Communications Manager administrator for assistance configuring devices.

For descriptions of each field, refer to the Cisco Unified Communications Manager online help, by choosing Help > This Page in the global navigation.


Table 2-5 SIP Profile Options

Field
Description/Recommendation

Name

Enter a name that indicates that this SIP Trunk Security Profile is for use by the Cisco Unified Application Environment SIP Trunk.

Description

Enter a description that indicates that this SIP Trunk Security Profile is for use by the Cisco Unified Application Environment SIP Trunk.

Default MTP Telephony Event Payload Type

101

Redirect By Application

Select this check box.

Disable Early Media on 180

Do not select this check box.


Step 5 Click Save.


Create the SIP Trunk

In this subtask, you will create the SIP Trunk the Cisco Unified Application Server will use as a connection to the Cisco Unified Communications Manager.

To create the SIP Trunk, follow these steps:

Procedure


Step 1 Open the Cisco Unified Communications Manager administrative web interface.

Step 2 Choose Device > Trunk.

Step 3 Click Add New.

Step 4 Select SIP Trunk as the trunk type.

The application sets SIP as the device protocol.

Step 5 Click Next.

The Trunk Configuration page appears.

Step 6 Enter the SIP trunk configuration information. Table 2-6 lists key fields and suggested settings (see note below).


Note If you are using the Cisco Unified Communications Manager 6.0 SDK Version, you can typically select the default for fields not specified in Table 2-6. If you are using a production environment, see your Cisco Unified Communications Manager administrator for assistance configuring devices.

For descriptions of each field, refer to the Cisco Unified Communications Manager online help, by choosing Help > This Page in the global navigation.


Table 2-6 SIP Trunk Fields

Field
Description/Recommendation 
Device Information

Device Name

Enter a name that indicates this trunk is used for communicating with the Cisco Unified Application Environment.

Media Termination Point Required

It is a best practice recommendation to leave this check box unselected for communication with the Cisco Unified Application Environment. However, if your application utilizes SCCP phones and requires DTMF to be audible, you should select this check box.

Retry Video Call as Audio

Select this check box.

Unattended Port

Do not select this check box.

Call Routing Information - Inbound Calls

Redirecting Diversion Header Delivery - Inbound

Select this check box.

Call Routing Information - Outbound Calls

Redirecting Diversion Header Delivery - Outbound

Select this check box.

SIP Information

Destination Address

Enter the IP address of the Cisco Unified Application Server.

SIP Trunk Security Profile

The security profile created in the "Create the SIP Trunk Security Profile" section.

SIP Profile

The SIP profile created in the "Create a SIP Profile" section.


Step 7 Click Save.


Task 5: Setting Up a Route Pattern

In this task, you will set up a route pattern in Cisco Unified Communications Manager to provide a route to the SIP trunk that you defined in Task 4: Creating a SIP Trunk in Cisco Unified Communications Manager.

A route pattern comprises a string of digits (an address) and a set of associated digit manipulations that route calls to a route list or a gateway. Route patterns provide flexibility in network design.


Note A route pattern is required if your application will use the IncomingCall event. In the example applications in this guide, calls are made from Cisco Unified Application Environment and therefore a route pattern is not required. These instructions are provided because use of IncomingCall in other applications is very common.


To set up a route pattern in Cisco Unified Communications Manager, follow these steps:

Procedure


Step 1 Open the Cisco Unified Communications Manager administrative web interface.

Step 2 Choose one of these:

Route Plan > Route Pattern (3.3).

Route Plan > Route/Hunt > Route Pattern (4.x)

Call Routing > Route/Hunt > Route Pattern (5.x, 6.x, 7.x)

Step 3 Click Add New.

The Route Pattern Configuration page appears.

Step 4 Enter the Route Pattern information. Table 2-7 lists suggested settings for key fields.


Note If you are using the Cisco Unified Communications Manager 6.0 SDK Version, you can typically select the default for fields not specified in Table 2-7. If you are using a production environment, see your Cisco Unified Communications Manager administrator for assistance configuring devices.

For descriptions of each field, refer to the Cisco Unified Communications Manager online help, by choosing Help > This Page in the global navigation.


Table 2-7 Route Pattern Options

Field
Description/Recommendation

Route Pattern

Enter the route pattern.

Description

This should indicate that the route pattern is for the Cisco Unified Application Environment and/or a specific application installed on it.

Gateway/Route List

Select the SIP Trunk created in the "Create the SIP Trunk" section.


Step 5 Click Save.

Step 6 Choose Accept in the Authorization Codes warning.


Task 6: Defining Cisco Unified IP Phones in Cisco Unified Communications Manager

In this task, you define the IP phones you will use in your network.

To define your phones, follow these steps:

Procedure


Step 1 Open the Cisco Unified Communications Manager administrative web interface.

Step 2 Choose Device > Phone.

Step 3 Click Add New.

Step 4 Select the phone type that corresponds to your phone model. For example, Cisco IP Communicator.

Step 5 Click Next.

Step 6 Select SIP or SCCP for the Device Protocol.

Step 7 Click Next.

The Phone Configuration page appears.

Step 8 Enter the Phone information. Table 2-8 lists suggested settings for key fields.


Note If you are using the Cisco Unified Communications Manager 6.0 SDK Version, you can typically select the default for fields not specified in the Table 2-8. If you are using a production environment, see your Cisco Unified Communications Manager administrator for assistance configuring devices.

For descriptions of each field, refer to the Cisco Unified Communications Manager online help, by choosing Help > This Page in the global navigation.


Table 2-8 Phone Configuration Options

Field
Description/Recommendation

Device Name

If your phone is a Cisco IP Communicator, enter the Device Name from the IP Communicator Network Preferences tab.

MAC Address

(Hardware Phones only)

Enter the Media Access Control (MAC) address that identifies Cisco Unified IP phones (hardware phones only). Make sure that the value comprises 12 hexadecimal characters.

For information on how to access the MAC address for other hardware phones, refer to the Cisco Unified IP Phone administration guide for the version of Cisco Unified Communications Manager that supports your phone model.


Step 9 Click Save.

The page refreshes and displays the Association Information section.

Step 10 Click the Line [1] - Add a New DN link.

The Directory Number Configuration page appears.

Step 11 Enter a directory number for the line.

Step 12 Make other configuration selections as necessary.

Step 13 Click Save.


Task 7: Configuring a Phone to Connect to the Cisco Unified Communications Server

In this task, you will configure the phones you will use in your network to connect to the Cisco Unified Communications Server.

To configure your phones, follow these steps:

Procedure


Step 1 Start Cisco IP Communicator.

Step 2 Select Preferences from the Menu drop-down list.

Step 3 Click the Network tab.

Step 4 Select Use these TFTP servers.

Step 5 Enter the Cisco Unified Communications Manager IP address in the TFTP Server 1 field.

Step 6 Click OK.

Step 7 The phone registers to the Cisco Unified Communications Manager.


Note If you choose the wrong MAC address or the wrong phone type when creating the phone in Task 6: Defining Cisco Unified IP Phones in Cisco Unified Communications Manager, the message "Error DB Config" appears on the phone screen.


Task 8: Configuring the SIP Provider Plugin

Tor apply configurations to a plugin, follow these steps:

Procedure


Step 1 Log in to the Cisco Unified Application Environment Administration.

Step 2 Choose Plugins > List Plugins. The List Plugins page appears.

Step 3 Select SIP Provider. The SIP Provider page appears.

Step 4 Enter the value for key fields as shown in Table 2-9.

Table 2-9 SIP Provider Plugin 

Field
Description/Recommendation

DefaultOutboundFromNumber

Default From number for outbound call.

SIPTrunkIP

SIP Trunk IP address for outbound call (should match the IP used for SIP Trunk in Communications Manager).


Step 5 Click Done.