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.

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.

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).

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).

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
<platform> <applicationUserAgent>ACDSampleApplication</applicationUserAgent> <gruu>sip:myMachine.mySubDomain.contoso.com@contoso.com;gruu;opaque=srvr:ACD:2M0lw60eEkyCKNuaSGvJjgAA</gruu> <port>9001</port> <certificateFriendlyName>myCert</certificateFriendlyName> <matchMaker>…</ matchMaker> <portals>…</portals> </platform>

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

<portal> <uri>sip:helpdesk@contoso.com</uri> <proxyHost>myOCS.contoso.com</proxyHost> <proxyPort>5061</proxyPort> <musicOnHoldFilePath>I Ka Barra (Your Work).wma</musicOnHoldFilePath> <welcomeMessage>Welcome to the Help Desk</welcomeMessage> <holdMessage>Please hold for the next available agent. Your call will be answered in the order in which it was received.</holdMessage> <timeOutNoAgentAvailableMessage>Sorry I could not find an available agent. Please call again.</timeOutNoAgentAvailableMessage> <imBridgingMessage>You are now connected.</imBridgingMessage> <finalMessage>Thank you. The helpdesk session is over. Please call again.</finalMessage> <offerMessage>Hello {0}</offerMessage> <portalSkills> <portalSkill name="Operating System" /> <portalSkill name="Program" /> </portalSkills> </portal>

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

<matchMaker> <proxyPort>5061</proxyPort> <proxyHost>myOCS.contoso.com</proxyHost> <maxWaitTimeOut>600</maxWaitTimeOut> <uri>sip:system@contoso.com</uri> <skills> <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 Unix</noRecoPrompt> <silencePrompt>Sorry I could not hear you. What operating system are you using? Windows, Linux, Mac, or Unix.</silencePrompt> <skillRecognizedMainPrompt>You said {0} is the operating system that you need help with.</skillRecognizedMainPrompt> <skillValues> <skillValue>Windows</skillValue> <skillValue>Linux</skillValue> <skillValue>Mac</skillValue> <skillValue>Unix</skillValue> </skillValues> </skill> </skills> <agents> <agent> <signInAddress>sip:acdAgent1@contoso.com</signInAddress> <publicName>Agent1</publicName> <instantMessageColor>red</instantMessageColor> <agentSkills> <agentSkill name="Operating System">Windows</agentSkill> <agentSkill name="Operating System">Linux</agentSkill> <agentSkill name="Program">Word</agentSkill> <agentSkill name="Program">Powerpoint</agentSkill> </agentSkills> </agent> </agents> </matchMaker>

• 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.
  
  

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.

Note:
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.

Note:
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.