Haiku #192
Seahawk football? Thanks.
But we'll just play with voice route
Cmdlets instead.
Well, autumn officially arrived in the Pacific Northwest this past weekend. How do we know that? Well, for one thing, the weekend was cold and damp, which is – well, never mind; come to think of it, it's pretty much always cold and damp here, regardless of the season. On top of that, the Seattle Mariners lost two more games this weekend, meaning they have no chance to – well, OK, never mind. Not a good example, either.
Wait, here's one: both of our football teams, the Seattle Seahawks and the University of Washington Huskies, got beat this past weekend.
Note. Sorry, Washington State University, but we don't really claim you as one of our football teams. Nevertheless, a tip of the hat to the Cougars for doing a pretty darn good imitation of a Pacific Northwest football team: WSU got whipped by San Diego State (San Diego State?!?) on Saturday.
Now, in all fairness, we should point out that both the Seahawks and Huskies were obviously victims of budget cuts and the economy. With money as tight as it is, the Seahawks were only able to send their defense to Pittsburgh and were forced to leave their offense at home. (And yet, despite that, the team still managed to cross the midfield stripe – twice.) The Huskies, beset by the same budget woes, decided to leave their defense at home, and, as a result, dropped a 51-38 decision to Nebraska. To put that in perspective, the 1991 Husky team that won the national championship gave up 101 points. That's 101 points over the entire 12-game season. In three games this year, the Huskies have already given up 110 points.
Autumn is such a delightful season.
Speaking of which, there's one other sign that autumn has arrived: we're almost done with the daily Lync Server PowerShell haiku. In fact, after today we'll have just two more nouns to cover: CsCertificate and CsDeviceUpdateRule. At that point, we'll have written haikus for all the Lync Server PowerShell nouns, something they said could never be done!
Or maybe it was something they said should never be done. But you get the idea.
At any rate, we'll have more about the haiku of the day – and our future plans for the Lync Server PowerShell blog – later. Today we have something way more important to talk about: the state of football in the Pacific Northwest.
On the other hand, based on the results of this past weekend, there really isn't much to talk about when it comes to football in the Pacific Northwest. So let's talk about the CsVoiceRoute cmdlets instead: Get-CsVoiceRoute, New-CsVoiceRoute, Remove-CsVoiceRoute, and Set-CsVoiceRoute. Oh, and Test-CsVoiceRoute, too.
Note. Don't worry, we'd never forget Test-CsVoiceRoute.
As you probably know, voice routes are used to route calls from Enterprise Voice users to phone numbers on the public switched telephone network (PSTN) or a public branch exchange (PBX) system. Without getting too technical (in large part because we can't get too technical when it comes to voice routes), any time an Enterprise Voice user places a call Lync Server converts the dialed number to the E.164 format and then tries to match that E.164 number to a SIP URI. If the E.164 number can't be matched to a SIP URI Lync Server then uses voice routes to determine how the call should be handled. For example, if the dialed number is 1-206-555-1219 a voice route would figure out that this is a call to a US phone number and send the call to the appropriate PSTN gateway. If the dialed number is 44-113-555-1219 a different voice route would recognize that this is a call to a number in the United Kingdom (country code 44) and, in turn, might route the call to a different PSTN gateway. Admittedly, that's a somewhat simplistic explanation of voice routes and how they work, but it'll do for now.
As for how you create a voice route in the first place, well, here's one example:
New-CsVoiceRoute -Identity RedmondVoiceRoute -PstnUsages @{add="Long Distance"} -PstnGatewayList @{add="PstnGateway:redmondpool.litwareinc.com"}
This happens to be a very basic voice route: it simply specifies an Identity (RedmondVoiceRoute) as well as one PSTN usage and one gateway. (A single route can support multiple PSTN usages and/or multiple gateways.) You can actually create a voice route that doesn't have a PSTN usage or a PSTN gateway; for example, this is a perfectly valid Lync Server PowerShell command:
New-CsVoiceRoute -Identity RedmondVoiceRoute
That command will create a voice route, but it will be a totally useless voice route: without a PSTN usage or a PSTN gateway, the route will not be able to forward calls; in turn, that means that your users won't be able to actually place phone calls. The moral of the story? It doesn't make a whole lot of sense to create a voice route that doesn't have at least one PSTN usage and at least one gateway.
Note. So what exactly is a PSTN usage? For more information, take a peek at Haiku #78. And, while you're at it, you might spend a few minutes reading Haiku #37, which gives you the lowdown on PSTN gateways.
That will give you something to do while you wait for the Seahawks to actually score a point.
Incidentally, the voice route we just created basically matches any E.164 number. In turn, that means that any number that gets dialed will be scooped up by this voice route and forwarded to the gateway redmondpool.litwareinc.com. How do we know that? Well, by default the NumberPattern property for a voice route is set to this:
[0-9]{10}
That's an odd-looking value, yes, but it's a regular expression that basically says this: if you see a phone number that consists solely of the digits 0 through 9 and that phone number is at least 10 digits long, well, then we've got a match. Needless to say, that's going to basically be any phone that gets converted to the E.164 format. But what if you only wanted to match calls made to the 206 area code in the US? In that case, you'd need to change the NumberPattern. For example:
-NumberPattern "^1206[0-9]{7}"
Without going into any details, that matches any number that starts with the value 1206, and then is followed by 7 digits. For example:
12065551219
The other thing you might need to do here is set the Priority for the voice route. As you might recall, the first voice route we created captures pretty much any E.164 phone number; that means it will capture phone calls made to the 206 area code. How do we make sure that our other voice route captures calls made to the 206 area code? One sure-fire way is to set the Priority of the route to 0:
-Priority 0
If you run into a situation where multiple voice routes match a given phone number, Lync Server will use the route that has the lowest Priority value. And 0 is the lowest priority.
By the way, here's the full command that creates a voice route that matches 206 numbers and has a Priority of 0:
New-CsVoiceRoute -Identity 206AreaCodeVoiceRoute -PstnUsages @{add="Long Distance"} -PstnGatewayList @{add="PstnGateway:redmondpool.litwareinc.com"} -NumberPattern "^1206[0-9]{7}" –Priority 0
And before you ask, yes, this can get complicated. Which is at least one reason why you should carefully plot out your voice routing strategy before you begin creating new voice routes willy-nilly.
Seeing as how New-CsVoiceRoute is used to create new voice routes, it probably comes as no surprise that Remove-CsVoiceRoute is used to remove existing voice routes; Get-CsVoiceRoute is used to return information about existing voice routes; and Set-CsVoiceRoute is used to modify existing voice routes. What kind of things would you ever need to modify in a voice route? Well, here's an interesting example. By default, any call placed using a given voice route will end up displaying the caller's phone number in any Caller ID system. For example, suppose Ken Myer has the phone number 555-0712 and he places a call to Pilar Ackerman. What number is going to show up on Pilar's Caller ID? This number:
5550712
That's fine, but suppose you'd rather have your company's phone number (5551234) show up on Caller ID systems, regardless of whether Ken Myer or anyone else places the call. Can you do that? Sure you can. All you have to do is set the SuppressCallerId property to True, and then specify the number to be displayed as the value of the AlternateCallerId number. You know, like this:
New-CsVoiceRoute -Identity 206AreaCodeVoiceRoute –SuppressCallerId $True –AlternateCallerId "5551234"
Just a little something you might find useful.
Another little something you might find useful is the Test-CsVoiceRoute cmdlet, which lets you verify that a given phone number will match the NumberPattern for a given voice route. In order to use the Test-CsVoiceRoute cmdlet you need to do two things. First, you need to use the Get-CsVoiceRoute cmdlet to retrieve an object reference to the voice route being tested. For example:
$x = Get-CsVoiceRoute "206AreaCodeVoiceRoute"
Second, you need to then use that object reference plus the number being dialed in your call to Test-CsVoiceRoute:
Test-CsVoiceRoute -TargetNumber "12065551212" -Route $x
The preceding test should return True. Why? Because the NumberPattern for the 206AreaCodeVoiceRoute is supposed to match any phone number that starts with 1206 and then is followed by at least 7 digits. This command should return False:
Test-CsVoiceRoute -TargetNumber "14255551212" -Route $x
Why? You got it: because the target number does not start with 1206. And this command will fail because, although the target number starts with 1206, it's not followed by 7 digits:
Test-CsVoiceRoute -TargetNumber "1206" -Route $x
Could we just sit around and run voice route tests all day? You bet we could. But that's mainly because, here in the Pacific Northwest, we don't have any football games worth watching. Those of you who live in Kansas City (and have watched your beloved Chiefs get outscored 89-10 this season) know exactly what we’re talking about.
See you tomorrow.