Integrate Microsoft Lync into a ASP.NET Web Application

Microsoft Lync (formerly known as Microsoft Office Communicator) as a instant messaging client that’s mostly used in a corporate environment as a replacement for Windows Messenger. It is possible to visualize the Lync status of a person (online, offline, busy, away, …) in a web application. This is already supported by default in Sharepoint, but it’s also possible to implement this feature in a custom web application.

The screenshot below shows you an example of Lync integrated into a web application that uses icons to display the current status of a person.

There are some requirements you need to fulfill to make this work.

• Lync must be installed on the client computer. This means that this functionality will probably only work on web applications on the intranet.
• It will only works on Internet Explorer. (Lync uses an ActiveX component to communicate with the browser)

The ActiveX component “Name.NameCtrl.1″ is located in the following library:

C:\Program Files\MicrosoftOffice\Office14\NAME.dll. and you can use this component in javascript.

if ($.browser.msie) {
    try {
        nameCtrl = new ActiveXObject('Name.NameCtrl.1');

        if (nameCtrl && nameCtrl.PresenceEnabled) {
            nameCtrl.OnStatusChange = onStatusChange;
        }
    }
    catch (e) {
        debug("could not load ActiveXObject('Name.NameCtrl.1')");
    }
}

In the JavaScript code above we first check if the user agent (browser) is Internet Explorer using jQuery.
We create an ActiveX object using the name of the ActiveXComponent and we bind the OnStatusChange event to an event handler..

function onStatusChange(name, status, id)
{
  ...
}

The onStatusChange event handler is displayed in the code above. This event gets triggered when the status of a contact changes.

The event has 3 parameters:

• name: the “sign-in name” of the contact (mostly the corporate email address)
• status: a code that describes a status.
• Online = 0
• Online (Out of Office) = 11
• Offline = 1
• Offline (Out of Office) = 12
• Away = 2
• Away (Out of Office) = 13
• Busy = 3
• Busy (Out of Office) = 14
• Be right back = 4
• On the phone = 5
• Out to lunch = 6
• Do not distrub = 9
• Do not distrub (Out of Office) = 15
• Idle = 16
• Idle (Out of office) = 17
• Blocked = 18
• Idle-Busy = 19
• Idle-Busy (Out of Office) = 20
• id: the id of the container element that contains the element that we need to update (in our case an <img> element).

There are 3 other functions that are pretty important. One function that allows you to retrieve the status of a contact and the other 2 functions are used to show or hide the Lync specific context menu called on-object UI.

//retrieve contact status
nameCtrl.GetStatus(bstrName, bstrID)

//show and hide on-object UI
nameCtrl.ShowOOUI(bstrName, iInputType, xLeft, yTop);
nameCtrl.HideOOUI();

The GetStatus method retrieves the current status of a contact and has 2 parameters:

• bstrName: the “sign-in name” of the contact (mostly the corporate email address)
• bstrID:
  the id of the container element that contains the element that we need to update (in our case an <img> element).

The on-object UI is displayed on the following screenshot:

The ShowOOUI method displays the on-object UI and has 4 parameters:

• bstrName:
  the “sign-in name” of the contact (mostly the corporate email address)
• iInputType: indicates if the user used the mouse or keyboard to open the on-object UI.
• xLeft: the x-coordinate of the location where the on-object UI has to be displayed starting from the upper left corner of the screen, in pixels.
• yTop:
  the y-coordinate of the location where the on-object UI has to be displayed starting from the upper left corner of the screen, in pixels.

The HideOOUI method hides the on-object UI.

With the OnStatusChange event and the methods GetStatus, ShowOOUI and HideOOUI you’ll have enough tools to integrate Lync into your web application. Below you’ll find a simple example:

<script>
  $(function() {
    //hide the ooui if the user scrolls.
    (window).scroll(function() {
      HideOOUI();
    });

    $('#lyncspan').hover(function() {
        //show ooui on mouseover event
        ShowOOUI();

    }, function() {
        //hide ooui on mouseout event
        HideOOUI();

    });
  });

  var sipUri = "your.contact@your.domain.com";
  var nameCtrl = new ActiveXObject('Name.NameCtrl.1');

  if (nameCtrl.PresenceEnabled)
  {
    nameCtrl.OnStatusChange = onStatusChange;
    nameCtrl.GetStatus(sipUri, "lyncspan");
  }

  function onStatusChange(name, status, id)
  {
    //In a real world application you would display
    //a status icon instead of an alert
    alert(name + ", " + status + ", " + id);
  }

  function ShowOOUI()
  {
    nameCtrl.ShowOOUI(sipUri, 0, 15, 15);
  }

  function HideOOUI()
  {
    nameCtrl.HideOOUI();
  }

</script>
<span id="lyncspan" style="border-style: solid">Your Contact<span>