Avaya Solution & Interoperability Test Lab

Application Notes for the DMCC TeleCommuter Sample

Application - Issue 1.0

Abstract

The TeleCommuter application is a Device, Media and Call Control (DMCC) sample
application which demonstrates usage of DMCC XML messages for performing various
telephony services. This application sets up a “Telecommuter Number” for a given extension
by using DMCC XML messages supported by Avaya Application Enablement Services (AE
Services).

The application was built and tested using the following configuration:
• Avaya Communication Manager 4.0.
• Avaya Application Enablement Services 4.0
• PC running Microsoft XP Professional Version 2002 Service Pack 2
• Microsoft .NET Framework Version 2.0
• Microsoft Visual C# 2005 Version 8.0.50727.42

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 1 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
1. Introduction
The TeleCommuter application uses DMCC XML messages supported by Avaya Application
Enablement Services (AE Services) to set up the telecommuter number for a configured [primary]
extension. While registering the extension with AE Services server (which then subsequently
registers with Avaya Communication Manager (CM)), the application provides a Telecommuter
number. Whenever there is an incoming call to this primary extension, CM will alert (ring) the
telecommuter number. The call can be answered at the telecommuter number. The application
prints events as they are occurring at the primary extension, which indicate call status changes.

The network configuration used during testing is shown in Figure 1.

Application Enablement Services

TeleCommuter
Application

Communication Manager

Calling Called TeleCommuter

Extension Extension Extension
Ext xxxxx Ext 40010 Ext 40011

Figure 1: Network Configuration Diagram

2. Equipment and Software

Equipment Software
Avaya S8300 Media Server with Avaya G700 Avaya Communication Manager 4.0
Media Gateway
Avaya Application Enablement Services 4.0

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 2 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
3. Configuring the Application
The application reads configuration data from the file “TeleCommuter.exe.config” (refer to
Section 5.1 for the directory structure details). This configuration file contains data in XML
format and following fields need to be set with appropriate values. It is necessary that the user
modifies this file with valid information and places it in the same directory where the application
exe is located. However, if the user is using Microsoft Visual Studio (MSVS) to run the
application (debug or release mode) then the configuration file is "app.config" and user should
make changes in this file. MSVS takes care of copying this file as "TeleCommuter.exe.config"
while running the application.

The content of this file is as follows:

<?xml version="1.0" encoding="utf-8" ?>

<configuration>
<appSettings>
<add key="callserver" value="192.168.17.129" />
<add key="extension" value="40010" />
<add key="extension.password" value="40010" />
<add key="telecommuter.number" value="45011" />
<add key="DMCC.server_ip" value="192.168. 17.128" />
<add key="DMCC.username" value="avaya" />
<add key="DMCC.password" value="avayapassword" />
<add key="DMCC.protocol_version" value=" http://www.ecma-
international.org/standards/ecma-323/csta/ed3/priv1" />
<add key="DMCC.server_port" value="4722" />
<add key="DMCC.secure" value="true" />
</appSettings>
</configuration>

The callserver represents the Avaya Communication Manager IP address.

The extension represents the user station extension number for which the application sets up a
Telecommuter number. This extension needs to be provisioned on Communication Manager.
The default call appearance locations chosen by Communication Manager must be used. The “IP
Softphone” field on page one of the station form must be set to “y”.
The extension.password field represents the password associated with the user station
extension. This information needs to be provisioned for the extension provisioned above.
The telecommuter.number represents the telecommuter number which will get called
whenever there is an incoming call on the user extension.
The DMCC.server_ip represents the AE Services server IP address.
The DMCC.username and DMCC.password are the login and the password fields respectively for
the AE Services server.
The DMCC.secure field is a Boolean value which is set to true if a secure connection/port is
requested. If unsecured access is to be utilized then set this field to false

NOTE:
• DMCC.server_port and DMCC.secure fields are interdependent, i.e., if
DMCC.server_port field is set to 4721, then DMCC.secure must be set to false and if
DMCC.server_port field is set to 4722, then DMCC.secure must be set to true.

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 3 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
 • To execute the application in secure mode, the trusted certificate, avaya.crt, should be
installed on the developer machine. The certificate is contained in the XML and .NET
SDKs.

The DMCC.server_port field represents the access port which will be used by the application to
communicate with the AE Services server. It can take one of two values: i.e. 4721 for secure
connection and 4722 for non secure connection. Note that 4721 and 4722 represent the default
ports on an AE Services server, and these can be changed via AE Services OA&M. Note further
that only the secure port is enabled by default, and if the non-secure port is going to be used, it
must be enable via AE Services OA&M. Login to AE Services OA&M (http://<ip-address-of-
AE Services server>:8080/MVAP and go to “CTI OAM Administration > Network
Configuration > Ports”. Enable required DMCC server port, and then restart the MVAP
application using “CTI OAM Administration > Maintenance > .Service Controller > Restart AE
Server”. Here is a snapshot showing how to configure DMCC server ports.

Figure 2: DMCC Server port configurations

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 4 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
4. Using the Application
The executable for this application is provided along with the zipped source code. Extract the
source code and make the necessary changes to the configuration file as mentioned in section 3.
To run the application from the Windows Explorer navigate to the TeleCommuter\bin\Release
directory and double-click on the TeleCommuter.exe file.

When the application starts, a console window will be displayed informing the user about the
start up process. The application requests a new application session with the AE Services server,
creates a deviceID for the primary extension, sets up a monitor to receive required events and
registers the deviceID along with the telecommuter number. The application now waits for
incoming calls on the primary extension.

When the primary extension is called, an event indicating incoming call is received by both the
extensions; i.e. the dialed extension (which is being handled by the telecommuter sample code
and not the physical primary station) and the telecommuter number. The call can then be
answered at the telecommuter number and appropriate events indicating changes in the call state
will be displayed in the application console. The audio path will be between the calling telephone
and the phone rung by the telecommuter number (unless a feature such as call pickup, bridging
or similar service is utilized).

5. Organization of the Sample Code

5.1. Directory Structure and Contents
The TeleCommuter sample code resides in the TeleCommuter directory. Snapshot of the
directory is as follows:

Figure 3: TeleCommuter Application Directory Structure

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 5 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
The list which follows is a description of the major files in this directory:

• XMLParser.cs - Contains XMLParser class. This class provides the functionality for
handling all XML messages that are exchanged between the application and the AE
Services server. Some methods from this class like StartApplicationSession,
MonitorStart are required for initialization and are used only once. These methods
format the required XML request using XMLFormatter class, then send the request to the
server over a TCP connection and wait for the response from the server. There are two
different ways, synchronous and asynchronous, in which responses are handled by the
XMLParser class. During initialization, after sending the requests, application blocks till a
response is received. These are synchronous responses and ensure that session
initialization is done correctly before application proceeds. However, after initialization,
all the responses and events are received asynchronously. These are collected using a
separate thread. There are two methods which start a new working thread. These are
StartAutoKeepAlive, which starts a thread for periodically sending keep alive request
and Run()which starts a thread for receiving all the asynchronous events. On receiving
these events, this function calls the event handler and passes the control to the
TeleCommuter class for handling the event

• XMLHandler.cs - Contains the XMLHandler class. This class provides the functionality
for sending and reading the XML messages between the application and the AE Services
server. It accomplishes it with the help of the two functions viz. sendrequest() and
readXMLMessage(). The readXMLMessage()function is used to read the various
responses received from the AE Services server and parse the XML data contained in it.
The XML message is then used for further processing by the XMLParser class. The
sendrequest() constructs the XML message according to CSTA-ECMA 323 standard
format and sends over the writer stream.

• XMLFormatter.cs - Contains the XMLFormatter class. Each function from this class
provides the exact XML request required by the application to communicate with the AE
Services server. These methods take parameters associated with the request and format
the XML request string. This class is used by XMLParser class for formatting various
XML requests.

• SocketHandler.cs - Contains the SocketHandler class. This class creates TCP socket
and attaches stream reader and writer to it. This reader and writer will be used to read
response data and write request data respectively. The openSocket() function gets
invoked in the XMLParser class when the application starts. For non-secure port this
class uses a NetowrkStream object. In case of secure port, SslStream object is used and
the application is authenticated with the server.

• EventArgs.cs - Contains the list of classes which are used for passing event information
when an event handler is invoked. There is one class for each event handled by the
application e.g. LampModeEventArgs class holds the information for LampModeEvent.

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 6 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
 These classes take in XML response for the event, parse XML content, extract the event
information and populate the respective member variables.

• TeleCommuter.cs - Contains TeleCommuter class which represents the main

application and implements the functionality starting from initiating a new application
session to performing the clean up. This class uses XMLParser for performing all XML
related information exchange with the AE Services server and also provides the event
handler routines such as OnLampModeEventHandler, OnDisplayUpdatedHandler,
OnRingerStatusHandler. Developers can write their telephony logic in these handlers.
Currently the application just displays event information in all these handlers just to
indicate that the events are received by the application.

5.2. Logical Flow

The basic flow of any DMCC based application can be enumerated as:
• Setup or Initialization
• Telephony logic
• Session recovery or maintenance
• Application cleanup

Like all XML API based applications, the TeleCommuter application follows this basic flow.

5.2.1. Initialization
When the application starts, TeleCommuter class initiates a new instance of XMLParser class
and invokes functions from this class to setup an application session. It calls Start function for
this and here is the snapshot of the code:

public void Start()

{
xmlParser = new XMLParser();

Console.WriteLine("To EXIT the application, type a character on

the console.\n");

AddEventHandlers();
string host = (string)propertyList[DMCC_SERVER_IP];
int port = Int32.Parse((string)propertyList[DMCC_SERVER_PORT]);
string username = (string)propertyList[DMCC_USERNAME];
string password = (string)propertyList[DMCC_PASSWORD];
string protocol_version = (string)propertyList[DMCC_PROTOCOL_VERSION];
string secure = (string)propertyList[DMCC_SECURE];

if (!(port == 4722 && secure.Equals("true")) || (port == 4721 &&

secure.Equals("false")))
{
Console.WriteLine("Improper settings for server port and secure
fields\n"
+ "Please check port is 4722 for secured connectiion
and 4721 for non-secured connection");

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 7 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
 if (Console.ReadKey() != null)
Environment.Exit(1);
}

/* Establish an application session between the application and the AE

* server
* Note:
* This application uses only one device and one session.
* An application can handle multiple devices with a single
* application session and a single socket can be used for
* sending all related requests.
*/
SessionID = xmlParser.StartApplicationSession(host, port,
username, password, protocol_version);

if (SessionID == null)
{
return;
}

Console.WriteLine("Application Session started. SessionID = {0}",

SessionID);

/* Obtain a device identifier for each station/device or extension that

* the application needs to work with. This application works with only
* one device.
*/
DeviceID = xmlParser.GetDeviceID((string)propertyList[CALL_SERVER_IP],
(string)propertyList[EXTENSION]);
if (DeviceID == null)
{
return;
}

Console.WriteLine("Device created.");

// Start device monitor

MonitorRefID = xmlParser.MonitorStart(DeviceID);

if (MonitorRefID == null)
{
return;
}

Console.WriteLine("Registered for monitoring services.");

/* Register the device

* The application registers the device with exclusive control
* and by specifying Telecommuter media mode by providing the
* Telecommuter number.
*/

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 8 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
 if (xmlParser.RegisterTerminal(DeviceID,
(string)propertyList[EXT_PASSWORD],
(string)propertyList[TELECOMM_NUMBER])
== false)
{
return;
}

Console.WriteLine("Terminal Registered.");

/* Start sending keep alive messages to keep the session active.

* This application sends one request every 55 sec.
*/
xmlParser.StartAutoKeepAlive(SessionID, 55000);

Console.WriteLine("Session Keep Alive started.");

Console.WriteLine("The application has set up {0} as the
Telecommuter number for the extension {1}",
(string)propertyList[TELECOMM_NUMBER],
(string)propertyList[EXTENSION]);

Run();
}

XMLFormatter class provides the XML request format for all XML requests used by this
application. Here is the snapshot for the RegisterTerminalRequest:

public static string FormatRegisterTerminalDeviceRequest(string device_id,

string password, string
telecommuter_number)
{
string getRegisterTerminalRequest =
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<RegisterTerminalRequest xmlns=\"http://www.avaya.com/csta\">" +
"<device typeOfNumber=\"other\" mediaClass=\"\" " +
"bitRate=\"constant\">" + device_id + "</device>" +
"<loginInfo>" +
"<forceLogin>true</forceLogin>" +
"<sharedControl>false</sharedControl>" +
"<password>" + password + "</password>" +
"<telecommuterExtension>" + telecommuter_number +
"</telecommuterExtension>" +
"</loginInfo>" +
"</RegisterTerminalRequest>";

return getRegisterTerminalRequest;
}

Note that as a part of the RegisterTerminalRequest, the application provides the telecommuter
number.

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 9 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
5.2.2. Telephony Logic
When an extension gets called, three generic changes occur at the physical device:

1) The phone rings (RingerStatusEvent).

2) A green call appearance lamp flashes. (LampModeEvent)
3) The display changes to show caller information. (DisplayUpdatedEvent)

The TeleCommuter application is sent these events by the AE Services server based on the
monitor that is has requested on the device and displays information regarding these events on
the console, as and when it receives them. Developers can enhance the routine handlers to
implement their own telephony logic based on the application requirements.

The application gets to know details about the events received by looking up the event structure
and the following section gives details about two sample events.

The ring pattern is supplied in the “RingerStatusEvent” event structure. Since this message is
an asynchronous message sent by AE Services server, there is a MonitorCrossRefID which is
used for correlating the message to the MonitorStart.

Here is a snapshot of RingerStatusEvent routine:

if ((RingPattern)args.RingPattern == RingPattern.RingerOff)
{
Console.WriteLine("The ringer is off.");
}
else
{
/* There are a number of different ringing patterns that can indicate
* that a call has been offered to the destination staition.
* Print out the pattern and expect that an interested user
* will investigate more throughly.
*/
Console.WriteLine("The ringer is ringing in pattern:" +
(RingPattern)args.RingPattern);
}

The identifier of the lamp that has changed, the lamp’s color and the lamp’s mode is supplied in
the LampModeEvent event structure. By detecting the state of the lamp with the lamp mode
constants, the application infers the call status. For example, if the lamp mode constant is “7”
and the lamp color is “3”, it implies a green flashing lamp and hence the call status is an
incoming call.

Here is snapshot from LampModeEvent handler routine:

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 10 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
if (args.LampMode == LampMode.Flashing ) // Incoming call
{
/* A flashing green call appearance lamp indicates that there is an
* incoming call.
*/
Console.WriteLine("Lamp " + args.Lamp + " is now flashing.");
Console.WriteLine("Incoming call received");
}
else if (args.LampMode == LampMode.Off) // Call disconnected
{
Console.WriteLine("Lamp " + args.Lamp + " is now off.");
}
else if (args.LampMode == LampMode.Steady) // Call connected
{
/* A steady green call appearance lamp indicates that the call is now
* established.
*/
Console.WriteLine("Lamp " + args.Lamp + " is now on.");
Console.WriteLine("The call has been answered");
}

The display contents are supplied in the “DisplayUpdatedEvent” event structure. This
application currently displays contents on the screen. Here is a snapshot for
DisplayUpdatedEvent handler routine.

if(args.Message != null)
Console.WriteLine("Display update event: " + args.Message);

5.2.3. Session Maintenance

There are two aspects to Session Maintenance. The first is maintaining a keep-alive handshake
between the application and the AE Services server. The second is session recovery in the event
of expiry of the session keep-alive, or loss of the socket connectivity. The telecommuter handles
the keep-alive handshake, but includes no logic for session recovery. Refer to the “Recovery”
section in the Avaya Application Enablement Services Device, Media and Call Control API XML
Programmer Guide R3.1.1 Document ID 02-300358, Issue 2.2, May 2006 for details regarding
session recovery.

When a StartApplicationRequest is sent to the AE Services server, a session duration interval is

communicated to the server. Server then keeps the session active for this period, even if there is
no activity on the connection.

When initialization is complete and application is waiting for events, the application will not
send any messages to the AE Services server (by its design – while other applications may
intermittently send messages they too need to implement a keep-alive handshake). Unless the
application sends keep alive messages, the AE Services server will expire the session at the end
of the session duration interval. To avoid this condition, the application must to send keep-alive
signals to the server at periodic intervals to keep the application session active.

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 11 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
The telecommuter application calls the StartAutoKeepAlive method which starts a separate
thread. This thread then sends keep alive signal to the server every one minute. Though our
application session duration timer is set to 180 seconds, its advisable to send across keep alive
messages once every 55 seconds so that even if there is a remote chance of two successive keep
alive messages getting lost, the session still remains active.

Here is snapshot of the code that maintains active sessions:

/* This function starts a separate thread for sending

* "ResetApplicationSessionTimer" requests
*/
public void StartAutoKeepAlive(string session_id, int duration)
{
if (SessionKeepAliveTimer == null)
{
SessionKeepAliveTimer = new Timer(new
TimerCallback(SendSessionKeepAlive), session_id, duration,
duration);
}
else
{
SessionKeepAliveTimer.Change(duration, duration);
}
}

private void SendSessionKeepAlive(Object stateInfo)

{
Console.WriteLine("\nSending session keep alive request at {0}",
DateTime.Now.TimeOfDay);
sendRequest(XMLFormatter.FormatSessionKeepAlive((string)stateInfo));
}

5.2.4. Application Cleanup

When the application exits, either by user’s choice or in case of an exception, it is always
advisable to clean up the activities that it performed during the start-up, in the reverse order
This mainly involves stopping the thread that the application created for sending keep alive
messages, un-registering the terminal, stopping monitors and finally closing application session.

Here is the snap shot for the clean up routine:

public void CleanUp()

{
if (SessionID != null)
{
// Stop the Auto keep alive signal
xmlParser.StopAutoKeepAlive();

// Unregister the device with the AE Services server

if (DeviceID != null)
xmlParser.UnregisterTerminal(DeviceID);

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 12 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
 // Stop the device monitor
if (MonitorRefID != null)
{
xmlParser.MonitorStop(MonitorRefID);
MonitorRefID = null;
}

// Release the device

if (DeviceID != null)
{
xmlParser.ReleaseDeviceID(DeviceID);
DeviceID = null;
}

// Stop application session

xmlParser.StopApplicationSession(SessionID);
SessionID = null;
}
}

6. Support
Available at http://www.avaya.com/support

7. Conclusion
The TeleCommuter application is a Device, Media and Call Control (DMCC) sample application
which demonstrates usage of DMCC XML APIs for performing various Telephony services. An
overall view of the sample code as well as usage instructions has been presented in this
document.

8. Additional References
8.1. Documentation
For additional information regarding DMCC XML API programming, refer to the following
document:
• Avaya Application Enablement Services Device, Media and Call Control API XML
Programmer Guide R3.1.1 Document ID 02-300358, Issue 2.2, May 2006, available at
http://www.avaya.com/devconnect or http://www.avaya.com/support

For additional information regarding administration of Application Enablement Services refer to:
• Avaya MultiVantage Application Enablement Services Administration and Maintenance
Guide Release 3.1.2, Document ID 02-300357, Issue 4, September 2006, available at
http://www.avaya.com/devconnect or http://www.avaya.com/support
• Avaya MultiVantage Application Enablement Services Administration and Maintenance
Guide Release 4.0, Document ID 02-300357, Issue 6, February 2007, available at
http://www.avaya.com/devconnect or http://www.avaya.com/support

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 13 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
8.2. Glossary

Technical Term Definition as it pertains to this document

AE Services Application Enablement Services

CM Communication Manager

CSTA Computer Supported Telecommunications Applications

DMCC Device Media and Call Control

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 14 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter
©2008 Avaya Inc. All Rights Reserved.
Avaya and the Avaya Logo are trademarks of Avaya Inc. All trademarks identified by ® and ™
are registered trademarks or trademarks, respectively, of Avaya Inc. All other trademarks are the
property of their respective owners. The information provided in these Application Notes is
subject to change without notice. The configurations, technical data, and recommendations
provided in these Application Notes are believed to be accurate and dependable, but are
presented without express or implied warranty. Users are responsible for their application of any
products specified in these Application Notes.

Please e-mail any questions or comments pertaining to these Application Notes along with the
full title name and filename, located in the lower right corner, directly to the Avaya DevConnect
Program at devconnect@avaya.com.

SK; Reviewed: Solution & Interoperability Test Lab Application Notes 15 of 15

SPOC 1/2/2008 ©2008 Avaya Inc. All Rights Reserved. Telecommuter