Automatic Call Distributor is an example collaboration-enabled and communication-enabled service that illustrates how developers can take advantage of multi-modal, multi-party communications and of Enhanced Presence awareness capabilities in the middle-tier to innovate and improve the way information workers communicate with automated systems.

This sample application is modeled after an automated technical support system (Helpdesk). It routes incoming audio and Instant Messaging calls from an information worker who needs technical assistance to agents selected by the system, based on the skills requested by the caller, and on the availability and willingness of the agents to communicate.


The people who interact with Automatic Call Distributor have the following roles:

  • Callersusing Microsoft Office Communicator 2007 R2—information workers who are in the same enterprise as the Helpdesk application or in a federated organization.

  • Agentsusing Office Communicator 2007 R2—information workers responsible for the technical assistance of employees.

  • Expertsusing Office Communicator 2007 R2—information workers who are not full-time agents but who have expertise in a particular domain, and who can be sought out by an agent who needs in-depth assistance while serving a customer.

  • Helpdesk administrator—the administrator responsible for installing and managing the Helpdesk application.

User Experience

When a user calls Helpdesk for help with a problem, Automatic Call Distributor greets the caller and gathers information about the nature of the problem. The application then selects an agent whose skills match those needed by the caller, and connects the caller to the agent. The following sections describe the user’s experience in more detail.

Data Collection

A caller contacts the Helpdesk application by selecting the Helpdesk contact in Office Communicator 2007 R2 through Instant Messaging or voice. The Helpdesk application greets and then interviews the caller to determine the technical skills required for this call.

Agent Matching

After the technical skills related to the caller’s problem are identified, the application places the caller on hold, and waits for an agent with matching skills to become available. If no agent becomes available in a predetermined time, the session ends. Two callers who request the same skills are served in the order that their initial calls were received by the application. A caller who uses voice to contact the Helpdesk application will hear music while being on hold.

Offering a Call to an Agent

After a matching agent is found, the application offers the call to the agent by establishing an Instant Messaging back channel while impersonating the caller’s identity. The application then awaits confirmation that the agent is willing to answer the call.

If the agent declines the offer, or does not answer within 30 seconds, the application tears down the Instant Messaging back channel. The application then makes a note of this agent so that the same call is not referred to this agent at a later time. Meanwhile, the application looks for another available agent whose skills match those needed by the caller.

If the agent accepts the call, the application escalates the peer-to-peer Instant Messaging back channel to a conference. Escalating the call to a conference serves multiple purposes: for example, it allows the agent to invite an expert to help assist the caller. Although not included in the sample application, the use of a conference also permits an application to record the interactions between the caller and the agent(s) or to let a supervisor silently monitor or coach the agents. It is important to note that the caller’s user experience throughout a given session is that of a two-party conversation with Helpdesk. The caller does not see the SIP contact information of the agent(s) serving her during any of her interactions with the automatic call distributor delegates (Interactive Voice Response server, Instant Messaging Bot, Music on Hold server, and agents).

Connecting to an Agent

After being connected to the customer, an agent can add a modality such as video or desktop sharing to better assist the caller. The agent can also use a set of built-in Instant Messaging commands exposed on the back channel to get the help of an expert based on skills, terminate the conference, or communicate with other agents while excluding the caller (a side-bar conversation).

Supported Modalities

  • Audio/video (video signaling only).

  • Instant Messaging.

  • Desktop sharing (viewing only) through UCMA 2.0 Core SDK modality-based extensibility. The caller may not share control in this sample with Office Communicator 2007 R2.

Recommended Operating Systems

  • Microsoft Windows Server 2003 R2 64-Bit Editions

  • Microsoft Windows Server 2008 64-Bit Editions

Solution Layout

The application is laid out in one solution file, AutomaticCallDistributor.sln, that has three projects:

  • AutomaticCallDistributor: Contains the automatic call distributor implementation

  • AutomaticCallDistributorExe: Command-line wrapper for the sample

  • AutomaticCallDistributorService: Windows Service

Agent Availability and Willingness to Communicate

The system determines that an agent is available to receive a call based on two main factors:

  1. Enhanced Presence

    An agent must be “available” to be offered a call. Changing the state of an agent to busy or do not disturb makes the agent unavailable to serve a customer.

  2. Willingness to communicate

    An agent must agree to serve a caller at that time to be connected to her by the system. The offer is sent to the agent in an Instant Message.

Any time an agent becomes associated with a session (through a new session or an invite to an existing session), that session is tracked as part of the agent’s status. If the agent leaves the conference associated with that session or the session is terminated, the agent’s status is updated.

High-Level Architecture

The following illustration shows the major architectural components of Automatic Call Distributor. An AcdPlatforminstance can host zero or more AcdPortalinstances, so an AcdPlatform instance can be thought of as logically containing a number of AcdPortalinstances. This relationship is shown in the following illustration by the use of a connector with a diamond-shaped endpoint at end with the containing class. In a similar way, each AcdPortalinstance can host zero or more AcdCustomerSessioninstances. An AcdPlatform instance has a one-to-one relationship with its associated AcdAgentMatchMakerinstance.

Unlike the previously-mentioned relationships, an AcdCustomerSessioninstance uses the AcdAgentMatchMakerinstance, so a different connector end is shown in the illustration.

There is also a one-to-one relationship between a Helpdesk caller and an AcdCustomerSessioninstance, but in the absence of callers, it is possible to have agents without an AcdCustomerSession, and it is also possible to have an AcdCustomerSessionwith no available agents.


The AcdPlatforminstance is unique in the process. It parses the general configuration information (Config.xml file) and constructs the configuration objects used by the other application components.

The AcdPlatformcreates and aggregates one Unified Communications Managed API 2.0 Core SDK CollaborationPlatforminstance used for connection management (listening on a port, connection pooling and throttling, MTLS), trusted GRUU provisioning, and media-based extensibility (for application sharing).

It is also responsible for creating as many AcdPortalinstances as are configured in the config.xml file. The lifetime of the AcdPortalinstances in the application is managed by the AcdPlatform, thus if there are five active portals, shutting down the platform causes it to iterate through each portal and begin the shutdown sequence. The AcdPlatformdoes not complete shutdown until all child portals have completed their shutdowns.

In addition, the AcdPlatformcreates one instance of an AcdAgentMatchMakerand terminates it after shutting down all the portals.

The following example shows AcdPlatformconfiguration (from Config.xml).

Copy Code

  <matchMaker>…</ matchMaker>

UCMA 2.0 Core SDK-specific AcdPlatformsettings:

  • applicationUserAgent

    The string that is used as the Application identifier (a string visible in the SIP User Agent header (network trace)).

  • gruu

    The GRUU that is obtained upon publishing the Active Directory trusted service object that corresponds to the current application instance. The ApplicationProvisioner sample utility can be used to provide the GRUU value. For more information, see “Creating a CollaborationPlatform Instance Using Application Provisioner” in Using ApplicationProvisioner.

  • port

    The listening port value that is specified when creating the Active Directory domain services trusted service object.

  • certificateFriendlyName

    The friendly name of the X.509 certificate issued by a Certificate Authority trusted by Microsoft Office Communications Server 2007 R2.


The AcdPortalcreates and aggregates the application endpoint representing a specific Helpdesk portal. The portal dispatches incoming calls according to whether they are new calls or existing calls that result from a modality addition or self-transfer. Additionally, the portal publishes its Presence as Always Online and exposes a multicast and efficient Music on Hold player shared across all AcdCustomerSessioninstances associated with that portal.

AcdPortalshutdown logic implements drainingof its AcdCustomerSessioninstances. This means that the system is allowed to shut down gracefully after all of the tasks in its AcdCustomerSessioninstances are completed. The portal does not accept new customer calls, but waits until all existing AcdCustomerSessioninstances are terminated before shutting down. While the system is draining, a customer already engaged in communication with Helpdesk can add new modalities or can be self-transferred.

The following example shows AcdPortalconfiguration (from Config.xml).

Copy Code
  <musicOnHoldFilePath>I Ka Barra (Your
  <welcomeMessage>Welcome to the Help
  <holdMessage>Please hold for the next available agent. Your
call will be answered in the order in which it was
  <timeOutNoAgentAvailableMessage>Sorry I could not find an
available agent. Please call
  <imBridgingMessage>You are now
  <finalMessage>Thank you. The helpdesk session is over.
Please call again.</finalMessage> 
  <offerMessage>Hello {0}</offerMessage> 
	<portalSkill name="Operating System" /> 
	<portalSkill name="Program" /> 

UCMA 2.0 Core SDK-specific AcdPortalsettings:

  • uri

    The address of record corresponding to a particular Helpdesk portal configured in an Active Directory Contact object.

  • proxyHost

    The fully qualified domain name of the Hardware Load Balancer fronting a Microsoft Office Communications Server 2007 R2 Enterprise Edition pool or Microsoft Office Communications Server 2007 R2 Standard Edition. The proxy host is also the Registrar of the AcdPortal ApplicationEndpoint.

  • proxyPort

    The listening port value of the proxyHost(usually 5061).

  • musicOnHoldFilePath

    The Music on Hold file location and name (absolute or relative path). The file must have a .WMA extension.

  • welcomeMessage

    The greeting message that is played to the caller when a new call is accepted.

  • holdMessage

    The speech-synthesized prompt that is played at the start of the agent matchmaking phase in a given AcdCustomerSession.

  • timeOutNoAgentAvailableMessage

    The speech-synthesized prompt that is played after the Music on Hold phase times out (when no agent is matched).

  • imBridgingMessage

    The message that is sent to all parties (customer and agents) upon successfully connecting an Instant Message communication between them.

  • finalMessage

    The message that is sent to all parties (customer and agents) upon successfully connecting an Instant Message communication between them.

  • offerMessage

    The first message (toast) sent to an agent candidate to ask for his or her willingness to take a customer call.

  • portalSkill

    A skill label (key) that references a skill that is prompted for during the data collection phase of the portal. It must match the name of a skill managed by the AcdAgentMatchMaker. A portalSkillelement has a nameattribute that is assigned a string that contains the name of the skill.


The AcdCustomerSessionencapsulates the data and operations necessary to connect to an agent including the data collection and hold phases preceding the connection to the agent. It provides media level functionality for conversing with the caller, as well as connecting the caller to the agent conference. After performing Data Collection on the requested skills, the AcdCustomerSessionrequests AcdAgentMatchMakerto locate an available agent with matching skills. After a match is made, the session connects the caller to the agent. The CustomerSessionStatestate changes to ConnectedToAgentand filters special commands sent by agents in Instant Messages. This creates a virtual agent back-channel for agents to execute command functions in the Automatic Call Distributor system. If a command is found, it is interpreted and executed. The following commands are supported:

  • cmd:help

    Display the help message.

  • cmd:escalate

    Ask the system to look for another qualified agent and ask that person to join the conference.

  • cmd:escalate s/skill=value [,s/skill=value]

    Ask the system to look for another qualified agent based on the specified list of skills and ask that person to join the conference.

  • cmd:message

    Send a message to other agents serving a given caller. The message is not visible to the caller.

  • cmd:terminate

    Terminate the customer session.


The AcdAgentMatchMakerpersistently subscribes to the Presence state of all the agents in the system. It also maintains a queue of pending match requests issued by AcdCustomerSessioninstances. While an AcdCustomerSessionexists for each caller, there is only one instance of AcdAgentMatchMaker. For each new match request, the AcdAgentMatchMakerfirst enumerates the list of available agents with matching skills, and returns an instance of an agent that is allocated for an AcdCustomerSessionif a match is made. If no match is found, the request is queued and is honored in the order of its location in the queue, after all prior pending requests for the same skills are satisfied. The pending request queue is scanned each time an agent becomes available through Presence.

The AcdCustomerSessionsequentially iterates by contacting the agent candidates until one indicates a willingness to accept the call. An agent is then returned to the AcdCustomerSessionthat requested the match.

The AcdAgentMatchMakeralso manages the definition of skills and their associated possible values. It reads these values from the configuration file. The following is an example of the syntax of the configuration file.

The following example shows AcdAgentMatchMakerconfiguration (from Config.xml).

Copy Code
	<skill name="Operating System">
	<mainPrompt>What operating system are you using?
Windows, Linux, Mac, or Unix.</mainPrompt> 
	<noRecoPrompt>I'm sorry, I did not understand that.
What operating system are you using? Windows, Linux, Mac, or
	<silencePrompt>Sorry I could not hear you. What
operating system are you using? Windows, Linux, Mac, or
	<skillRecognizedMainPrompt>You said {0} is the
operating system that you need help

		<agentSkill name="Operating
		<agentSkill name="Operating
		<agentSkill name="Program">Word</agentSkill> 

  • proxyPort

    The listening port of the remote next hop proxy (usually the same as the portal). This is where the ApplicationEndpointregisters to get access to the Presence Store.

  • proxyHost

    The fully qualified domain name (FQDN) for the next hop proxy. This is where the ApplicationEndpointregisters to get access to the Presence Store.

  • maxWaitTimeOut

    The maximum duration that a pending match request can stay in the AcdAgentMatchMakerqueue.

  • uri

    The URI entered in the Active Directory domain services contact object assigned to the AcdAgentMatchMaker ApplicationEndpoint.

  • skills

    A collection of one or more skillelements. Each skillelement has a name, a variety of prompts that are played or sent in Instant Messages when the skill is managed by a portal ( mainPrompt, noRecoPrompt, silencePrompt, skillRecognizedMainPrompt), and a skillValuesentry that lists specific skill values in a skillValueelement.

  • agents

    A collection of one or more agentelements. Each agent element has properties that describe him or her, including the agent’s SIP address of record, signInAddress, the agent’s public name, publicName(to prevent the agent’s identity being disclosed to the customer in Instant Messages), the distinguishing color of the agent’s Instant Message text, instantMessageColor, used when exchanging IMs with the customers to improve the user experience. Because multiple agents or experts can serve a customer at the same time, the customer receives Instant Messages from different sources on a two-party Instant Message channel. Color-coding the Instant Message text can help the customer understand the origin of the message. The agentSkillsproperty is a collection of skills possessed by given agent, with one agentSkillelement for each. These skills are used to match an agent to skills requested by a given customer.

General Flow

This section describes the flow of control in the major components of Automatic Call Distributor.


On startup the AcdPlatformcreates and starts a CollaborationPlatforminstance. After the CollaborationPlatformstartup has completed, the AcdPlatformiterates through the list of portals defined in Config.xml. It creates an AcdPortalinstance for each portal entry, and invokes the startup procedure. After all portals have started, the platform startup sequence is complete. On shutdown, the platform iterates through the list of portals, and invokes the shutdown procedure on each instance. After all portals have shut down, the CollaborationPlatformis shut down, and the AcdPlatformshutdown sequence is complete.


On startup each AcdPortalinstance creates an ApplicationEndpointinstance, establishes the endpoint, and publishes its Presence as Always Online (for scalability reasons, this is the only supported middle tier publishing scheme in Office Communications Server 2007 R2). The portal registers for incoming calls. During its lifetime, the portal provides a multicast Music on Hold service to all of its customer sessions that were initiated as audio calls. It also constructs a Workflow Runtime instance that hosts the Skill Gathering (Data Collection) Workflow instance in each AcdCustomerSession. The principal task of the AcdPortalis to dispatch each incoming call appropriately, depending on whether it is a new call, a modality addition, or a self-transfer call.

Upon shutdown, the AcdPortalfirst drains all existing AcdCustomerSessioninstances.


When a call is received, an AcdCustomerSessioninstance is created, and processing for the session begins. The session proceeds through a sequence of states, as shown in the following illustration.

Adding modalities is permitted only in the ConnectedToAgentstate. Attempts to add modalities in other states will be declined.

  • Incoming

    The initial state of the session, in which a call arrives from a caller. The initial call is either an InstantMessagingCallinstance or an AudioVideoCallinstance.

  • CollectingData

    In this state, the system interacts with the caller to determine the agent skills needed to address the caller’s issue by using a dedicated Workflow instance using speech recognition and speech synthesis, as well as text recognition in Instant Messages. The AcdCustomerSessioninstance delegates this operation to a session-specific instance of GatherRequiredSkillsHandler. The system iterates over the list of defined skills, prompting the caller to choose from the configured values for each skill. For example, if the defined skills are “Program” and “Operating System”, the system prompts the user to first choose from the possible programs (Word, PowerPoint, and so on), and then the possible operating systems (Windows, Linux, and so on). After the necessary skill values are identified, this state of the session is complete.

  • AgentMatchMaking

    In this state, the system searches for an available agent with skills that match those identified in the CollectingDatastate, and contacts the agent to determine whether he or she is willing to accept a call. If the agent is unwilling, the next available agent with matching skills is contacted. This continues until a willing agent is found, or until a timer expires, indicating that a match was not made in time. This process involves the AcdAgentMatchMakerto which agent match requests are directed. After an agent match is found, the session is notified and the process of connecting the agent to the caller begins.

  • ConnectingToAgent

    In this state, the call to the agent is escalated to a conference. If the initial call was an InstantMessagingCall, Instant Message escalation to a conference occurs. If the initial call was an AudioVideoCall, it is transferred to the AudioVideoMcu. The caller is then connected to the agent conference in one of two ways, depending on the type of the initial call:

    • If the initial call was by Instant Message, the caller will be connected to the agent conference.

    • If the initial call was an audio call, the caller is connected by self-transferring the initial AudioVideoCall, which causes the caller’s client to make a new call to the Helpdesk application that can be back-to-backed into a conference in the back office.

    If an error occurs while connecting the two parties, the AcdCustomerSessionis terminated.

  • ConnectedToAgent

    In this state, the caller and agent are able to communicate by bridging, in the case of an initial Instant Messaging call, and by direct back-to-back communication, in the case of an initial audio call. The caller and the agent can add modalities in this state. The following situations can occur:

    • The caller adds Instant Messaging (supported).

    • The caller adds audio/video (supported).

    • The caller adds desktop sharing (supported, but sharing control is not supported).

    • The agent adds audio/video (supported only if the initial call was an InstantMessagingCall).

    • The agent adds audio (supported only if the initial call was an AudioVideoCall).

    • The agent adds Instant Messaging (not implemented).

    • The agent adds Application Sharing (not supported).

    Additionally, in this state an agent can request that another agent or expert be added to the conference. In this case, the target agent is identified, and an Instant Message call is initiated to the agent. The AcdAgentMatchMakerprovides the engine to find additional agents to serve a customer. The session then invites the target agent to the conference with the caller and the first agent.

  • Terminating

    In this state session resources are cleaned up. This includes the call from the caller and the call to the agent conference. Depending on the circumstance triggering a transition to the Terminatingstate, a message might be played to the caller or agent(s).

  • Terminated

    The session is now completely cleaned up and shut down. The session cannot be reactivated.


On startup, the match maker registers the ApplicationEndpointagainst the Office Communications Server 2007 R2 pool and then persistently subscribes to the Presence of all agents specified in Config.xml.

AcdAgentMatchMakerdoes not publish its Presence as Always Online. This endpoint is not meant to receive incoming calls or conference invitations.

During its lifetime, the match maker maintains the updated Presence availability of all agents listed in Config.xml, and is responsible for matching an agent to a caller based on the skills requested by callers.