Wednesday, January 25, 2012

Integrating Instant Alert Manager for OCS and Lync with Email

Instant Alert Manager for OCS and Lync provides a server based alerting engine and notification system for Microsoft Lync and Microsoft OCS.  Our application is capable of dispatching a series of instant messages (IMs) to users - typically this is used to notify people who are running either Microsoft Lync or Microsoft OCS of some event (i.e. a system outage, the status of a help request, etc.). 

We have developed Alert Manager with an extensible API - with the idea that other systems might want to dispatch messages using our framework.  Recently, a prospective customer requested the ability to integrate an email notification system with our IM dispatching system.  At a high level, our application will monitor a mail box and will immediately dispatch the messages to a set of online users running OCS or Lync - as the messages are received by the mail system.  The idea is provide a single inbound notification bridge, via an email account, and then immediately alert the correct set of people using IM.

So, several days after the initial request, we have developed a new listening service that integrates our alerting system with a POP3 mail account.  This new listening service will monitor a mail account and immediately dispatch inbound mail messages to an appropriate group of users who are online in either Microsoft OCS or Microsoft Lync 2010.

Here is a screen shot of the mail account - with a message pending:

This is a sample message - where the message is currently encoded as XML.

After the email is received, our new email listening service parses the message and dispatches the request to Alert Manager - where it is placed in queue for immediate delivery.

As soon as the message is placed into the dispatching queue, it is staged for delivery - awareness for the recipient(s) is verified, and then the message is delivered using either Microsoft Lync 2010 or Microsoft OCS.

Setting up a TrustedApplication for Lync 2010

  1. Open Lync Management Shell
  2. Create TrustedApplicationPool
    1. Run Get-CsSite.  Note SiteId
    2. Run Get-CsService –Registrar.  Note Identity:Registrar:
    3. Run New-CsTrustedApplicationPool –Identity [LyncServer] –Registrar [Registrar] –Site [SiteId]
    4. Run Enable-CsTopology
  3. Run New-CsTrustedApplication – Save these settings, as you will need them to configure BLM
    1. ApplicationId: Supply a descriptive name here
    2. TrustedApplicationPoolFqdn: The fully-qualified domain name of the trusted application pool created in the previous step.  Can be found by running Get-CsTrustedApplicationPool
    3. Port: Select a port to access the trusted application.  Should be >1024.  Be sure that the port is open on your firewall.
    4. Run Enable-CsTopology to commit the changes
    5. Run “Get-CsTrustedApplication > [some file name].txt”  This will save the information you will need to configure BuddyList Migrator to a text file, as it is very difficult to copy from the Management Shell.
  4.    Setup TrustedApplicationEndpoint
    1.   Run New-CsTrustedApplicationEnpdoint –ApplicationID urn:application:yourAppname –TrustedApplicationPoolFqdn appPoolFQDN –SipAddress sip:name@domain –DisplayName “Name”
  5. Setup Certificates for the machine on which you will install BuddyList Migrator.  If installing to the Lync Server, this can be ignored
    1. Run mmc
    2. Add the Certificates snap-in.  Select “Local Computer”
    3. Go to Personal->Certifcates
    4. Action->All Tasks->Request New Certificate
    5. Continue through the Wizard.  Select “Computer” for the type of certificate.

Monday, January 2, 2012

Checking the presence of a user (or queue) in Sametime using JavaScript

Recently, while tracking down a potential bug in one of our Queue Manager deployments, it was decided that we needed a way to check the presence of a logged in user through the Sametime Connect Web API. For instance, while on a website an end user clicks on a ‘Live Chat’ link, they are logged into a Sametime client on their computer, so we use JavaScript to talk to that Sametime client to get a bit more information. We check with the Sametime client to see if our ‘Live Chat’ support queue (user) is online, if the Sametime client can see that user online, we will start the conversation through their installed Sametime client, if it can’t, we will launch our branded web client so the conversation can still happen.

After reading through the Sametime SDK/Connect Web API documentation fairly extensively, I determined that there was no real official or right way of doing the above on the client side with JavaScript, so we’d have to improvise a bit, piecing different parts of the API together to get it to do what we wanted. Let’s look at some code.

The first thing we needed to do was wire up some Sametime livenames. According to the documentation, livenames are a UI representation of a contact; they display the online status using a status icon, and bold coloring of the contact’s display name. To do this, we include the getStatus.js JavaScript file; this file exists inside the user’s local Sametime client, and includes a lot of utility functions to deal with livenames/presence.

<script type="text/javascript" src="http://localhost:59449/stwebapi/getStatus.js"></script>

The Sametime client listens on http://localhost:59449, so if the user currently has Sametime running, these files will exist for us to include in our HTML/JS pages.

The next step is to add some HTML links for the users which we’ll be checking presence on. For our use case, we didn’t want these links to appear on the page, we just wanted our JavaScript and the getStatus.js file provided to utilize them as needed, so I added a style=”display: none;” tag to the link to hide it. These links need to have the class=”awareness”, as that is how the getStatus.js file will pick them up when the page loads.

<a class="awareness" userId="System%20p" style="display: none;">Resolving contact, please wait....</a><br />
<a class="awareness" userId="zac" style="display: none;">Resolving contact, please wait....</a><br />
<a class="awareness" userId="test user" style="display: none;">Resolving contact, please wait....</a><br />

The userId=” {username} ” denotes the user which we are tracking presence of. In the example, we have System p (one of our test support queues), zac (my internal username), and test user (a non-existent user which will show up as offline).

After saving the file, we can access the HTML page we created. It will appear blank, but if we have Sametime running, we should be able to see some things under the covers in the browser. Using Firebug, we can see that the getStatus.js file has built up an array, called sametime_livenames, where it has stored a bunch of values about the users which we added to the page.

Now that we have these populated objects, let’s see how we can manipulate them to get a presence. In this example, we have three users; two (System p, zac) of them online, 1 (test user) that is offline. Now that we have sametime_livenames built up, we need to find the user’s presence. This took some serious digging on my part to find the differences, and good ways of doing this. I eventually settled on the fact that if the user is online, a “_properties” variable will be defined, if the user is offline, this variable doesn’t exist. Below is the Firebug output that lead me to this while testing.

sametime_livenames[0]._properties represents the first user we are tracking, System p, which is logged in.
sametime_livenames[2]._properties represents the last user we are tracking, test user, which is not logged in, and returns undefined.

So now we know what we are looking for to detect presence, but we need this to happen automatically when a user clicks a link, and have some custom logic to determine which chat client to launch, so let’s build our function to do this.

We will be using object literal notation since we don’t want our JavaScript to interfere with any other libraries the site we post to may be using.
// Detect presence of watched Sametime users
Instant.detectPresenceOfUser = function (stid) {
    user = stid.toLowerCase(); // Convert stid variable to lower case for switch statement

    switch (user) {
        // Check if STID is System p
        case 'system p':
            livename = sametime_livenames[0];

            // Check if user is logged in
            if (typeof livename._properties === "undefined") {
                return false;
            } else {
                return true;
        // Check if STID is zac
        case 'zac':
            livename = sametime_livenames[1];

            // Check if user is logged in
            if (typeof livename._properties === "undefined") {
                return false;
            } else {
                return true;
        // Check if STID is test user
        case 'test user':
            livename = sametime_livenames[2];

            // Check if user is logged in
            if (typeof livename._properties === "undefined") {
                return false;
            } else {
                return true;

The Instant.detectPresenceOfUser function is where we will return a true/false based on whether or not the user that we pass into the function is online or offline. The user gets passed in (ex. Instant.detectPresenceOfUser(“System p”);), the function converts it all to lower-case, and then passes it through the switch which determines what user we are looking for the presence of. Next, it checks that _properties variable, if it exists, the user is online, and the function returns true, otherwise, it returns false as it can’t see the user.

This gets bundled into our Instant.startChat function, so that we can have some logic about how we want to start the conversation. Now, if the website can’t see the user when a chat is initialized, it will launch the web client. In our case, the user may not be offline, just the site can’t see them, and the web client will bridge that gap.

Our full file of JavaScript utilities can be seen below. This includes checking whether the user is running Sametime, the presence detection function, and the function that can start a chat conversation from the web using Sametime.