CUAE API Reference Glossary

This glossary defines the complex concepts that are needed for fuller understanding of individual actions, events, and types defined in the CUAE API Reference Guide.

CUAE Core Terms

Action

An action represents a single block of code that has zero or more inputs and zero or more outputs.

Action Parameter

An action parameter is an input to an action. It is comprised of a name, a value, and a type declaring how the value should be intepreted (literal, variable, csharp).

Application Lifetime

The life of an application is started when the application server loads the application, which in practice happens either when the application is first installed or if the application is already loaded when the application server service is starting. The life of the application ends when the application is either disabled, uninstalled, or if the application server service is stopped.

Application Partition

All script instances execute within the context of an application partition. An application partition defines a number of parameters for the script instance, such as Call Route Group, Media Resource Group, Reserve Media Early, Locale, and custom configuration items. An application partition can not be set or changed by the script instance; instead, by setting event filter criteria, one can configure in mceadmin which partition of a particular script initiates under which condition.

Partitions provide a means to split a single application into different templates or modes of operation. Usually partitions correspond to geographies of the user(s) of the application, but certainly this is not the only use for partitions.

Application Runtime Environment

The entity within the application server which manages the execution and messaging of scripts.

Asynchronous Action

An ansynchronous action is an action that has defined one or more asynchronous callbacks. An asynchronous action, in conjuction with asynchronous callbacks, form a simple design pattern: the usage of a single asynchronous action will result in one (and only one) of the asynchronous callbacks defined for that action being fired back to the same script instance that invoked the action.

Asynchronous Callback

One ansynchronous callback event out of other asynchronous callbacks defined by an asynchronous action, is guaranteed to fire back to the same script instance that used the corresponding asynchronous action, making an asynchronous callback a non-triggering event.

Branching

Actions always exit with a branch condition which should indicate the overall outcome of the action. An action can return any string value; by convention, must actions built by Cisco Systems return success and failure. The default branch condition is a special keyword that one can define when using any action to indicate a catch-all branch for that action.

Call Route Group

A Call Route Group defines 1 or more telephony endpoints that practically correspond to one or more Cisco Unified Communication Manager nodes in a cluster. A Call Route Group also is associated with a single call control protocol (SIP, H.323, SCCP, CTI). Call Route Groups are associated with application partitions in mceadmin.

Once a Call Route Group has been defined, it can be associated with any number of application partitions. If a script instance uses MakeCall or Barge, the configured Call Route Group will decide which protocol is used to communicate with the Cisco Unified Communications Manager configured in the Call Route Group.

Cisco Unified Application Designer

The graphical IDE of the Cisco Unified Application Enviroment in which applications are built.

Cisco Unified Application Environment

The Cisco Unified Application Environment is an umbrella term encompassing the three discrete products which comprise a development platform for building applications which leverage Cisco voice infrastructure and enterprise applications and data. These there products are the Cisco Unified Application Server, Cisco Unified Media Engine, and the Cisco Unified Application Designer.

Cisco Unified Application Server

The Cisco Unified Application Server performs two major functions. One is to act as a hub for any number of protocols, implemented via providers. The other is to host applications, which implement business logic and have the installed providers at their disposal when executing.

Cisco Unified Media Engine

The Cisco Unified Media Engine is a rich-media processing node that can perform a number of operations on RTP audio streams. The Media Engine is not directly extensible or programmable. The only means by which it is controlled is with the Cisco Unified Application Server the Media Control or Call Control API.

Custom Action Parameters

Actions are comprised of zero or more static, well-defined action parameters. For some actions, it may be possible for the developer of the action to declare every action parameter when the action is built. If the action allows custom action parameters, then the action can have arbitrary action parameters, meaning they can have any name. Such actions have a different behavior within the property grid of the Cisco Unified Application Environment, in that they have a unique property called Custom Action Parameters.

CustomCode

CustomCode is a special-case action that allows an application developer to create user-defined C# code and place it in a single function that is invoked when the action is executed by the script instance.

There are a few major aspects of a CustomCode action.

Method Arguments

In the string Execute(...) method signature of a CustomCode, one can pass in any global variable, local variable, or the few, special omnipresent variables that always exist in the context of a script instance or loop. Regardless of what is being passed in, one must make sure that the resulting public static string Execute(...) is valid C#. So for instance, if one wanted to pass in an System.Int32 global variable named 'id' and also the always-present LogWriter log variable, the method signature becomes public static string Execute(int id, Logwriter log)

Event Filter Criteria

When an event rises up from a provider to the Application Runtime Environment, the event signature is subjected to the event filter criteria of every enabled script, in order to determine which script has the best-fit match for the event. If no script is a match, then a No Handler will occur.

Event Handler

An event handler function is initiated due to the occcurrence of an incoming event. An event handler function can also be invoked with the CallFunction action.

Event Parameter

An event parameter is a name/value pair that is associated with an instance of an event. Events are usually defined with event parameters that are known to occur for that event. However, events can send up undefined parameters and applications can use them if the name of the event is known by the application developer.

Event Signature

An event signature defines the characteristics of an event. When an event is created and sent up to the Application Runtime Environment, there are two fundamental components to the event. One is the event type, or name. The other is any event parameters that are associated with the event. A good example is an incoming call. The event name of that event is Metreos.CallControl.IncomingCall, and if number dialed was 6000 from a phone with a line number of 2000, then the event parameters would be To=6000, OriginalTo=6000, and From=2000.

Final

A final action is one that can not be followed by any other actions; it is always the last action in a function. There can be multiple final actions in a single function.

Function

A function contains some number of actions. A function can be initiated by an incoming event; such a function is known as an event handler. A function can also be invoked with the CallFunction action. All functions must formally declare when they come to an end. This is done by using a final action, such as EndFunction, EndScript, or Forward.

Media Resource Group

A Media Resource Group defines 1 or more media engines. Media Resource Groups are associated with application partitions in mceadmin.

Once a Media Resource Group has been defined, it can be associated with any number of application partitions. If a script instance uses any action which results in the creation of a media engine connection, then the configured Media Resource Group will determine which Media Engine in the group with the most available amount of resources will be used to host and process the connection (the exception to the rule is if one specifies MmsId in such an action, bypassing Media Resource Group logic. Such actions are ReserveConnection, CreateConnection, MakeCall, AnswerCall, AcceptCall and Barge.

Native Type

A variable built to exist within a script. All such variables must implement the IVariable interface.

When a value is passed to a native type, the best-fit Parse(System.Type) is used to take the value in and perform whatever processing deemed necessary for the type. All native types must implement Parse(System.String) due to the IVariable interface, although any number of Parse(System.Type) overloads may be implemented by a native type if the native type designer expects other value types to be passed to the native type variable.

No Handler

A no handler indicates the condition in which an event is sent up from a provider to be the Application Runtime Environment

Non-Triggering Event

A non-triggering event is an event that is sent to an already-running script instance. There are two types of non-triggering events: unsolicited and asynchronous callbacks..

Protocol Provider

A protocol provider typically implements a particular protocol, and translates it into the message format native to the Cisco Unified Application Enviroment. From the perspective of a protocol provider developer, the ultimate goal is to take complex interaction with the protocol and convert it to simple yet powerful API calls for applications built within the Application Runtime Environment. From the perspective of the application developer, protocol providers present an API from which underlying complexities of the protocol have been hdden away, and digested down to simple actions, events, and types.

Result Data

A result data parameter is an output to an action. It is comprised of a name and a variable native type that will be used to store the result of the action.

RoutingGuid

The RoutingGuid is a unique identifier for a script instance. It is used throughout the platform to identify a particular script instance.

Sandboxing

Sandboxing is a system-wide configuration which, if enabled, causes all calls and all media connections created by a script to be automatically destroyed when the script ends.

Script Event Queue

A script instance can only execute one event at a time. The Script Event Queue is an entity that exists for every script instance, and will queue up events that are routed to the script. The queue behaves in a first in/first out pattern; there is no way to alter this behavior. There is also no way to read events currently in the script queue. The only way to cause events to be handled in the queue promptly is to follow the best practice of designing event handler functions to spend as little time as possible in these functions so that events in the queue can be processed with minimal delay.

Session Data

SessionData is an omnipresent variable found in all script instances. It's instance name is .NET is sessionData

Triggering Criteria

A triggering event is an event that can cause a new script instance to begin executing.

Unsolicited Event

An unsolicited event is a non-triggering event that does not necessarily have a known number of times or when it will fire. For instance, if a chat system was integrated into the application server, each message in a session would conceivably be an unsolicited event, because it is generally unknown how many times, and when, a user will send a message.

Telephony Terms

Call Control

Call Control is used to encompass any 1st-party call control protocol, such as SIP, H.323, SCCP, or CTI (JTAPI, being a 3rd-party device monitoring protocol, is not consider a Call Control protocol). The Cisco Unified Application Environment has abstracted these 4 protocols into a single Call Control API that hides the underlying characteristics of complexities of the particular protocol being implemented.

Call Control Feature Matrix

.

Call Routing

Call Routing can be a very complex subject because it goes well beyond the boundaries of the Cisco Unified Application Environment. The calls that are made and answered by the Cisco Unified Application Server are, as a matter of best practice, routed through Cisco Unified Communications Manager. Cisco Unified Communication Manager's proficiency is call routing, and so it should always be the negotiator of the calls placed to and from the application server. Once a call is sent from the CUAE to CUCM, the call could be routed virtually anywhere, including other CUCM clusters, to the PSTN, voicemail, and other destinations. Likewise, a call that came from CUCM to the CUAE could have originally come from anywhere.

Because Call Control should always route through Cisco Unified Communications Manager, the path of the call control signaling will terminate to CUCM. As an example, even though a call may be SIP or H.323 from the CUAE to CUCM, CUCM may very well convert that call to SCCP if the calling/called device is a SCCP phone.

The sum of all routing logic defined by the administrator in Cisco Unified Communications Manager is known as the dial plan. Your application, when making calls, must conform to this dial plan. Specifically, if one is using MakeCall, the value To will be processed by the dial plan to determine where the specified number should go. In CUCM terms, the device appearance of the CUAE (such as an H.323 gateway, SIP Trunk, CTI Port, etc) has a calling search space(s) assigned to it, and some number of route patterns, line numbers, translation patterns, hunt patterns, and so on will all be analyzed to determine what final destination is a best match for the called number. In truth, call routing in CUCM can be even more complex then mentioned here. The 2nd chapter of Cisco CallManager Fundamentals (2nd edition) is a great summary of CUCM call routing.

Peer-to-Peer

A peer-to-peer call is actually two call legs that have been logically joined together by the Application Runtime Environment. The purpose of forming a peer-to-peer relationship between two call legs is to cause the media engine to be bypassed for the streaming of RTP for each call. Instead have the remote endpoints of each call stream directly to each other. Special behavioroccurs for the termination P2P calls; if one call leg hangs up, the other is also automatically hung up.

There are two ways to create a peer-to-peer call. One is to use the UnbridgeCalls action on two, already established call legs. The other is topass in a CallId from an unanswered, incoming call to the PeerCallId action parameter of MakeCall. When the call from MakeCall completes with MakeCall_Complete, the incoming call is automatically answered and the media streams of both are negotiated in a peer-to-peer fashion.

One can undo a peer-to-peer call by using the BridgeCalls, which will result in both call legs having their media streams renegotiated to transmit/receive to the media engine, in the process creating two new Media Engine connections.

Reserve Media Early

Reserve Media Early affects at what point during an outbound call created with MakeCall that the Application Runtime Environment will use ReserveConnection to create a connection on a media engine for the call. If set to true, then the connection is reserved as soon as the call is offered. If set to false, then the connection is not reserved until the media negotiation phase of the call, which is typically as the call is being answered by the remote endpoint. This setting is configured per application partition.

Wait For Media

Wait For Media is a parameter on MakeCall and AnswerCall that determines at which point in the call control and media negotiation signalling that the Application Runtime considers the call completed. Regardless of the setting, the call must be at a minimum completed from a purely telephony protocol perspective before the cal is considered completed; in other words, if one were using H.323 or SIP for instance, the call must reach the CONNECT or a 200 OK state. A value of TxRx, which is the default for both actions, indicates that the call should be considered completed only once both transmit and receive properties of the RTP streams for the call have been established. A value of Tx indicates that the call should be considered completed once the transmit properties of the RTP streams for the call have been established. A value of Rx indicates that the call should be considered completed once the receive properties of the RTP streams for the call have been established. A value of None indicates that the call should be considered completed as soon as the call control considers the call completed.

Media Control Terms

Base Audio Path

The Base Audio Path is the base directory for all media files available to the media engine. This path by default is C:\Program Files\Cisco Systems\Unified Application Environment\MediaServer\Audio. All recorded files are placed in this directory. If audio files are defined as resources of an application and that application is deployed to an application server, the application server will create additional folders under this Base Audio Path for that application for any media engines in its control. Please reference Application Audio Directory and the Locale Audio Directory for more information.

Application Audio Directory

The Application Audio Directory is a folder created underneath the base audio path for any application which has more than one audio files defined as a resource. No audio files are placed into this directory; it is used as a placeholder to distinguish from other applications and their own audio files.

The name of the folder corresponds to the name of the application.

Locale Audio Directory

The Locale Audio Directory is a folder created underneath the application audio directory. One such folder is created for every locale defined by audio files defined as resources in the application. Each audio file has a locale defined with it; all audio files packaged with the application as resources are placed into the their own defined locale directory. The media engine will attempt to read from this locale directory corresponding to the current locale that the application is executing under.

The name of the locale folder(s) corresponds to the name of the locale (i.e, 'en-US').

Media Control Error Codes

The following table represents all potential error codes and descriptions returned by Media Control API operations:
Error CodeDescription
0No Error
1No Error
4All sessions are in use
5Server disabled; likely shutdown
6Server code or logic error
7Device error
8Media resource not available
9Server in unexpected state
10Event registration error
11Unspecified event error
12Session inactivity
13Command timeout
14Session busy with prior request
15A connection already exists
16No connection exists
20Unrecognized event fired
21Command number not defined
22ConnectionId is in invalid format
23ConnectionId not registered
24Session is not in conference
25No operation in progress
26Insufficient parameters supplied
27Value error e.g. non-numeric
30File open error
31File read or write error
35Server command format error
36No such condition or bad value

Application Designer Terms

DefaultValue (local)

One can initialize a local variable with a string value by specifying a value in the DefaultValue property.. When the function starts that contains the local variable, the value in the event parameter will be assigned to the variable, using the Parse(System.String) overload defined on the IVariable class. Note that the DefaultValue will not be used if the InitializeWith property has been specified for which an event parameter is present that matches the value specified in that property.

InitializeWith (local)

One can initialize a local variable with an event parameter by specifying a value in the InitializeWith property which corresponds to the name of the event parameter of interest. When the function starts that contains the local variable, the value in the event parameter will be assigned to the variable, using the best-fit Parse() overload defined on the IVariable class. Note that one should also define a value in the DefaultValue when using InitializeWith with string-compatible variables to gracefully take care of the case that the event parameter does not exist in the event. In that case, the string value defined in DefaultValue will be used to initialize the variable instead. One can then do a comparison in their script to determine if the DefaultValue was used to initialize the variable by checking if the variable is the same value as the value defined in the DefaultValue property of the grid.