Haiku #65

Warning: It might not

Rain today. Stay calm and test

All your outbound calls.

Just a few minutes ago the author of today's Lync Server PowerShell haiku checked the weather report. (Which, admittedly, is a silly thing to do when you live in the Seattle area. But he did it anyway.) When he got to the Web page with the Seattle area forecast he saw this in big red letters at the top of the page:

Non-Precipitation Warning for Seattle Metropolitan Area

Alas, it's true: in Seattle they warn you when it's not going to rain, just to make sure that you have plenty of time to prepare yourself for this once-in-a-lifetime event.

Note. So what do Seattle area residents do when it's not raining? Hey, how would we know? We've only lived here for 22 years.

Ha! Get it? You see, because it rains all the time here and – well, never mind.

But all kidding aside, we Seattle residents do what anyone else does when it's not raining: we clean and oil our umbrellas; we ogle the raingear in the latest L. L. Bean catalog; and we use the Test-CsPstnOutboundCall cmdlet to ensure that we can still use Lync Server to make phone calls out to the PSTN network.

Ah, good question: how do you clean an umbrella? Well, from personal experience we can tell you how not to clean an umbrella: don't put it in the washing machine; that's just an all-around bad experience. Instead, wash your umbrella in a bathtub full of warm water and a little bit of laundry detergent.

Any other questions? Oh, that's a good one, too: how do you use the Test-CsPstnOutboundCall cmdlet to ensure that you can still use Lync Server to make phone calls out to the PSTN network? Let's see if we can figure that out.

Before we do that, however, we should take a moment to clarify what the PSTN network is. PSTN is short for Public Switched Telephone Network, and is what we tend to think of as the "regular" telephone network as opposed to a Voice over IP network like Enterprise Voice. (And this includes cell phones as well as your good old-fashioned "landlines.") Connecting a VoIP network to the PSTN network can be a little tricky, what with PSTN gateways and SIP trunks and assorted other paraphernalia. Because of that, once you have everything hooked up it's a good idea to test the system every now and then. That's where Test-CsPstnOutboundCall comes in.

The basic idea behind Test-CsPstnOutboundCall is pretty easy: the cmdlet simply makes a phone call to a phone number out on the PSTN network. Couldn't you just fire up Microsoft Lync and make a phone call from there? Sure, and that works great as long as the call gets through. But what happens if the call fails? With Microsoft Lync, all you know is that the call failed. By comparison, the Test-CsPstnOutboundCall cmdlet keeps a log of everything it does, and can even display each step it takes in trying to make that call. (To see that step-by-step display, just include the Verbose parameter in your call to the cmdlet.) For example, you might run the cmdlet and get back information similar to this:

VERBOSE: 'Register' activity started.

Sending Registration request:

  Target Fqdn: = atl-cs-001.litwareinc.com

  User Sip Address = kenmyer@litwareinc.com

  Registrar Port = 5061

Auth Type 'Trusted' is selected.

An exception 'The endpoint is unable to register. See the ErrorCode for specific reason.' occurred during Workflow Microsoft.Rtc.SyntheticTransactions.Worklfows.STOcsPSTNWorkflow execution.

As you can see, in this case the test never really got started: our test user (kenmyer@litwareinc.com) was unable to log on to the system. That could just be a problem with that test user account; for example, maybe you don't even have a user with that SIP address. Alternatively, you could be having problems with the Registrar for that pool. Either way, you have more to go on than just the fact that you dialed the phone and nothing happened.

Note. OK, we admit it: that might not be the greatest example we could have come up with. However, we PowerShell blog writers don't currently have a test environment where we can make calls to the PSTN network; every call we try to make will end up failing. So we used an invalid user account just so we'd have a semi-realistic error message to show you.

Basically it was either that somewhat-lame example or we were going to have to walk you through the steps involved in washing your umbrella.

As for how you actually use Test-CsPstnOutboundCall, well, there are a couple different ways. If you have configured health monitoring test accounts for a pool (see the help topic for the New-CsHealthMonitoringConfiguration cmdlet) then you can run Test-CsPstnOutboundCall using a command as simple as this:

Test-CsPstnOutboundCall -TargetFqdn atl-cs-001.litwareinc.com -TargetPstnPhoneNumber "+12065551298" -Verbose

Basically all you have to do is include the TargetFqdn parameter (followed by the fully qualified domain name of the Registrar pool being tested) and the TargetPstnPhoneNumber parameter, followed by the phone number you want to call. In this example we've configured that phone number using the E.164 format. However, that's not required. We could have also formatted the phone number, like, say, this:

-TargetPstnPhoneNumber "206-555-1298"

When you do that, Test-CsPstnOutboundCall will use the dial plan of the test user to try and normalize that phone number. If that dial plan can't normalize the number (that is, convert it to a format Lync Server understands) then the call will fail, just as it would in real life.

The moral of that story? To fully test the system as users will use it, set phone numbers using the same format your users will likely use; that way, you can see if the dial plan will be able to make sense of that number. On the other hand, if all you want to do is verify that the system is capable of making calls, then use the E.164 format. If you do that, then dial plan problems won't interfere with your test.

If you haven't set up any health monitoring accounts then you can run Test-CsPstnOutboundCall using any valid Lync Server user account and a pair of commands similar to these:

$cred1 = Get-Credential "litwareinc\kenmyer"

Test-CsPstnOutboundCall -TargetFqdn atl-cs-001.litwareinc.com -TargetPstnPhoneNumber "+12065551298" -UserSipAddress "sip:kenmyer@litwareinc.com" -UserCredential $cred1 -Verbose

As you can probably see, in the first line of code we use the Windows PowerShell Get-Credential cmdlet to create a credentials object for the user in question; that means we have to enter both the user name (in the format domain_name\user_name) and his or her password. That credentials information gets safely tucked away in a variable named $cred1, and is then used when we call Test-CsPstnOutboundCall. Note, too, that when we run that cmdlet we also need to specify the SIP address of our test user:

-UserSipAddress "sip:kenmyer@litwareinc.com"

So what happens after that? Well, after that Test-CsPstnOutboundCall will try to log the test user on to Lync Server. If the logon succeeds, the cmdlet will then attempt to place a phone call across the PSTN gateway. (As implied earlier, this phone call will be placed using the dial plan, voice policy, and other policies and settings assigned to the test account.) When the call is answered, the cmdlet sends dual-tone multi-frequency (DTMF) codes across the network in order to verify media connectivity.

Keep in mind that Test-CsPstnOutboundCall makes an actual phone call: the target phone will ring and must be answered for the test to succeed. Which simply means that maybe you want to call, say, your cell phone as opposed to one of those 1-900 numbers you saw advertised on late-night TV.

Just a suggestion.

So do we have any other suggestions before we call it a day? Just one. If you ever need to predict the weather in Seattle, here's a good rule of thumb. If you can look out the window and can see Mt. Rainier, then that means it's going to rain. And if you look out the window and can't see Mt. Rainier, then that means it's already raining.

Note. Hey, we don't write these ourselves. We just steal them from other Web sites. See you Monday.