In a campus, in the event of an emergency, the response can come from multiple sources such as the campus security and the police department. When a 911 call is placed, the campus security needs to be alerted with the appropriate information in addition to routing the 911 call to the 911 emergency centers.

This paper investigates how CUAE can provide the ability to build such an application.

Use case#

A campus, abc.edu has many phones installed. The campus has a command and control center that has many desk phones and mobile phones that are used by the campus security. When a student in the campus dials 911, in addition to routing the 911 call to the 911 emergency centers, the campus security must be alerted in multiple formats with the following information about the 911 call that was placed.

1. MAC Address of the device

2. UserID of the caller

3. IP Address of the device

4. Location of the device

5. Time at which the call was made

Requirement Analysis#

Based on this use case, the requirements can be summarized as

1. The alerts must provide the appropriate information for the security to locate the area from which the call was made

2. The alert must be made in multiple formats such as text and audio announcements.

3. The alerts must be displayed on a variety of phones which includes desk phones as well as cordless phones such as a 7921 phone.

4. Due to the sensitivity of the type of call, the 911 call should not be affected even if the alert system is down.

High Level Design#

Based on these requirements, CUAE appears to a perfect fit to build such an application that will provide the required functionality.

The High Level Life cycle#

The high level life cycle of such a call would involved the following steps

1. In the event of a 911 call, kick start the CUAE application

2. Collect the appropriate information from multiple sources

3. Push the alerts to the phones on the command center

4. Play the audio alert on the phones on the command center

CUAE provides multiple options to build such a solution. It provides actions such as record using its own internal components in addition to the flexibility to integrate with external functionality.

The Application Flow#

The application flow will include the following steps

1. When the system comes up, get the list of devices and add it to the monitored device pool and monitor the phones using JTAPI.

2. A student makes a 911 call from one of the campus phone. The call is routed to the 911 center without CUAE active involvement through PSTN.

3. A JTapiCallEstablished event with the trigger params matching the emergency call pattern triggers the application in CUAE

4. The application verifies the digits dialed once more and starts the alert procedures.

5. The CUAE application communicates with the CUCM using AXL and gets the IP address of the phones.

6. The CUAE application communicates with the management service and gets the user ID and other information

7. The application communicates with the campus information server and gets the physical location of the device

8. CUAE pushes this information to the display on all the phones by using JTAPI

9. CUAE uses TTS and media engine conference and multicasts the audible alerts to all the phones and to the campus security PA system.

High Level System Architecture#

CUAE provides multiple options to use in terms of protocols and configurations. The diagram indicates the high Level System Architecture of such a solution.

Implementation Notes#

CUAE provides multiple options to build such a solution. We will consider few of these cases.

Starting the CUAE application in the event of a 911 call#

The 911 call can be extended to the CUAE using active (first party call control) or passive (3rdparty call control). CUAE provides the choice of SIP, H323 or CTI for the first party call control and JTAPI for third party call control.

Even though CUAE provides both passive (using JTAPI monitoring) and active (using first party call control with SIP/H323/CTI protocols) methods to extend the call from the CUCM to the CUAE, due to the sensitivity of the call, active involvement is not recommended.

Passive Involvement of CUAE#

When a 911 call is made by a student in the campus, JTAPI 3rdparty events are used to inform the call origination to the CUAE. This uses 3rdparty APIs

Advantage://

If CUAE is down, this setup will not affect the original call.

Disadvantage://

The devices must be CTI monitored. (Registered with a monitored device pool)

Active Involvement of CUAE#

When a 911 call is made, the call is routed to the CUAE as a first party call. A protocol such as SIP, H323 or JTAPI can be used. CUAE is involved in the call and the routing from the CUCM to CUAE is based on the pattern. CUAE forwards the call to the 911 center (Not recommended for 911 calls).

This can be choice if the campus security is interested in the voice conversation between the originating phone and the 911 center.

Advantage://

The devices do not have to be monitored for this phase. This is better in terms of scale.

Disadvantage://

If CUAE is down, this setup will affect the original call

Protocol Choices#

For this type of an application since the passive approach is preferred, JTAPI (3rdparty) is preferred.

Using JTAPI monitoring of phones#

The campus phones can be monitored using JTAPI 3rparty APIs. When a student makes a 911 call, JTAPI 3rdparty call events such as JTapiCallInitiated and JTapiCallEstablished.

Triggering the CUAE Application#

CUAE can have multiple applications registered with it. The intended application can be triggered using the appropriate triggering event and parameters.

Further decision on when to start the alert procedures can be done at two levels:

1. Filtering at the CUAE level: Applications can add triggering parameters that would dictate when the application is triggered and the emergency procedures are started.

2. Filtering at the Application level: Once the application is triggered, the application can use its own business logic (in this case, the digits dialed analysis) to decide if it is interested in starting the emergency procedure. (Less preferred due to the application being triggered for every call)

Triggering Events and Parameters#

In this scenario, since we are interested in the dialed digits, the obvious choice for the triggering event would be

¿ JTapiCallEstablished

If trigger parameters are not specified, the application will get triggered for all calls since all calls generate JTapiCallEstablished.

Trigger Params can be used to trigger specific application when a particular condition matches. For example, In this case, if the dialed digits match the emergency call pattern (911, 9911) the application will be triggered and to achieve this, the trigger parameter 'To' can be used. This will ensure that Emergency application will be triggered only for emergency calls.

Note 1: Remember to add all the patterns for emergency calls as parameters. CUAE supports adding multiple parameters with the same name, but different values.

Note 2: The trigger params can be added using the management service API programmatically. Please refer the configuration section.

Exploring alternative events#

Alternative events can also be used to trigger the application, but may not be the most efficient or ideal choice. We will consider few cases and mention the caveats.

JTapiCallInitiated and JTapiGotDigits//#

The combination of these events has some caveats:

1. Each digit generated a JTapiGotDigits. The applications has to buffer these digits and do the analysis

2. If the user doesnot go offhook and dials the digits and presses the softkey 'Dial', JTapiGotDigits will not be generated

JTapiCallInitiated and JTapiCallEstablished//#

In the CUAD applications, each call can have only one triggering event. Since both JTapiCallInitiated and JTapiCallEstablished are triggering events, the JTapiCallEstablished is not forwarded to the application.

Instead, the non triggering version of JTapiCallEstablished, JTapiNonTriggeringCallEstablished can be used if this combination is required by the application.

Collect the appropriate information from multiple sources#

In addition, it provides the flexibility to integrate with external applications using multiple protocols.

The JTapiCallEstablished event contains the device name of the device from which the call was made. Using this information, addition information can be collected from multiple sources

Getting the line and User Information#

JTAPI provides APIs to find the addresses mapped on the device. The application can call actions on the JTAPI 3rdparty API to get this information. The management service API also provides additional information on the devices.

Getting the Network Information#

The AXL interface on the CUCM provides information such as the IP address, UserName, Extensions.

Getting the location Information#

The physical location of the device can be obtained from the campus information servers. Since such servers can have different interfaces, CUAE provides the ability to build customer Plugins for such applications. These Plugins provide an Etch interface to the applications to access the APIs of the Plugins.

Push the text alerts to the phones in the command center#

Once the appropriate information has been collected, the information can be pushed in the form of IP phone commands to the phones using HTTP or JTAPI.

CreateText phone API is used to create the Text XML object, which can be displayed on a Cisco IP Phone. CreateText allows the developer to format the phone display with Title, Prompt and Text sections of the message.

Using HTTP#

The SendExecute API can be used to push the text using HTTP. The XSI data obtained from the CreateText phone API is send to the phone in the message.

Advantages://

The devices do not have to be JTAPI monitored.

Disadvantages://

The application has to know the IP address of the phone.

Supports a maximum of 1500 bytes of payload

Using JTAPI#

The JTapiSendXSIData API can be used to push the text using JTAPI. The XSI data obtained from the CreateText phone API is send to the phone in the message.

Advantages://

The application does not have to know the IP address of the phone.

Supports larger size (2000 bytes) of payload

Disadvantage://

The devices have to be JTAPI monitored.

Adding Devices to the Monitored Device Pool//#

On the CUAE side, the device must be added in the monitoring device pool. This can be done in multiple ways and is documented in the configuration section.

Play the audio alert on the phones on the command center#

We will use the information that we have and convert to the text to an audio stream using TTS and multicast it to all the command and control phones.

The media engine creates a conference with the PA system and the multicast port. JTAPISendExecute pushes the execute object with the RTPMRx with the multicast port on which the TTS message will be played to every phone.

The application sends the appropriate message to the TTS server using the app server media control API 'Play'.

The PA systems can be either added to the conference if they support RTP streams or the sound output of RTP player can be fed to it through an audio input.

Configuration#

Adding Agent phones for monitoring#

Application can add agent phone for monitoring using multiple options provided by CUAE. These include:

1. Adding the phones to a monitored device pool manually through the cuaeadmin

2. Adding the phones from the application using JTapiNonTroggeringSubscribe

3. Adding the phones from the application using the management service API

Trouble Shooting#

JTapiSendXSIData fails#

Follow the following steps to debug the issue

1. Check if the device is monitored and is in Enabled Running

2. Verify if the data being send is greater than 2000 bytes

Contact Information#

For questions, please send an email to cuae-developers@developer.cisco.com

The discussion archives can be found at http://developer.cisco.com/web/cuae/forums

Author: Rajesh Vargheese

Sample reference application#

Coming soon...