Extending Unified Communications Services of UCMA Bots to PIC Clients: Introduction (Part 1 of 5)

Summary:   Learn how to extend Microsoft Lync Server 2010 supported unified communications services that are provided by a trusted Microsoft Unified Communications Managed API (UCMA) bot application to Public Internet Cloud (PIC) clients. Without the extension, the unified communications services are restricted to a limited number of Microsoft Lync 2010 clients in a single enterprise network domain. This number is derived from the CategorySubscriptions property of the presence policy that is set by a Lync Server 2010 administrator. Here, PIC clients can include Windows Live Messenger, Skype, and Yahoo! Messenger.

Programmatically, you learn how to enable a Lync Server 2010 application by using the Microsoft Lync Server 2010 SIP Application API and UCMA. Lync Server 2010 SIP Application API is used to intercept a presence subscription from a PIC client and UCMA is used to send the requesting PIC client the online status of an active bot.

Applies to:   Microsoft Unified Communications Managed API (UCMA) 3.0 Core SDK | Microsoft Lync Server 2010 SDK

Published:   May 2012 | Provided by:   Kurt De Ding and Ajay Soni, Microsoft | About the Author

Contents

• Introduction

• General Architecture of a SIP Application API Application

• SIP Application Manifest of a Lync Server Application

• MSPL Script of a Lync Server Application

• Managed Component of a Lync Server Application

• Deploying and Running a Lync Server Application

• Next Step

• Additional Resources

  Download code

This is the first in a series of five articles about how to extend the services of a Microsoft Unified Communications Managed API (UCMA) bot application to Public Internet Cloud (PIC) clients by enabling an unlimited number of PIC clients that can subscribe to the presence of the UCMA bot.

• Extending Unified Communications Services of UCMA Bots to PIC Clients: Intercepting Presence Requests (Part 2 of 5)

• Extending Unified Communications Services of UCMA Bots to PIC Clients: Handling SUBSCRIBE Requests (Part 3 of 5)

• Extending Unified Communications Services of UCMA Bots to PIC Clients: Creating Application Project (Part 4 of 5)

• Extending Unified Communications Services of UCMA Bots to PIC Clients: Building and Deploying Application (Part 5 of 5)

Introduction

In a Microsoft Lync Server 2010 deployment, a bot, serving as a middle-tier between Lync Server 2010 and a client, can be created and deployed to provide automated communications services. An example is a bot that functions as a help desk to connect a customer to an appropriate support staff based on the customer’s answers to questions from the bot. Another example is an application that provides news feeds or stock quotes that are based on direct user input. In these scenarios, the bot is a trusted server application that uses Microsoft Unified Communications Managed API (UCMA) and can be added to the contact list of a user.

Once enabled, the bot’s presence can be subscribed to by a Microsoft Lync 2010 client. When the bot is online, a Lync 2010 client can connect to it and interact with it by using instant messaging or voice calling, as long as the bot is voice- and speech-enabled. However, this workflow does not apply to a public-Internet-cloud (PIC) client like Windows Live Messenger. When a PIC client asks the Lync Server 2010 computer for the presence status of a bot, the server returns the Offline or Presence Unknown as the status for the bot. With Windows Live Messenger, this means that the user cannot connect to and communicate with the bot because Windows Live Messenger does not send any messages to an offline endpoint.

To optimize performance and conserve resources, the Lync Server 2010 limits the maximum number of registered subscribers for each presentity. The subscription limitation is specified by the CategorySubscriptions property of the Presence Policy that is configured by a Lync Server 2010 administrator. Currently, the maximum number of category subscriptions is 3000. When each user subscribes to only one presence category, such as the state category, the presentity cannot exceed 3,000 registered subscribers. In practical applications, a useful bot will exceed 3,000 subscribers. Hence, the CategorySubscriptions limitation will prevent all except the first 3,000 users from being included in the bot’s contact list. And, as the result, the bot’s presence will appear offline or unknown to them.

To bypass this limitation, a bot is designated as an automaton when it is registered with Lync Server 2010. An automaton can publish presence state, but does not maintain a contact list. Once enabled, it is expected to be always online, making constant monitoring unnecessary. When Lync 2010 signs in to the Lync Server 2010, it starts a subscription to receive the presence published by the entities in the user’s contact list. If a bot is in the contact list, Lync removes it from the subscription as soon as it receives its presence status. It then caches the obtained presence status and displays it to show the availability of the bot until the Lync 2010 client endpoint is closed. The user is not counted as a registered subscriber of the bot and there is no breach of the CategorySubscriptions limit on the bot. Furthermore, no user is prevented from interacting with the bot because of an unknown presence status that is affected by the category subscription limit.

Unfortunately, a PIC client, such as Windows Live Messenger, may not implement the same logic. When such PIC clients are involved, a bot could be over-subscribed. To prevent a bot from overreaching its category subscription limit, Lync Server 2010 does not enable PIC clients to be added to the bot’s subscriber list and always returns to a PIC client the bot’s presence status as Offline or Presence Unknown. This is problematic for some PIC clients, such as Windows Live Messenger, which does not support sending messages to any endpoint that has the Offline or Presence Unknown status. Thus, the middle-tier service that is provided by a bot cannot be made available to any users who are using only Windows Live Messenger or other PIC clients.

When you must extend a bot’s service across or beyond enterprise network boundaries, the correct presence status of the bot must be returned to a PIC client. One way to do this is to enable a Lync Server 2010 application to maintain the knowledge of the installed bots on the server, intercept incoming subscription requests from a PIC client, and return the online presence status for the bot if the target of the request matches an installed bot. For a subscription request from a non-PIC client, the application has to reroute the request back to the server, which handles the request as usual. This article discusses how to create and deploy such an application.

Programmatically, the proposal involves building a Lync Server 2010 application with the Microsoft Lync Server 2010 SIP Application API. This API supports simple message-processing through scripting using Microsoft SIP Processing Language (MSPL). For more involved message processing, the API allows an application to delegate the event handling to a managed application component using the Microsoft.Rtc.Sip namespace. In practice, a Lync Server 2010 application often involves several other technologies supported in a Lync Server 2010 deployment. These include Unified Communications Managed API (UCMA) and the use of Lync Server Management Shell cmdlets. Before discussing the details of the solution, let us get an overview of the general architecture of a Lync Server 2010 application.

General Architecture of a SIP Application API Application

In general, a Microsoft Lync Server 2010 SIP Application API application is composed of the following components:

• A SIP application manifest declared as an XML document that has an .am file name extension.

• A Microsoft SIP Processing Language (MSPL) script embedded in the application manifest.

• An optional managed code application component invoked by the MSPL script to handle dispatched events.

The Lync Server 2010 roles appear in figure 1. Following the Application Manifest, the Lync Server 2010 computer passes registered SIP messages to the application for the embedded MSPL script to start to process. For unhandled messages, the script reroutes them back to the server. In a script-only application, the script also reroutes the processed message back to the server. When a managed code is involved, the script forwards the message to the managed application component for additional processing. The managed component then communicates the results back to the requesting client through the interactions with the server.

Figure 1. Application architecture

The managed application component can support as many features as the application requires. The messaging functionality is provided by either the Microsoft.Rtc.Sip namespace or the Microsoft.Rtc.Collaboration namespace and its supporting namespaces. The components of the Lync Server 2010 application are discussed in the following sections.

SIP Application Manifest of a Lync Server Application

In addition to specifying the filtered message types and hosting the embedded MSPL script, the Microsoft Lync Server 2010 SIP Application Manifest declares how the SIP application is run and specifies the application’s identity, including its version. The following XML document shows a SIP application manifest for catching the SIP SUBSCRIBE requests in all server roles where registration can run before UserServices.

<?xml version="1.0"?>
<r:applicationManifest
 r:appUri="https://www.microsoft.com/LCS/SDK/Samples/PresenceSubInterceptorForBot"
 xmlns:r="https://schemas.microsoft.com/lcs/2006/05"> <!-- V3.0 application -->
  <r:allowRegistrationBeforeUserServices/>           <!-- Can run before UserServices if applicable -->
  <r:serverFilter roles="ALL"/>                      <!-- All server roles -->
  <r:requestFilter methodNames="SUBSCRIBE"/>
  <r:responseFilter reasonCodes="ALL"/>
  <r:proxyByDefault action="true"/>
  <r:splScript>
    <![CDATA[
// MSPL script goes here. See listing below
    ]]>
  </r:splScript>
</r:applicationManifest>

The appUri attribute of the root element, <applicationManifest>, specifies a HTTP URL that uniquely identifies the SIP application to Lync Server 2010. The namespace attribute specifies the version of the Lync Server 2010 computer on which the application runs. When specified, the <allowRegistrationBeforeUserServices> element indicates that the application can run before UserServices module on the hosted Lync Server 2010 computer. If this is absent, the application will fail when it attempts to run before the UserServices module. The <serverFilter> element is used to declare the role of the Lync Server 2010 computer in which the application can run. In the previous example, the application can run in all Lync Server 2010 roles. The <requestFilter> element specifies the kinds of requests to be passed to the application by the Lync Server 2010 computer. Here, only the SUBSCRIBE requests will be passed into the application. Similarly, the <responseFilter> element specifies which response classes are passed to the application. To ensure that any messages not handled by this application are treated as ordinary, the <proxyByDefault> element is declared with the action attribute set to True. If this is set to False, any unhandled message will be dropped and will not be passed along to any other Lync Server 2010 applications or the server for additional processing. A message that is passed to the application is handled if the Dispatch, ProxyRequest or ProxyResponse, EndFork, or Respond function is called in the embedded MSPL script. Finally, the <splScript> element contains the required MSPL script in which the passed-in SIP message is processed or delegated to the managed component.

MSPL Script of a Lync Server Application

An MSPL script is an ordered collection of statements in Microsoft SIP Processing Language (MSPL). The script is enclosed in a CDATA section inside the <splScript> element of the application manifest. MSPL is designed specifically for filtering, routing, and logging SIP messages. It has a limited set of language primitives, including the built-in constants and variables, and supports a small set of built-in classes and functions. The built-in variables are used to hold the passed-in message and the related transactional context that are passed to the script by the server. The MSPL functions provide most basic functionality for manipulating text, parsing message headers or parameters, creating proxy objects, rerouting messages, and logging diagnostic information. Dispatch is one built-in MSPL function that is used to delegate the message handling to the managed Lync Server 2010 application component. The built-in MSPL classes have corresponding types exposed in the managed Microsoft.Rtc.Sip namespace. For more information about the corresponding types for the MSPL classes, see the next section.

Managed Component of a Lync Server Application

A managed Lync Server 2010 application component is a standard .NET Framework application that uses the Microsoft.Rtc.Sip namespace and other namespaces that support specific application needs. The Microsoft.Rtc.Sip namespace enables the managed application to parse, fork, and proxy SIP messages. Other .NET Framework namespaces can be used to improve message handling or provide other functionalities. For example, Unified Communications Managed API (UCMA) can be included to make the managed Lync Server 2010 application routable with the help of the ApplicationEndpoint type that is exposed in the Microsoft.Rtc.Collaboration namespace. Other namespaces in UCMA can be used to enable page-mode messaging. For example, in the case of handling the presence subscription by a PIC client, the SipPeerToPeerEndpoint type in the Microsoft.Rtc.Signaling namespace is used to return the Online presence status of a bot by sending the PIC clients SIP NOTIFY messages. For more information about how to create a managed Lync Server 2010 application component, see Extending Unified Communications Services of UCMA Bots to PIC Clients: Handling SUBSCRIBE Requests (Part 3 of 5).

Deploying and Running a Lync Server Application

To run a Lync Server 2010 application, the application manifest must be registered with or installed on the Lync Server 2010 computer. This is completed by running the New-CsServerApplication cmdlet. For a script-only Lync Server 2010 application, the registration amounts to loading the application manifest and running the embedded MSPL script. In other words, the application becomes operational when it is registered or when the server restarts. For the non-script-only Lync Server 2010 application, the registration configures the server to accept connections by the managed application, to pass the specified messages to the loaded MSPL script, and to dispatch the filtered messages to the correct managed event handler. An installed Lync Server 2010 application can be inspected by running the Get-CsServerApplication cmdlet, and its registration can be modified by calling Set-CsServerApplication and canceled by calling Remove-CsServerApplication.

If the Lync Server 2010 application has a managed component and the managed component uses an ApplicationEndpoint instance of UCMA, the application must also be enabled to become a trusted application. This activation involves configuring the application as a trusted application in a specified trusted application pool and registering the application endpoint as an Active Directory Contact object with a specified SIP URI. These tasks can be carried out using the Lync Server Management Shell New-CsTrustedApplicationPool, New-CsTrustedApplication and New-CsTrustedApplicationEndpoint cmdlets. For more information, see Extending Unified Communications Services of UCMA Bots to PIC Clients: Building and Deploying Application (Part 5 of 5).

Next Step

The following aspects of creating and deploying the Lync Server 2010 application to handle subscriptions to the presence of a bot by PIC clients are discussed in part 2 through 5.

1. Intercept presence subscription requests from a PIC client. This involves using an MSPL script to catch SIP SUBSCRIBE messages.

2. Process the intercepted subscription requests. This involves using the Microsoft Lync Server Managed API to parse the intercepted message.

3. Determine the presence of bots. This involves using Lync Server Management Shell cmdlets to obtain a list of available bots running on the server.

4. Respond to a PIC client with appropriate presence status of bots. This involves using UCMA 3.0 to send presence status of the bots to a PIC client.

5. Install and run the Lync Server 2010 application on a Lync Server 2010 computer. This involves activating a trusted UCMA server application and registering a Lync Server 2010 application on a Lync Server 2010 computer or pool.

Additional Resources

For more information, see the following resources:

• Microsoft Unified Communications Managed API 3.0 SDK

• Microsoft Lync Server 2010 SDK

About the Author

Kurt De Ding is a Senior Programming Writer in the Microsoft Office Content Publishing (UA) group. Ajay Soni is a Senior Program Manager with Engineering, Community & Online (ECO) of Microsoft Services.