List All the Users Who Use a Specific Gateway


Back here at the Windows PowerShell cave on the Microsoft campus we’ve set up an internal SharePoint site where people can make suggestions for Microsoft Lync Server 2010 scripts they’d like someone to write.
 

Note. In case you’re wondering, the Windows PowerShell cave is an exact duplicate of the Batcave used by Batman. Of course, we don’t have a crime lab or any other kind of laboratory; we don’t have any mechanized workshops; we don’t have a personal gymnasium; we don’t have a library; an airplane hangar; a trophy room; our own bat colony; or a Justice League teleporter.  But, other than that, the Windows PowerShell cave is an exact duplicate of the Batcave used by Batman.

 
At any rate, one of the suggestions left on the SharePoint site was this:

 
“Maintenance on a gateway might have an impact on users and their voice experience. How do we identify a list of users that are dependent on a gateway?”

 
Good question: how do we identify a list of users who are dependent on a gateway? Our first thought was to ask the Batcomputer. That proved to be difficult to do; after all, we don’t actually have a Batcomputer. Therefore, we decided to go with Plan B; we’d write a Windows PowerShell script that can return a list of users that are dependent on a gateway:

 
$routes = @()
$routeIdentities = @()

 

$gateway = $args[0]

 

$usages = Get-CsVoiceRoute | Where-Object {$_.PstnGatewayList -match “PstnGateway:$gateway”} | Select-Object PstnUsages

 

foreach ($i in $usages.PstnUsages) 
    {
        $routes += ((Get-CsVoicePolicy | Where-Object {$_.PstnUsages -match $i}) | Select-Object Identity) 
    }

 

foreach ($i in $routes)
    {$routeIdentities += ($i.Identity)}

 

$routeIdentities = ($routeIdentities | Sort-Object | Get-Unique)

 

foreach ($i in $routeIdentities)
    {
        $i = $i -replace “Tag:”, “”
        “Policy: $i”
        $users = (Get-CsUser -Filter {VoicePolicy -eq $i} | Select-Object DisplayName)
        foreach ($w in $users)
            {$w.DisplayName}
        Write-Host
     }

 
Let’s see if we can explain how this script works. (Unfortunately, there’s never a BatPowerShellScriptExplainer around when you need one.) For starters, let’s show you how you actually run the script. Suppose you’ve copied this code and saved it to a file named C:ScriptsGet-GatewayUsers.ps1. In that case, and assuming your PSTN gateway has the IP address 192.168.0.240, you’d run the script using this command:

 
C:ScriptsGet-GatewayUsers.ps1 “192.168.0.240”

 
OK, so that was easy enough; but what exactly does this script do? Well, for starters, it uses this command to return all the voice routes where our gateway (192.168.0.240) shows up in the values found in the PstnGatewayList property:

 
$usages = Get-CsVoiceRoute | Where-Object {$_.PstnGatewayList -match “PstnGateway:$gateway”} | Select-Object PstnUsages

 
Actually, we should clarify that a little: what we’re really returning here is not the voice routes but the PSTN usages associated with those voice routes. A PSTN usage is simply a string value that ties a voice route to a voice policy. What we’re doing here is getting back a list of PSTN usages associated with all the voice routes that use our gateway.

 
And why, pray tell, do we do that? Funny you should ask that question. In order to determine which users access a particular gateway, we need to know two things: we need to know the voice routes that use that gateway, and we need to know the voice policies that use that gateway. As soon as we know the PSTN usages associated with the gateway we can then use this block of code to run through that collection of usages and find all the voice policies that also employ those PSTN usages:

 
foreach ($i in $usages.PstnUsages) 
    {
        $routes += ((Get-CsVoicePolicy | Where-Object {$_.PstnUsages -match $i}) | Select-Object Identity) 
    }

 
After we do a little formatting, we can take these policies, one at a time, and use this command to return all the users who have been assigned each of those voice policies:

 
$users = (Get-CsUser -Filter {VoicePolicy -eq $i} | Select-Object DisplayName)

 
Those users – as you might have guessed – are the very same users who have the gateway 192.168.0.240.

 

Note. One important caveat about this script: it assumes that you are employing per-user voice policies and not relying on the global voice policy or voice policies configured at the site scope. That seems like a reasonable assumption, but if it’s not you’ll definitely have to make some changes to the script to account for that.

Skip to main content