Haiku #109

Wednesday? Thursday? Who

Cares? It's always a good day

With Test Voice User.

Well, it's Thursday – again. We say that not because we had another Thursday just a week ago; instead, we say that because, yesterday morning, both of the people who run the Lync Server PowerShell blog thought it was already Thursday. Despite what they thought, however, it wasn't. Yesterday was Wednesday; today is Thursday. To be honest, that whole "I thought it was Thursday" business came as a big surprise to us.

Note. Was it a big surprise because both of the authors of the Lync Server PowerShell blog made the same mistake and thought it was Thursday when it was really Wednesday? No, not really. We were more surprised that both of the authors of the Lync Server PowerShell blog actually had a thought of any kind. You don't see that very often around here.

Speaking of Thursday, here's a little more information about the day itself, courtesy of the Internet:

"The contemporary name comes from the Old English Þunresdæg, "Thunor's Day" (with loss of -n-, first in northern dialects, from influence of Old Norse Þorsdagr, meaning "Thor's Day"). Thunor and Thor are derived from the Proto-Germanic god Thunaraz, god of thunder. Most Germanic languages name the day after this god: Torsdag in Danish, Norwegian, and Swedish, Hósdagur/Tórsdagur in Faroese, Donnerstag in German or Donderdag in Dutch. Torstai in Finnish."

And there you have it. Would any other Lync Server blog bring you information like that? Definitely not.

And for good reason.

Ah, but here's something else that no other Lync Server blog would bring you (we know, because we looked): information about the Test-CsVoiceUser cmdlet.

Note. By amazing coincidence, the name Test-CsVoiceUser is also derived from the Old English Þunresdæg. What are the odds, huh?

You know, that's a good question: should other Lync Server blogs be telling people about the Test-CsVoiceUser cmdlet? Of course they should: this is a very handy little cmdlet to know about. As you probably know, setting up Enterprise Voice can be a little tricky, especially in large organizations that have users with different area codes, users with different country codes, users with different dialing rules to obtain an outside line, users with different extension numbers, etc., etc. Depending on your needs, you might have to configure a bunch of different dial plans, voice routes, voice policies, PSTN usages and other good things to ensure that any given user can pick up the phone, dial a number, and be confident that the call will go through. And, of course, that will happen only if you've assigned that user the correct dial plan, voice route, voice policy, and – well, you get the idea.

So how do you know if you did everything correctly; how do you know that a given user (say, Ken Myer) will actually be able to make a phone call? That's where the Test-CsVoiceUser cmdlet comes in. With Test-CsVoiceUser, you pass the cmdlet a phone number (using a format you might expect an actual user to use when dialing) and a user SIP address. In turn, the cmdlet will effectively tell you whether or not the user would be able to complete that call as dialed.

What does that all mean? Let's show you. Suppose Ken Myer typically makes a phone call by picking up his phone and punching the following numbers on his keypad:

12065551219

Is that going to work for Ken Myer? Hey, don't ask us; ask Test-CsVoiceUser:

Test-CsVoiceUser –DialedNumber 12065551219 –SipUri "sip:kenmyer@litwareinc.com"

When we ran the preceding command on our test computer, we got back the following:

TranslatedNumber MatchingRule FirstMatchingRoute MatchingUsage

---------------- ------------ ------------------ -------------

+12065551219 Descripti... LocalRoute Local

So what does that mean? Well, what Test-CsVoiceUser did here was take the number we dialed – 12065551219 – and determine whether or not a call could be made to that number using the dial plan, voice policy, voice route, PSTN usages and other voice-related things associated with Ken Myer's user account. The TranslatedNumber property is simply the number that will be handed off to Lync Server to make the call. As you know, Lync Server requires phone numbers to be in the E.164 format; that means a number that’s constructed something like this:

We handed off the phone number 12065551219, and Ken's dial plan used one of its normalization rules to convert that number to the E.164 format:

+12065551219

And that's good: that means that Ken can type in 12065551219 and Lync Server can convert that number to the E.164 format.

You say you'd like to know how it converts that number to the E.164 format? Well, that's what the MatchingRule property is for; it tells us which normalization rule was used to convert the number. You can't see much of the rule on screen, so try running this command:

Test-CsVoiceUser –DialedNumber 12065551219 –SipUri "sip:kenmyer@litwareinc.com" | Format-List

When we pipe the output to the Format-List cmdlet we get something a little easier to read:

TranslatedNumber : +12065551219

MatchingRule : Description=;Pattern=^(\d{11})$;Translation=+$1;

                    Name=Prefix All;IsInternalExtension=False

FirsMatchingRoute : LocalRoute

MatchingUsage : Local 

We won't discuss normalization rules in any detail today, but suffice to say that the rule shown above takes any 11 digit value entered on the keypad (like 12065551219) and adds a plus sign (+) to the front of it. Thus, the translated number +12065551219.

The FirstMatchingRoute property lists the voice route that the call will take, while the MatchingUsage property lists the PSTN usage that will be used for the call.

Note. We should probably note that our test computer isn't connected to the real world, and can't really make phone calls. Because of that, we simply tacked together a few voice policies and dial plans and what have-you to make sure we got some kind of output to show you. We mention that simply because someone who really knows their stuff might look at this and think, "That combination of dial plans and routes doesn't make any sense; I don't think that would work in real life." And there's a good reason for that: it might not work in real life. This is all for demonstration purposes only. But in real life, you'll get something very similar to this.

OK, that's what things look like when you enter a number that Lync Server can handle. Now, suppose Ken enters this number on his dialpad:

5551219

Is that call going to go through? Let's find out. First, let's call Test-VoiceUser:

Test-CsVoiceUser –DialedNumber 5551219 –SipUri "sip:kenmyer@litwareinc.com"

And now let's look at the output:

TranslatedNumber MatchingRule FirstMatchingRoute MatchingUsage

---------------- ------------ ------------------ -------------

As you can see, there's nothing there: Lync Server can't translate the phone number 5551219. What does that mean? That means we either have to tell Ken to dial the complete number (12065551219) or we need to create a new normalization rule that can convert 5551219 to the E.164 format.

By the way, here's a little tip that might come in handy for you. When you call Test-CsVoiceUser, you might want to tack on the Verbose parameter:

Test-CsVoiceUser –DialedNumber 5551219 –SipUri "sip:kenmyer@litwareinc.com" -Verbose

What the Verbose parameter will do is provide a little more information about Test-CsVoiceUser and what it's doing. For example, when we ran the preceding command we got back this additional data:

VERBOSE: Locating user with identity "sip:kenmyer@litwareinc.com"

VERBOSE: Loading dial plan: "RedmondDialPlan"

As you can see, when we use the Verbose parameter we get back the name of Ken's dial plan: RedmondDialPlan. We've already seen that Ken's dial plan can't normalize the phone number 5551219. Now we know which dial plan needs to be updated if we want to allow Ken to dial a number like that.

That's all we have for today. Happy … um, hang on a second here while we look this up … Happy Thursday everyone!