Cisco Unified Application Environment Application Developer Getting Started Guide
Using the Cisco Unified Application Designer
Downloads: This chapterpdf (PDF - 281.0KB) The complete bookPDF (PDF - 2.93MB) | Feedback

Using the Cisco Unified Application Designer

Table Of Contents

Using the Cisco Unified Application Designer

Understanding the Cisco Unified Application Designer

Workflow

Application Components

User Interface

Using the Cisco Unified Application Designer

Creating a Project

Creating a New Script

Adding Existing Scripts to a Project

Navigating Between Scripts

Manipulating Elements on the Function Canvas

Adding New Actions

Adding an Action to the Toolbox

Deleting Canvas Elements

Setting the Execution Path

Creating a Branch Condition

Using Elements That Create Handlers

Defining Properties

Creating Variables

Creating a Local Variable

Creating a Global Variable

Using the Initialize With Property

Building an Application

Deploying an Application

Setting Application Configurations

Configuring Connection to Cisco Unified Application Server


Using the Cisco Unified Application Designer


The Cisco Unified Application Designer is a visual Integrated Development Environment (IDE) you can use to create, build, deploy, and debug applications to run on the Cisco Unified Application Environment. It minimizes the need to write code during application development by allowing you to build script functions with graphical representations of predefined telephony API actions.

This chapter describes the Cisco Unified Application Designer interface and architecture and provides instructions for common tasks. It contains the following sections:

Understanding the Cisco Unified Application Designer

Using the Cisco Unified Application Designer


Note For a step-by-step tutorial that illustrates the concepts described in this chapter, see the Chapter 5, "Building the MakeCall Application with the Cisco Unified Application Designer."


Understanding the Cisco Unified Application Designer

This section describes the basic workflow, application components, and user interface of the Cisco Unified Application Designer.

This section describes these topics:

Workflow

Application Components

User Interface

Workflow

The following information describes the high-level Cisco Unified Application Designer workflow:

1. Cisco Unified Application Designer prompts you to name the project and create the first script. The script is the most important grouping in your project; it contains all functions and variables.

2. When you create the script, you select a triggering event, which causes the designer to create a function to handle the event. This function is initially represented by an empty canvas in the user interface that you must populated with actions (which are prebuilt blocks of code in the Cisco Unified Application Designer interface), variables, and application logic.

3. As you define additional functions, new blank canvases are created for you to populate. Asynchronous functions require a handler function for each event that might be launched by the function. Stub handler functions for each such event are automatically created for you at the time you drop such an action onto the canvas. For example, when you select the MakeCall action, handler functions are created for MakeCall_Complete and MakeCall_Failed.

4. You add additional scripts as needed to complete your application.

5. When the application is complete, or when you are ready to test some part of it, the Build command compiles the application, displays any error messages, and creates the application package.

6. If the application is complete and the compiler writes no error messages, you can both build and deploy the application using the Deploy command.

Application Components

Cisco Unified Application Designer applications consist of the following primary components:

Script(s)—Contains all functions and variables. An application must contain at least one script.

Installer—Allows you to declare items which you want the application administrator to be able to configure, such as strings and numbers

Databases—Supports coordination between multiple scripts or script instances by providing a MySQL database that scripts can read and write to.

Localized String Table—Allows you to define and store localizable strings to use in your application.

Web Folder—A Web-accessible folder you can use to store images and other static content your application needs in an HTTP-accessible location.

Voice Recognition Resources—Allows you to store grXML grammar files.

Media Resources— Allows you to associate static audio files with your application, which will be bundled and deployed to Cisco Unified Media Engines automatically.

User Interface

The Cisco Unified Application Designer interface has five main sections:

Figure 3-1 Cisco Unified Application Designer Main Interface

1. Explorer Window

The Explorer Window displays all of the application components so you can navigate between them. For more information about the components you can navigate to from the Explorer Window, see "Application Components" section.

2. Canvas

Two types of canvases appear in the canvas frame, depending on what you select:

Global Canvas—Appears in the canvas frame when you select the script tab from the top of the canvas or the script item in the Explorer Window. It displays all script events, functions, and global variables. From this canvas, you can add new global variables and manage event-level and project-level parameters.

Function Canvas—Appears in the canvas frame when you select a function or event tab from the top of the canvas or in the Explorer Window. You populate a Function Canvas with actions and events from the Toolbox. The Function Canvas contains the Variables Tray, which you can use to view and create local variables.


Note As you add actions to a function, the screen may not be large enough to simultaneously display all the nodes the function contains. In this case, the canvas automatically expands to accommodate additional elements displaying horizontal and vertical scroll bars that can be used to navigate the canvas.


Variables Tray—Within a function, local variables store data for actions and events to access. Local variables are specific to a function; for actions inside more than one function to access the same data, you must create a global variable. By default, the Variables Tray is not visible. To view the Variables Tray, right click on any blank area of the Function Canvas and select Variables Tray.

3. Toolbox

Actions and other application elements—such as variables, comments, and events—reside in the Toolbox, which is divided into categories. You can view the list of actions for a specific category by clicking on the tab with that category label. Drag actions from the Toolbox to the Function Canvas to add them to your script and configure their parameters.

The following Toolbox categories appear out-of-the-box. Third-party actions can be added to the Toolbox by developing new providers or native actions and adding them to the project.

Cisco IP Phone

Call Control

Media Control

HTTP

Cisco DeviceListX

Mail

DialPlan

Database

Application Components

4. Properties Grid

Most Cisco Unified Application Designer elements have configurable properties. You can view and modify the properties in the Properties Grid, which displays the properties of the element that is currently selected on the canvas.

Depending on the type of element selected, different types of properties appear in the Properties Grid. For example, typically actions have three types of properties: Action Parameters, Logging properties, and Result Data properties.

In the Properties Grid, properties are grouped by category or alphabetically. To switch between these two options, click the grouping button or the alphabetical button.

Some properties allow you to choose from a specific set of values. In these cases the values are displayed in a drop-down menu. Some properties allow different types of values, such as a literal string, variable, or a C# code snippet.

5. Output Window

When you compile an application, the compiler generates informational, warning, and error messages that are displayed in the Output Window interface.

Using the Cisco Unified Application Designer

This section contains detailed procedures for frequently performed Cisco Unified Application Designer tasks.

The following topics are provided:

Creating a Project

Creating a New Script

Adding Existing Scripts to a Project

Navigating Between Scripts

Manipulating Elements on the Function Canvas

Creating Variables

Building an Application

Deploying an Application

Creating a Project

The project is the container for all scripts in an application. In fact, a project is also sometimes referred to as an application. Therefore, before you can create a new application, you must first create a new project.


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


To create a new project, follow these steps:

Procedure


Step 1 Choose File > New Project to create a new project.

The New Application Designer Project window appears.

Step 2 Enter a unique project name in the Project Name field.

Step 3 Browse to the location you want to use to store the project files. If necessary, you can move the project to a new location at a later time by relocating this folder

Step 4 Click OK.

The New Application Designer Project window closes and the New Application Script window appears containing a list of preconfigured triggering events for you to choose from.

In most cases, you create your first script at the same time that you create the project. You can click Cancel in the New Application Script Project window if you want to create your first script at another time.

Step 5 Name your script and associate the script with a triggering event.

The triggering event causes a new script instance to begin executing. A script can have only one triggering event. For more information about an event, see the API reference for the version of Cisco Unified Application Designer you are using.

Step 6 Enter a script name.

Step 7 Select an event from the list of triggering events.

Step 8 Click OK.

The New Application Script window closes and your script's Global Canvas appears.

The interface is updated with a new tab representing the script and a new tab that represents the triggering event handling function.


Creating a New Script

Every project must contain at least one script.

To create a new script, follow these steps:

Procedure


Step 1 Choose Project > Add Script > New Script.

A New Application Script window appears.

Step 2 Enter a name in the text field and select a triggering event from the Select Triggering Event list.


Note Scripts require a unique name, and must be triggered by an external event.


Step 3 Click OK to continue.

The Cisco Unified Application Designer creates the new script using the name provided. A new tab representing the script and a new tab that represents the triggering event handling function are added to the user interface.


Adding Existing Scripts to a Project

You can copy existing scripts into your project from other projects.

To add an existing script to your project, follow these steps:

Procedure


Step 1 Choose Project > Add Script > Existing Script.

The Add Existing Applications Script window appears.

Step 2 Browse to the project folder that contains the script you want to add.

Step 3 Select the script .app file.

Step 4 Click Open.

The Cisco Unified Application Designer copies the existing script. A new tab representing the script appears.


Navigating Between Scripts

When navigating from one script to another, the system prompts you to save the current script if you have made changes. You cannot have unsaved changes in multiple scripts simultaneously.

Manipulating Elements on the Function Canvas

Every function execution begins with the start node, represented by the green Start icon. To create your application, you must add actions, variables, and application components.

Adding New Actions

To add a new action node to the function canvas, follow these steps:

Procedure


Step 1 Expand a category in the Toolbox by clicking the category name.

Step 2 Drag and drop an action from the Toolbox to the Function Canvas. Figure 3-2 shows an example of the Toolbox with the expanded Media Control category.

Figure 3-2 Toolbox With Expanded Media Control Category


Adding an Action to the Toolbox

If you want to add certain actions that do not appear in the Toolbox by default or new, custom actions that you create, follow these steps:

Procedure


Step 1 Right-click inside the Toolbox and select Add/Remove Items.

Step 2 The Customize Toolbox window appears.

Step 3 Select the check boxes corresponding to the actions you want to add, or click Browse to locate an action on your network to select it.

Step 4 Click OK.


Deleting Canvas Elements

To delete an arrow, a node, or any other element on the application canvas, follow these steps:

Procedure


Step 1 Click once on the title or border of the element.

Step 2 Press the Delete key.

The item is immediately deleted.


TipYou can also right click an element and select Delete.

To delete a group of elements, select the entire group by clicking and dragging a box around a set of elements.


Setting the Execution Path

The first time you add an action to a canvas, the start node is automatically connected to the new action node with an arrow, thus creating the initial execution path.


Tip When adding subsequent actions, you must connect them manually.


The execution path indicates the order of action execution in the function. Figure 3-3 shows the execution path between the Start node and the Play action.

Figure 3-3 Execution Path From Start Node To Play Action

To connect two actions, follow these steps:

Procedure


Step 1 Hover your mouse over the action icon to cause the icon to display the gray Link port.

Step 2 Click the Link port and drag the cursor to the node to which you want to connect.

The arrow points to the second node, indicating the program flows from the first node to the second node.


Creating a Branch Condition

Every action returns a high-level outcome (Success, Failure, or Timeout). By default, the execution path has no branches; no matter the outcome of the previous action, the path continues to the next action. You can create a branch condition to create more than one possible execution path based on the outcome of the previous action.

To create a branch condition, follow these steps:

Procedure


Step 1 Add the action to the canvas that you want to cause the execution path to branch.

Step 2 Create different paths away from the action by connecting it to the two (or more) actions that you want to follow it.

The execution path between the initial action and each successive action is labeled Default when you first draw the link.

Step 3 Click the word default on one of the execution paths to convert it to a drop-down box. Figure 3-4 shows an example of the Condition drop-down box.

Step 4 Select an outcome.

Step 5 Repeat for all other branches.

Figure 3-4 MakeCall Action With A Branched Execution Path


Using Elements That Create Handlers

Asynchronous actions require a handler function for each of the asynchronous events that might be launched by the action. For example, the MakeCall action has the event handler functions MakeCall_Complete and MakeCall_Failed.

At the time you drop such an action onto the Function Canvas, the Cisco Unified Application Designer automatically does the following:

Displays a list of the asynchronous events in italics below the action icon on the Function canvas

Creates stub handler functions for each asynchronous event and displays a corresponding tab above the Function Canvas for each


Tip To complete your application, you must complete these functions to resolve the outcomes of the events.


Defining Properties

Most Cisco Unified Application Designer elements have configurable properties. You can view and modify the properties in the Properties Grid, which displays the properties of the element that is currently selected on the Function Canvas.

Figure 3-5 shows the Properties Grid for the SendResponse action.

Figure 3-5 Selected Action (SendResponse) Displays Properties Grid

To edit properties, follow these steps:

Procedure


Step 1 On the Function Canvas, select an element to display its properties.

The element's properties display in the Properties Grid. Depending on the type of element selected, different types of properties appear in the Properties Grid, such as: Action Parameters, Logging, and Result Data properties.

Step 2 In the Properties grid, locate the property you want to modify.

Step 3 Change the value. Some properties allow only a range of values. In these cases the values are displayed in a drop-down menu. Other properties allow you to enter text into the field. Some properties allow different types of values, such as a literal string, variable, or a C# code snippet.


Tip If the parameter type has been set to C# or Literal, the Cisco Unified Application Designer displays a square containing an ellipsis (...) to the right of the element that allows you to access an editor window for modifying parameters with lengthy values.



Creating Variables

The Cisco Unified Application Designer supports local variables and global variables. Local variables are available only within the function in which they are defined. Global variables are available to all functions within a script.

Creating a Local Variable

To create a local variable, follow these steps:


Step 1 Right-click the Function Canvas and select Variables Tray.

The Variables Tray appears at the bottom of the canvas.

Step 2 Right-click inside the Variables Tray and select Add New Item.

An unnamed variable appears in rename mode.

Step 3 Enter a name for the variable and press ENTER to save the name.

The properties for the new variable appear in the Basic Properties section.

Step 4 Configure the variable properties as necessary.


Creating a Global Variable

To create a global variable, follow these steps:


Step 1 Click the script tab to view the Global Canvas.

Step 2 Right-click the Variables folder and select Add New Item.

An unnamed variable appears in rename mode.

Step 3 Enter a name for the variable and press ENTER to save the name.

The properties for the new variable appear in the Basic Properties section.

Step 4 Configure the variable properties as necessary.


Using the Initialize With Property

The Initialize With property is located under the Basic Properties section. The Initialize With property provides a drop-down list that contains a combination of all the installer configuration values and all the localized strings defined for this project. You can use the Initial With property as follows:

To initialize a variable with the value of an installer configuration or localized string when the script starts, choose the appropriate selection from the drop-down list.

To initialize a local or global variable to be initialized with the value of an event parameter when the function starts, select that event parameter from the Initialize With drop-down list. The drop-down list contains all of the event parameters for the event the function represents.

In some cases, an event will not pass in a value for the selected parameter. Therefore, when creating a variable, you should define the variable's DefaultValue property value. If the event parameter does not exist in the event, the string value you define in DefaultValue is then used to initialize the variable instead.

Building an Application

Build functionality prepares your application for deployment by converting the Function Canvas contents into a proprietary XML-based intermediate language. The code is then compiled and additional application components (such as media resources, the installer, and so on) are combined into a single .mca archive file.

To build your application, follow these steps:

Procedure


Step 1 Choose Build > Build Project.

The build process starts and sends build-related output to the Output window, including errors. If the build succeeds, the message Build Successful appears at the end of the output.


Deploying an Application

Deploy functionality uploads the archived .mca file to the Application Runtime Environment.


Tip If you have not already done so, Deploy will also build and save your project.


To deploy the project, follow these steps:

Procedure


Step 1 Choose Build > Deploy.

If you have not configured the Application Server Network Address and Administrator User Name and Password, the system prompts you to do so now. For more information, see the "Configuring Connection to Cisco Unified Application Server" section.

The deployment process starts and sends output to the Output window, including errors. If the deployment succeeds, the message Package deployed appears at the end of the output.

The application enters an Enabled Running state.


Setting Application Configurations

After you deploy 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, it is likely that this step would be 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.

Configuring Connection to Cisco Unified Application Server

To deploy your application, you can either send it to the administrator of the Cisco Unified Application Environment to deploy for you, or you can automatically deploy from the Cisco Unified Application Designer. To automatically deploy, you must configure the Unified Application Designer to connect to the Cisco Unified Application Server.

To configure the connection to the Cisco Unified Application Server, follow these steps:

Procedure


Step 1 Choose Tools > Options.

The Options window appears.

Step 2 Click Connectivity.

The Connectivity page appears.

Step 3 Enter the IP address of the Cisco Unified Application Server to which you want to deploy your applications.


Tip Always use port 8120 as this is not configurable on the server side.


Step 4 Enter the administrator User Name and Password.

Step 5 Click OK.