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.
An action represents a single block of code that has zero or more inputs and zero or more outputs.
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).
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.
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.
The entity within the application server which manages the execution and messaging of scripts.
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.
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
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
default branch condition is a special keyword that one can define when using any action to indicate a catch-all branch for that action.
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
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.
The graphical IDE of the
Cisco Unified Application Enviroment in which applications are built.
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.
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.
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.
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 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
string Execute(...) method signature of a
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)
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.
An event handler function is initiated due to the occcurrence of an incoming event. An event handler function can also be invoked with the
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.
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
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.
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
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
A variable built to exist within a script. All such variables must implement the
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.
A no handler indicates the condition in which an event is sent up from a provider to be the
Application Runtime Environment
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.
RoutingGuid is a unique identifier for a script instance. It is used throughout the platform to identify a particular script instance.
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.
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.
SessionData is an omnipresent variable found in all script instances. It's instance name is .NET is
A triggering event is an event that can cause a new script instance to begin executing.
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.
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 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.
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 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
Wait For Media is a parameter on
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.
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 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 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').
The following table represents all potential error codes and descriptions returned by Media Control API operations:
|4||All sessions are in use|
|5||Server disabled; likely shutdown|
|6||Server code or logic error|
|8||Media resource not available|
|9||Server in unexpected state|
|10||Event registration error|
|11||Unspecified event error|
|14||Session busy with prior request|
|15||A connection already exists|
|16||No connection exists|
|20||Unrecognized event fired|
|21||Command number not defined|
|22||ConnectionId is in invalid format|
|23||ConnectionId not registered|
|24||Session is not in conference|
|25||No operation in progress|
|26||Insufficient parameters supplied|
|27||Value error e.g. non-numeric|
|30||File open error|
|31||File read or write error|
|35||Server command format error|
|36||No such condition or bad value|
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.
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.