Microsoft Lync has a rich set of .NET APIs which make it easy to extend the platform and integrate it with other applications. This blog helps explain how to use them.

What is a GRUU?

Posted: November 16th, 2011 | Author: | Filed under: Lync Development, OCS Development | Tags: , | 6 Comments »

The term “GRUU” comes up fairly often in Lync development, and I wanted to use this post to give a brief overview of what it means and why you would use one.

Photo of "GRUUs" -- Photo courtesy of "bungler" on sxc.hu

GRUUs in their natural habitat?

Contrary to what you may have been led to believe, a GRUU is not a large herd animal or a part of the small intestine. The initials actually stand for “Globally Routable User-Agent URI,” which may or may not clarify things for you at all. The definition of a GRUU is explained in an IETF document which you can find here. In a nutshell, a GRUU is a SIP URI which has a few properties:

  • It identifies a specific user agent — in other words, a specific endpoint where a user is signed on.
  • It is (in theory) routable to that specific endpoint from anywhere.
  • It remains valid for a long time.

You’ll find a GRUU in the Contact header on SIP INVITE messages; the GRUU identifies the specific endpoint where the request is coming from. You can identify a GRUU in the wild by looking for a format like the following:

sip:user@domain;opaque=user:epid:UghFocauauCHBHoLhAAA;gruu

Let’s say this user, with the SIP URI sip:user@domain, is logged into three devices. If you were to send a message to sip:user@domain, the request would be “forked” to all three locations where the user is logged in.

INVITE forked to all endpoints

If, however, you sent the request to sip:user@domain;opaque=user:epid:UghFocauauCHBHoLhAAA;gruu, it would go to the specific device identified by the GRUU, and not to any of the others.

INVITE to GRUU

Let’s take a couple of examples of where this comes in handy. The example the IETF document uses is a call transfer. The way a transfer works in SIP is this: User A is on a call with User B, and wants to transfer User B to User C. User A sends a REFER message to User B, with User C’s SIP URI included in the message. User B then places a new call to User C.

Here’s the problem: User A may be talking to User C at the moment, and may need to transfer User B to a specific endpoint where User C is registered. If the SIP URI provided to User B is just a regular SIP URI, User B’s new call will end up going to all of the endpoints for User C. To solve this problem, User A can provide User B with the GRUU for a specific endpoint for User C.

Another example which applies to Lync is multimodal communication. Let’s say I’m on a Lync audio call with you on your laptop, and I want to add application sharing. When I click the button in the Lync client to add application sharing, that app sharing call shouldn’t go to ALL of the endpoints where you’re logged on — it should only go to your laptop, right? So to avoid this, I can send an INVITE message for the application sharing session to the GRUU associated with the Lync client on your laptop. Make sense?

One place where GRUUs come up often in Lync development is in creating a trusted application instance for your UCMA application. A trusted application always uses a GRUU because the application is tied to a specific server, and so it is always receiving messages from Lync at the same location.

The way Lync handles message routing for UCMA applications, and particularly application endpoints, is an interesting topic of its own, and I plan to cover that in my next post, so let me know if you have specific questions in that area that you would like to see answered.


6 Comments on “What is a GRUU?”

  1. 1 The many faces of remote participants | Lync Development said at 4:02 pm on April 17th, 2012:

    [...] device. If you look at the Uri property on a ParticipantEndpoint object, you will likely see a GRUU that belongs to the endpoint in [...]

  2. 2 How to tell where a call is ringing in UCMA | Lync Development said at 12:29 pm on May 8th, 2012:

    [...] A 180 Ringing indicates that an endpoint has received the message and is alerting the user to the call in some way. The 180 Ringing will contain details of the endpoint, such as that endpoint’s GRUU. [...]

  3. 3 » How to tell where a call is ringing in UCMA Clarity UC said at 12:42 pm on May 8th, 2012:

    [...] A 180 Ringing indicates that an endpoint has received the message and is alerting the user to the call in some way. The 180 Ringing will contain details of the endpoint, such as that endpoint”s GRUU. [...]

  4. 4 Keith Fong said at 11:29 am on July 30th, 2013:

    is there any way that a UCMA application can query the GRUU of a endpoint which already register to the Lync FE?

  5. 5 Ken Stauffer said at 8:48 am on February 22nd, 2014:

    Michael – Thanks as always for your great information. Possibly dumb question. So if this Gruu assigned at the time the app starts, different value each time? Is there any way to set it manually or have it be static?

  6. 6 Michael said at 9:06 am on March 6th, 2014:

    Hi Ken,

    For trusted applications, the GRUU is static. You can find it in Lync Management Shell by running the Get-CsTrustedApplication command.

    Michael


Leave a Reply

  • Note: Comment moderation is in use because of excessive spam. Your comment may not appear immediately.

  •