If you have deployed or managed large Lync environments with Enterprise Voice, you should be well aware of how uninviting phone number management can be.
Assume you are running a large deployment with hundreds or thousands of number assignments and want to get a list of available or taken DDIs, or you need to assign a number to a new user and you need to look up the next available number in your range; or perhaps you attempt to assign a number, and you realize it's already taken, but you have no idea by whom. All of these supposedly normal administrative tasks will require either of the following:
- Advanced filtering on the Lync Control Panel
- PowerShell cmdlets or scripts
- An accurate and up-to-date documentation of number assignments
Search-LineURI (by Lasse Wedø) and Get-UnusedNumbers (by Ståle Hansen) are helpful tools, which will ease some number management aspects.
The authors have started a joint project on http://www.lyncnumbers.net with the aim to collect tools and information about Lync number management. You will find their updated scripts available as individual downloads, specifically Search-LineURI: http://gallery.technet.microsoft.com/Search-for-that-LineURI-814ac281/ and Get-UnusedNumbers: http://gallery.technet.microsoft.com/Find-next-available-number-58391c72.
Search-LineURI is a PowerShell script that will search and list/display all numbers assigned on a Lync environment. It includes numbers assigned to users as well as special resources such as Response Groups, common area phones, and so on; all resources that can have a number assigned are covered. It comes with several switches and options and we recommend that you review these in their entirety by opening the PS1 script in a text editor and reading through the description. We will look at a practical usage example along with the most useful options.
Assume that our Lync 2013 Enterprise Voice deployment uses the following numbering range:
- The first number is 212-555-1001 (in E.164, this is +12125551001)
- The last number is 212-555-1999 (in E.164, this is +12125551999)
The script must be run from Lync PowerShell. As it is not signed, you might first need to allow the execution of unsigned scripts. Proceed as follows:
- Open PowerShell and type
Set-ExecutionPolicy Unrestricted. - Run the script as follows:
.Search-LineURI.ps1 –search 5551 -ListAsGridView.
The –search 5551 (actually, it is *5551*) option tells the script to match all numbers that contain the 5551 string in the URI. It should be noted that a minimum of 2 digits must be provided in the search option.
The –ListAsGridView command instructs the tool to display a GUI-based list, as shown in the following screenshot:
The output will list all assigned numbers (for users, it will display both the main line URI and the private line, if applicable) along with the SIP address and identity path. Note that the last entry (name: RG1) actually belongs to a Response Group.
Other typical usages are described in the following table:
|
Command |
What does the command do? |
|---|---|
|
|
This finds all assigned numbers that contain 5551 in the URI and displays them within the PowerShell session. |
|
|
This finds all assigned numbers that contain 5551 in the URI and saves the output at |
The Get-UnusedNumbers script is a PowerShell script that will search through all users, special services, and devices and list/display unassigned numbers.
For proper operation, the script needs to know what number ranges are being used on the Lync platform; the following are the two ways to achieve this:
- Leverage the Unassigned Number voice feature in Lync. You will need to configure this before running the script.
- Specify a custom range within the script
Let's make a practical example for case 1, assuming our Lync deployment has a SIP trunk with the following numbering range:
- First number: 212-555-1001 (in E.164: +12125551001)
- Last number: 212-555-1019 (in E.164: +12125551019)
We first need to configure an announcement for unassigned numbers. A full explanation about all options is available at http://technet.microsoft.com/en-us/library/gg425944.aspx. For our example, we will configure a simple text-to-speech announcement through the following PowerShell command (note, announcements cannot be configured through the Control Panel):
New-CsAnnouncement -Identity applicationserver:lyncsefe01.giombini.com -Name DefaultAnnouncement -TextToSpeechPrompt "This number is not assigned" -Language en-US
The result is shown in the following screenshot:
We are now able to configure an unassigned number range. This can be done through PowerShell or the Control Panel. We will use the latter and configure as per the following illustration (when done, click on OK then the commit button):
Now, we need to change something in the script before being able to run it interactively, and leveraging the unassigned number feature. Please open the script with a text editor (Notepad or the like), and browse towards the end until you find the following line:
$FirstNumber=Get-Unused -RangeStart +47232323001111 -RangeEnd +47232323001190 -Name "Custom Range Norway" #-ListAll $true
Change the preceding lines to the following:
$FirstNumber=Get-Unused -Name "Unassigned Number range" -ListAll $true
Such change will instruct the script to not use a custom phone range (therefore it will use the range defined in the unassigned number announcement feature), and will list all free numbers, not just the first one.
We are now ready to run the script by opening a PowerShell, browsing to the folder where the script was saved and typing the following:
.Get-UnusedNumbers.ps1
The first useful information we retrieve is our range is made of 19 numbers, 14 of which are not assigned. Then, type L, to list all available numbers, and then press Enter. This will return all unused numbers in our deployment, as shown in the following screenshot:
Now, let's make another example for case 2. This time, we will not be using the unassigned number feature; we will instead specify a custom parameter in the script. Please go back to the following line in the original script:
$FirstNumber=Get-Unused -RangeStart +47232323001111 -RangeEnd +47232323001190 -Name "Custom Range Norway" #-ListAll $true
And change the preceding line as follows:
$FirstNumber=Get-Unused -RangeStart +12125551001 -RangeEnd +12125551009 -Name "My Custom Range" -ListAll $true
We are now ready to run the script by opening a PowerShell, browsing to the folder where the script was saved and typing:
.Get-UnusedNumbers.ps1
The first useful information we retrieve is our custom range is made of 9 numbers, 5 of which are not assigned. Then, type L, to list all available numbers, and then press Enter. This will return all unused numbers in our deployment (this time, in our custom range defined within the script):
The currently reviewed version is v.4 and does not feature the ability to export the output to a table or a file. This is expected in a future version.
Another great feature is the script is a function, and may be then reused in other scripts. An example could be reusing the function in a script that enable users for enterprise voice, retrieve the first available number in the range, then programmatically assign it to users as they get automatically enabled. This is also the reason why we needed to change some parameters directly within the script before being able to run it interactively. The author is planning to add support for parameters in a future version.