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

Building the MakeCall Application with the Cisco Unified Application Designer

Table Of Contents

Building the MakeCall Application with the Cisco Unified Application Designer

Understanding the Example Application

Parsing the HTTP Request

Creating the MakeCall Example Application

Using Branch Conditions

Creating a Branch Condition

Using If Statements

Creating an If Statement

Building and Deploying the MakeCall Application

Configure the Application Partition Call Route Group

Running the MakeCall Application


Building the MakeCall Application with the Cisco Unified Application Designer


This chapter guides you through creating a sample using the Cisco Unified Application Designer. It contains the following sections:

Understanding the Example Application

Parsing the HTTP Request

Creating the MakeCall Example Application

Using Branch Conditions

Using If Statements

Building and Deploying the MakeCall Application

Running the MakeCall Application


Tip Chapter 6, "Building Etch-Based Applications" contains Etch-based example applications with sample code in Java and C#. Additional example applications and articles are available on the Cisco Unified Application Environment wiki at the following URL:
http://developer.cisco.com/web/cuae/wikidocs


Understanding the Example Application

The MakeCall example application will do the following:

1. Receive an HTTP Request that contains a phone number in the query portion of the URI.

2. Call the number from the URI.

3. If the call is successful, play a message and hang up the correct call based on the callID.

4. If the call is successful, but the answering party hangs up before the message finishes playing, end the script.

5. If the call is unsuccessful, end the script instance.

6. If the call is successful, but the message fails to play, hang up the correct call based on the callID, and end the script instance.

Parsing the HTTP Request

After you deploy the MakeCall application, an instance of the application will be triggered to start when the application server receives an HTTP request from a URI like the following:

http://<host:port>/path?query

For example:

http://10.1.1.50:8000/makecall_tutorial?to=5000

Table 5-1 explains each component of the URI and how it works with the Cisco Unified Application Environment in this example.

Table 5-1 MakeCall Example Application URI Components

URI Component
Description

Host

The IP address or host name of your Cisco Unified Application Server

Port

The port to use for the HTTP request. Always use port 8000 to send an HTTP request to your Cisco Unified Application Server.

Path

The path portion of the URI begins with the initial '/' after the Host portion and ends with the character before query parameter.

Query

This is the query string that will contain the phone number the script instance will dial.


Creating the MakeCall Example Application

To create the MakeCall example application, follow these steps:

Procedure


Step 1 Create a new project to contain the script or scripts that make up your application:


Note For this example, you will create only one script.


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

The New Application Designer Project window appears.


Tip A project is also sometimes referred to as an application. It is the container for all scripts.


b. Enter a project name in the Project Name field. For this example, enter makecall_tutorial.

c. Browse to the location you want to use to store the project files.

d. Click OK.

The window closes and the New Application Script window appears.

Step 2 Name your script and connect the script with a triggering event:


Note A triggering event is an event that can cause a new script instance to begin executing. When you create a new project, the system displays a list of preconfigured triggering events for you to choose from. For more information about an event, see the API reference for the version of Cisco Unified Application Designer you are using.

For this example, the triggering event will be an HTTP request made to the Cisco Unified Application Server.


a. Enter a script name. For this example, enter script1.

b. Select Metreos.Providers.Http.GotRequest from the list of triggering events.

c. Click OK.

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

The Designer creates an OnGotRequest script canvas and displays the OnGotRequest tab.

Step 3 Set the application to recognize the type of HTTP requests that trigger an instance of this script:

a. Select the triggering event in the Global Canvas. For this example, the triggering event is Metreos.Providers.Http.GotRequest.

GotRequest event parameters populate the Event Parameters section. Figure 5-1 shows an example of the Event Parameters for the OnGotRequest triggering event.

Figure 5-1 OnGotRequest Event Parameters


Tip For a detailed description of all event parameters, see the API reference, which is installed with the Developer Tools and also available on the Cisco Unified Application Environment wiki, at the following URL: http://developer.cisco.com/web/cuae/wikidocs?src=/wiki/display/CUAE/API+Reference


b. Enter a string in the Url event parameter field to identify the path portion of the request URI. For this example, enter /makecall_tutorial. Figure 5-2 shows the Url parameter.

Figure 5-2 Url Parameter

Step 4 Add the MakeCall action:

a. Click the OnGotRequest tab.

The OnGotRequest Function Canvas appears. It contains only a Start node.

b. Drag the MakeCall action from the Call Control toolbox to the Function Canvas. Figure 5-3 shows an example MakeCall action on the OnGotRequest Function Canvas.

Cisco Unified Application Designer creates two new functions, OnMakeCall_Complete and OnMakeCall_Failed, and displays tabs for the Function Canvases.

Figure 5-3 MakeCall Action On Canvas

Step 5 Create a local variable that can access the query portion of the HTTP Request URI so that you can extract the phone number in the MakeCall function:

a. Right-click the Function Canvas and select Variables Tray. Figure 5-4 shows the right-click options on the Function Canvas.

Figure 5-4 Function Canvas Right-Click Options

The Variables Tray displays at the bottom of the canvas.

b. Right-click inside the Variables Tray and select Add New Item. Figure 5-5 shows the Variables Tray and how to add a new variable.

Figure 5-5 Variables Tray Right-Click Option

An unnamed variable appears in rename mode.

c. Name the variable query and press ENTER to save the name.

The Basic Properties for the new variable appear in the Properties Grid.

The InitializeWith drop-down list contains all of the GotRequest event parameters. Figure 5-6 shows an example of the Basic Properties for a variable.

Figure 5-6 Query variable properties

d. Select Query from the IntializeWith drop-down list.


Note This points the query local variable to the query portion of the request URI. Other actions in the same function can then use information from the query.


e. Select QueryParamCollection from the Type drop-down list.


Note The QueryParamCollection native type allows you to access the name-value pairs contained in the query portion of the URI.

When the Application Server receives an HTTP request containing the path you specified in Step 3 above, the Application Runtime Environment initializes the QueryParamCollection type with the string value contained in the Query event parameter.

In this example, the string value would be similar to: '?to=5000'. Once the QueryParamCollection type has initialized and therefore parsed the query portion of the URI, you can then use the type in a C# code snippet to extract the phone number from the query.


Step 6 Create a local variable that can access the host portion of the HTTP Request URI so that you can extract the host's IP address in a later function:

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

b. Name the variable host and press ENTER to save the name.

The Basic Properties for the new variable appear in the Properties Grid.

The InitializeWith drop-down list contains all of the GotRequest event parameters.

c. Select Host from the IntializeWith drop-down list.

Step 7 Set the destination number for the phone call to the number in the HTTP request URI:

a. Click the MakeCall action.

MakeCall properties populate the Properties Grid.


Tip You can also select an action by clicking and dragging to draw a box around it.


b. Right-click the STR box that corresponds to the To property.

Select csharp. Figure 5-7 shows an example of the To property options.

Figure 5-7 MakeCall Action To Parameter Right-Click Options

c. Enter query["to"] in the field.

Step 8 Configure the MakeCall_Complete event to play a message:

a. Click the OnMakeCall_Complete tab.

The OnMakeCall_Complete Function Canvas appears.

b. Drag the Play action from the Media Control toolbox to the Function Canvas.

Cisco Unified Application Designer creates two new functions, OnPlay_Complete and OnPlay_Failed, and displays tabs for the Function Canvases.

c. Right-click the Function Canvas and select Variables Tray.

The Variables Tray displays at the bottom of the Function Canvas.

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

An unnamed variable appears in rename mode.

e. Name the variable connectionId and press ENTER to save the name.

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

The InitializeWith drop-down list contains all of the MakeCall_Complete event parameters.

f. Select ConnectionId from the IntializeWith drop-down list.


Note This maps the connectionID local variable to the actual unique identifier assigned to a successful connection. The local variable can then be used in subsequent Media Control API operations.


Step 9 Configure the Play action to contain a text-to-speech message:

a. Click the Play action.

Play properties populate the Properties Grid.

b. Right-click the STR box that corresponds to the ConnectionId property.

c. Select variable.

All global variables and local variables for this function display in the drop-down list.

d. Select connectionId.


Note Associating the connectionID to the ConnectionId property tells the Play action over which connection to send media.


e. Ensure that STR is in the input type box corresponding to the Prompt1 property.

f. Enter a text message in the Prompt1 field and provide a prompt message. In this example, text-to-speech speaks the text message.

Step 10 Hang up the call after the message plays successfully:

a. Click the OnPlay_Complete tab.

The OnPlay_Complete Function Canvas appears.

b. Drag the Hangup action from the Call Control toolbox to the Function Canvas.


Note The Hangup action requires a CallId to hang up the correct call. Every completed MakeCall action is assigned a unique identifier named CallId. To pass this identifier to the Hangup action, you must create a global variable and assign it with the MakeCall result variable.


c. Click the script1 tab.

The Global Canvas appears containing two folders: Events and Functions and Variables.

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

An unnamed variable appears in rename mode.

e. Name the variable g_callId and press ENTER to save the name.

The properties for the new variable appear in the Properties Grid.

f. Click the OnGotRequest tab.

The OnGotRequest Function Canvas appears.

g. Click the MakeCall action.

MakeCall properties populate the Properties Grid.

h. Under Result Data, right-click the CallId drop-down list.

i. Select g_CallId.

j. Click the OnPlay_Complete tab.

The OnPlay_Complete Function Canvas appears.

k. Click the Hangup action.

Hangup properties populate the Properties Grid.

l. Right-click the STR box that corresponds to the CallId property.

m. Select variable.

n. Right-click the CallId drop-down list.

o. Select g_CallId.

Step 11 End the OnMakeCall_Complete function:

a. In the OnMakeCall_Complete canvas, drag the EndFunction function from the Application Components toolbox.

Step 12 End the script after hanging up:

a. In the OnPlay_Complete canvas, drag the EndScript function from the Application Components toolbox.


Note Use EndScript or EndFunction to clean up all associated script resources. Correctly using EndScript keeps your script instance license usage down to a minimum. Failure to use either EndScript or EndFunction for all scripts causes build errors.


Step 13 End the script if the call fails:

a. In the OnMakeCall_Failed canvas, drag the EndScript function from the Application Components toolbox.

Step 14 Hang up the call and end the script if the message fails to play successfully:

a. Click the OnPlay_Failed tab.

The OnPlay_Failed Function Canvas appears.

b. Drag the Hangup action from the Call Control toolbox to the Function Canvas.


Note The Hangup action requires a Call ID to hang up the correct call. Since you created a global CallId variable in Step 10, you can use that variable again here.


c. Click the Hangup action.

Hangup properties populate the Properties Grid.

d. Right-click the STR box that corresponds to the CallId property.

e. Select variable.

f. Right-click the CallId drop-down list.

g. Select g_CallId.

h. In the OnPlay_Failed canvas, drag the EndScript function from the Application Components toolbox.

Step 15 End the script if a remote party hangs up the call before the message plays:


Note The RemoteHangup event signifies that the party called with the MakeCall action has hung up.  When a call is ended in this way, all resources associated with the call are automatically stopped. For example, if the text-to-speech prompt played by this script was playing as the remote party hung up the call, then that prompt is automatically stopped, and the underlying connection to the Cisco Unified Media Engine is disconnected.


a. Click the script1 tab.

The Global Canvas appears containing two folders: Events and Functions and Variables.

b. Drag the RemoteHangup event from the Call Control toolbox to the canvas.

The RemoteHangup event is added under Events and Functions and an OnRemoteHangup tab appears. Figure 5-8 shows the RemoteHangup event in the Call Control toolbox.

Figure 5-8 Adding the RemoteHangup event to the script

c. Click the OnRemoteHangup tab.

The OnRemoteHangup Function Canvas appears.

d. Drag the EndScript function from the Application Components toolbox.


Using Branch Conditions

Every action returns a condition indicating the high-level outcome of the action (Success, Failure, or Timeout). Using conditions, you can create a branch off of the execution path for a success path and failure path within a function. This section describes how to create a branch condition for the MakeCall example you just created.

For each script instance, the execution path will branch depending on the outcome of the MakeCall action in the following way:

If the MakeCall action initiates successfully, the script sends a response to the user that the intended endpoint should be ringing.

If the MakeCall action does not initiate successfully, the script sends a response page to the user that contains some common mistakes to check.

Creating a Branch Condition

To create a branch condition on the MakeCall example application, follow these steps:

Procedure


Step 1 If you closed the Cisco Unified Application Designer after creating the MakeCall_Tutorial application, open the MakeCall example and navigate to the OnGotRequest Function Canvas:

a. Choose File > Open Project to open an existing project.

The Open Application Designer Project window appears.

b. Browse to the location where you saved your project files and select the file with the .max extension.

c. Click Open.

The window closes and the project appears in the Cisco Unified Application Designer.

d. Click the OnGotRequest tab.

The OnGotRequest Function Canvas appears.

Step 2 Branch the execution path to send a plain text response if the MakeCall action succeeds:

a. Drag the SendResponse action from the HTTP toolbox to the Function Canvas and position it between the MakeCall and EndScript actions that already exist.


Note Up to this point, the MakeCall example application uses only default branch conditions because there was not a need to define a specific path based on an action's condition.


Click the execution path between MakeCall and SendResponse on the word default and select Success from the drop-down list. Figure 5-9 shows the branch Condition drop-down list.

Figure 5-9 Condition drop-down list

b. Click the SendResponse action.

SendResponse properties populate the Properties Grid

c. Enter the following response message in the Body text box.

The call was initiated successfully. The endpoint should be ringing.

d. Enter text/plain in the Content-Type text box.

e. Enter 200 in the ResponseCode text box.

Step 3 Create a variable that contains the IP address of the RemoteHost from the GotRequest event and use it in the SendResponse action:

a. Right-click the script canvas and select Variables Tray.

The Variables Tray displays at the bottom of the canvas.

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

An unnamed variable appears in rename mode.

c. Name the variable remoteHost and press ENTER to save the name.

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

The InitializeWith drop-down list contains all of the GotRequest event parameters.

d. Select RemoteHost from the IntializeWith drop-down list.


Note This points the remoteHost local variable to the actual IP address that sent the triggering HTTP Request. The local variable can then be used in subsequent HTTP operations, such as SendResponse.


e. Click the SendResponse action.

SendResponse properties populate the Properties Grid.

f. Right-click the STR box that corresponds to the RemoteHost property.

g. Select variable.

h. Click the RemoteHost drop-down list.

i. Select remoteHost.

Step 4 Add a branch condition that sends an HTML response if the MakeCall action fails:

a. Drag the SendResponse action from the Application Components toolbox to the Function Canvas and create a new branch to it from the MakeCall action that already exists.


Tip For information about how to create a branch and other tips on using the Designer, see Chapter 3, "Using the Cisco Unified Application Designer."


b. Drag an EndScript action from the Application Components toolbox and position it after the new SendResponse action to end that branch.

c. Ensure that the branch between MakeCall and the new SendResponse uses the default condition.


Note Since you created a Success condition on the branch in Step 2 above, the default branch will handle all non-Success conditions, such as Failure or Timeout.


d. Click the SendResponse action.

SendResponse properties populate the Properties Grid.

e. Click the ... (ellipsis) button that corresponds to the Body property.

f. In the text box, enter the following HTML:

<html>
<body>
<h1>The call failed to initiate.</h1>
Consider troubleshooting one of the following:
<ul>
<li>Configuration between the Cisco Unified Application Server and Cisco Unified 
Communications Manager</li>
<li>Installation and configuration on the Cisco Unified Application Environment 
itself</li>
</ul>
</body>
</html> 

g. Enter text/html in the Content-Type text box.

h. Enter 200 in the ResponseCode text box.

i. Right-click the STR box that corresponds to the RemoteHost property.

j. Select variable.

k. Right-click the RemoteHost drop-down list.

l. Select remoteHost.


Note All SendResponse actions require a RemoteHost property to respond to the correct IP address. Since you created a remoteHost variable in Step 3 above, you can use that variable again here.



Using If Statements

For most applications that receive user input, it is a best practice to validate the input in some way. Creating an If statement in the Cisco Unified Application Designer is practically similar to branching the execution path using branch conditions, but it is used primarily to validate user input.

For the MakeCall example application, the If statement checks to ensure that the HTTP Request contains a 'to' query parameter. If it does not, then it returns an appropriate error response to the client, to indicate that the 'to' query parameter must be supplied.

This example will use C# snippets to validate the query parameter and to send a response containing data specific to the script instance.

Creating an If Statement

To create an If statement on the MakeCall example application, follow these steps:

Procedure


Step 1 Open the MakeCall example created in the "Creating the MakeCall Example Application" section.

Step 2 Create an If statement to validate that a "to" query parameter is present in the HTTP Request:


Tip For example: http://[appserver_ip]:8000/MakeCall_Tutorial?to=5000. For more information about the HTTP Request URI, see "Parsing the HTTP Request" section.


a. Click the OnGotRequest tab.

The OnGotRequest Function Canvas appears.

b. Drag the If action from the Application Components toolbox to the Function Canvas and position it between the Start and MakeCall actions.

c. Connect the Start node to the If action and connect the If action to the MakeCall action.

d. Select the true condition for the branch between the If action and MakeCall action.

e. Click the If action.

Properties for the If action populate the Properties Grid.

f. Right-click the STR box that corresponds to the Value1 property.

g. Select csharp.

h. Enter the following code snippet in the text box:

query["to"] != null && query["to"] != String.Empty 

Note This snippet verifies that the "to" query parameter is in the HTTP Request URI and that is not empty.


Step 3 Configure the SendResponse action:

a. Drag the SendResponse action from the HTTP toolbox to the Function Canvas and position it below the If action.

b. Select the false condition for the branch between the If action and SendResponse action.

c. Create a new branch to the SendResponse action from the IF action.


Tip For information about how to create a branch and other tips on using the Designer, see the"Configuring Connection to Cisco Unified Application Server" section on page 3-15


d. Drag an EndScript action from the Application Components toolbox and position it after the new SendResponse action to end that branch.

e. Click the SendResponse action.

Properties for the SendResponse action populate the Properties Grid.

f. Right-click the STR box that corresponds to the Body property.

g. Select csharp.

h. Enter the following code snippet in the text box:

"Please specify in the URI a 'to' query parameter.\nEx: http://" + host + 
"/MakeCall_Tutorial?to=5000" 

Note This snippet replaces " + host +" in the code with the server's IP address and port.


i. Enter text/plain in the Content-Type text box.

j. Enter 200 in the ResponseCode text box.

k. Right-click the STR box that corresponds to the RemoteHost property.

l. Select variable.

m. Right-click the RemoteHost drop-down list.

n. Select remoteHost.


Note All SendResponse actions require a RemoteHost property to respond to the correct IP address. Since you created a remoteHost variable in Step 3 in the "Creating a Branch Condition" section, you can use that variable again here.



Building and Deploying the MakeCall Application

To build and deploy your application, follow these steps:

Procedure


Step 1 Choose Build > Deploy.


Note 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 on page 3-15.


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.

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.


Configure the Application Partition Call Route Group

After you install your application and before you run it, you must configure the application's Default partition to use the Default SIP Call Route Group in the Cisco Unified Application Environment Administration. This causes the application to use the SIP integration created in Chapter 2, "Preparing Your Development Environment" when communicating with Cisco Unified Communications Manager.

To configure the partition call route group, follow these steps:

Procedure


Step 1 Log in to Cisco Unified Application Environment Administration.

Step 2 Click Applications > List Applications.

The list of all applications appears.

Step 3 Locate and click the MakeCall application in the list.

The Application Details page appears.

Step 4 Select the Default SIP from the CallRoute GroupId drop-down list. Figure 5-10 shows a properly configured Application Details page.

Step 5 Click Done.

Figure 5-10 MakeCall Application Details Page


Running the MakeCall Application

To run the example MakeCall application, follow these steps:

Procedure


Step 1 Open a web browser and enter the URL to the Cisco Unified Application Server with the trigger you assigned to the application in Step 3 in Creating the MakeCall Example Application.

If the call initiates successfully, a message is displayed in the web browser, as shown in Figure 5-11, the phone you configured rings and when answered, plays a message.

Figure 5-11 Testing the MakeCall Application


Note If the test does not work, check the server logs for any errors. See the Cisco Unified Application Environment Administration Guide for more information about logging.