Default routing endpoints in UCMA

UCMA 3.0 introduced the concept of a “default routing endpoint.” To put it very generally, a default routing endpoint is a single application endpoint that receives any messages that have nowhere else to go. I’ll illustrate further in a moment. When I first heard about this new feature, I could not understand what use it could possibly have. Gradually, over a period of months, situations came up where default routing endpoints turned out to be very handy. Since I figure that other folks might have the same initial reaction of complete confusion when hearing about the default routing endpoint feature, I thought I would write up a bit of explanation on this odd but useful creature in the hope that it will help in others’ development efforts.

Message routing and UCMA applications

To start, it’s important to understand how messages get from Lync Server to a UCMA application. The Lync Front End Server acts as both a SIP proxy and a SIP registrar, which means that users, including endpoints created by your application, sign in to the server to start receiving messages. Any user that wants to communicate with another user sends a message to the Front End Server, which routes it to the appropriate place. In most cases, there is only one user logged in on a given machine. With a UCMA application, however, there can be many users logged in at the same location.

You can think of it as an apartment building with one address but separate mailboxes for each tenant. The post office delivers all the letters, and the mailroom staff look at the names or apartment numbers and sort them out. So the messages are all sent to the same IP address and port, and the collaboration platform needs to look at the To header on each message to match it to the right endpoint.

Normally this works fine, as long as the To header contains a valid SIP URI and the application has an endpoint signed in that matches that SIP URI. If the SIP URI doesn’t match an endpoint, though, or that endpoint is not signed in, UCMA effectively marks it “return to sender.”

The default routing endpoint feature allows you to designate a single ApplicationEndpoint instance (UserEndpoints need not apply) to receive all of these messages that can’t be routed normally to any other active endpoint.

Why?

This is the part that baffled me at first with this feature. I could understand the idea, but couldn’t think of any applications for it. As it turns out, though, there are quite a few.

First of all, if you have multiple application endpoints running on a single server, you can use a default routing endpoint to handle incoming messages for an application that is down for maintenance. You can play an explanatory message, transfer the call elsewhere, or whatever. This is simple to do, but it is only the beginning of what you can do with default routing endpoints.

Another thing you can do is handle all messages (calls, IMs, etc.) that are sent to the GRUU that belongs to the trusted application. The GRUU, or Globally Routable User-Agent URI, is a SIP URI that uniquely identifies the endpoint of your trusted application; unlike a regular SIP URI, it is tied to a specific server and can’t be used from multiple locations. You can create a number of different SIP URIs for an application (by creating trusted application endpoints in PowerShell) and then instead of establishing multiple endpoints, you can establish a single one as a default routing endpoint and it will receive calls for all the others tied to the same application. It will even receive calls sent directly to the GRUU as the To URI. It’s like you make up a bunch of fake box numbers or apartment numbers for your house address, but the mail all comes to your one mailbox.

Also, you can use a default routing endpoint in conjunction with Microsoft SIP Processing Language (MSPL) and other techniques to change the normal routing behaviour in Lync Server. As an example, with MSPL you could reroute all direct incoming calls for customer service employees to a server which houses a UCMA application. The default routing endpoint would pick up all the messages, even though the To address doesn’t match, and could conference in a supervisor for quality control or training along with the person who was originally dialed. Keeping to my postal analogy, this would be a bit like a customs facility, or a mail forwarding service: it opens all the mail, regardless of whom it’s addressed to, and does some things with it. With some of the mail, it then packs it back up and sends it along using the original address on the envelope.

How to use it

To designate an ApplicationEndpoint as a default routing endpoint, set the IsDefaultRoutingEndpoint property on the ApplicationEndpointSettings object to true:

ApplicationEndpointSettings settings = new ApplicationEndpointSettings(_ownerUri, _proxyServerFqdn, 5061);

settings.IsDefaultRoutingEndpoint = true;

ApplicationEndpoint endpoint = new ApplicationEndpoint(_collabPlatform, settings);

Once the endpoint is established, and you’ve registered an event handler to receive incoming calls, it will receive all incoming calls (AudioVideoCall, InstantMessagingCall, etc.) regardless of the SIP URI in the To header. As long as the message comes to the application’s listening port, the default routing endpoint will pick it up.

In future posts, I’ll explain more about how you can combine default routing endpoints with MSPL scripting to do some interesting things with message routing.

As always, feel free to email me if you have questions, or if there’s something else you’d like to see me write about!