Sunday, 29 November 2015

Skype4B / Lync DHCP Config Tool

Put up your hand if you know how to configure DHCP for Skype for Business and Lync phone devices? Leave your hand raised if you enjoy this process? Okay, I thought so, read on…

When deploying Skype for Business/ Lync Optimized or Qualified phone devices you are required to make specific DHCP configuration settings in order for the devices to be able to authenticate and connect to the system. The settings that are required are some special Vendor Class Options and a standards-based Option 120 setting.

DHCP Vendor Class Options - Option 43

Option 43 is a special option type used in DHCP responses that encapsulates options for a specific Vendor Class. A DHCP server will respond with Vendor Class options only when a device specifically requests them. The method for requesting the Vendor Class options is normally achieved by the device putting a Vendor Class ID in Option 60 of its initial DHCP DISCOVER message. This method is usually used for settings that might be required by the device when it first boots.

Another method (which I’ve only ever seen used by Skype4B/Lync devices) is to send an INFORM message after the initial discovery process has completed to the DHCP server requesting additional information for a specific Vendor Class. The signalling for the Vendor Class request is the same as in the DISCOVER method however, in this case the Option 60 message is inserted in the INFORM message. It is important to note that the INFORM method is not supported by all DHCP servers, however, it is supported by Windows DHCP servers and Cisco switch/router DHCP servers. If you're using an different DHCP server you may need to check that it response to INFORM messages. 

Skype for Business and Lync phone devices use Option 43 to pass information about the certificate provisioning service to the phones. The phones need this information in order to do PIN Authentication with the system. The options encapsulated within option 43 include the following:

Option Number
Option Name
Setting Type
Vendor Class
Common setting
Common setting
Variable - Set this to match your pool / domain
Web Port
Common setting
Cert Prov URL
Common setting

These settings combine to give the phone all the information it needs to contact the Certificate Provisioning service on the system. The phone will recombine these to be a URL as follows:

DHCP Option 120

Option 120 is a specific option that is described as part of a RFC 3361. The option describes SIP server locations in the form of FQDNs or IP Addresses. Skype for Business and Lync devices have been designed to use this standard option to discover the location of the pool for SIP signalling (registration, authentication, call signalling, etc).   

Option Number
Option Name
Setting Type
Variable - Set this to match your pool / domain

The encoding of Option 120 is not just a simple ASCII byte conversion for entry into the DHCP server. There are also framing bits around the FQDN that is described as part of RFC 3361. The RFC described two different types of encodings for Option 120 –  the first is FQDN format, and the second is IP Address format. Only the FQDN formatting option is available for Skype for Business and Lync due to the fact that it uses TLS-based SIP which requires FQDN matching when creating the secure channel connection.

How Does DHCP Option 120 interact with DNS?

If you don’t specify anything for DHCP Option 120 the Skype4B/Lync Phone Edition devices will fall back to looking up the following DNS records:
  • _sipinternal._tls SRV record
  • _sip._tls SRV record
  • sipinternal.<user domain>  (Be careful of this record. This is not included in the certificate SAN list by default so don’t enter it into DNS unless you have added it specifically to the SAN list)
  • sip.<user domain> (This record is included by default in the certificate SAN list. So it’s safe to use.)

During the process, if Option 120 is not discovered, the Skype4B/Lync Phone Edition devices will display “Registrar FQDN cannot be found. Please contact your support team” on the screen and then sign in using the fall back DNS lookups. This is not ideal because users might be confused by this message so it’s always recommended to configure Option 120.

Configuring the DHCP Server

The method of configuring the DHCP server supplied by Microsoft is to use a command line tool called DHCPUtil that will create the byte encoded output for each of the required Options. The output of the DHCPUtil command is then used in conjunction with a batch file to deploy the setting within your DHCP server. This process is multi-step and I have found it prone to errors, and difficult to troubleshoot once the options are deployed, because they are displayed as bytes in the interface. The DHCPUtil method also only supports configuring Server Options within the Windows DHCP server and does not support Scope Level options configuration. I figured I could build a tool in Powershell that would be easier to configure, more flexible, and help you in troubleshooting your DHCP deployments.

Skype4B / Lync DHCP Config Tool

  • Deploy Server and Scope level settings within your Windows DHCP server.
  • The tool will encode the settings as required to be deployed within the server.
  • The tool will download and display the current settings from the DHCP server.
  • Edit and remove individual settings as required.
  • Export to Cisco IOS Switch/Router DHCP configuration commands.
 Note: The tool must be run on a Windows DHCP server!

Available on the TechNet Gallery:


The tool itself is fairly straightforward to use –  when it loads, it will query for all the scopes configured in the DHCP server. The scopes are displayed in the drop down list at the top of the form. When you select a Scope from the list, the tool will query the Options available for that scope and show them in the settings text boxes (current settings are shown in green). If the scope has no options configured, the boxes will be empty. If you would like to auto fill the boxes with the common configuration settings you can click on the Defaults button. When you have filled in the settings with the desired configuration you can click the Upload Settings button and the Options will be configured on the server. If you would only like to upload specific Options, you can use the Check Boxes next to the settings to select the desired Options to upload. The Remove Settings button will remove any of the settings from the selected scope that has the check box ticked. If you only want to delete a specific option, then you tick only the check box of the specific item before clicking the Remove Settings button.

Your DHCP server may already have Option 120 or the Vendor Class options defined. If this is the case and any of these options are defined as anything other than the Binary type then the tool will display the setting as <UNSUPPORTED TYPE>. This looks like the following:

Unsupported Type of and Existing Option

If this happens you can choose to upload a new setting over the existing setting. If you do this the tool will display a dialog asking if you would like to delete and replace the existing option definition with a new one. The new definition that the tool will create will be Binary in type which it will be able to edit and display.

Option Definition Change Dialog

The tool also does checks on Option 120 when it reads it from the DHCP server to ensure that it is formatted correctly (as defined by RFC3361). If it determines that the setting is not in the correct format it will display <UNSUPPORTED FORMAT> in the text box. If this happens, then I suggest you upload a new setting over the top of the unsupported setting to ensure that your phones can parse the option properly.

Important Note: You must refresh the scopes within the Windows DHCP Server MMC console in order to see changes you have made with the DHCP Config Tool. 

Cisco Router / Switch Configuration

If you do not have Windows DHCP server for the subnet that your devices are deployed on, you may choose to use a Cisco switch or Router to be the DHCP server. The "Export Cisco" button allows you to export Cisco IOS configuration commands for option 120 and 43 of a Cisco switch or router running as a DHCP server.

It should be noted that when you use this format in a router or switch there is a significant difference from a Windows DHCP server implementation. In the Cisco method you are hard coding the DHCP server to respond with these Option 43 settings for every device that requests Vendor Class options of any class. On a Windows DHCP server, it will only send Option 43 information to devices that have requested the specific Vendor Class of MS-UC-Client (the device does this by putting this Vendor Class info into Option 60 of its initial request message). This means that, per subnet, you can only have one Vendor Class deployed on a Cisco switch/router. In addition to this, you need to make sure that there are no other devices on the subnet that use Option 1-5 in their respective Vendor Classes because they will receive the settings you have deployed for Skype4B/Lync in their DHCP responses. This may have undesired results when they parse and use these settings instead of the ones they were expecting. So be sure you understand the risks of this where deploying using this method and try to limit the device on the subnet to be your Skype4B / Lync devices only (where possible).

The tool will output the format as shown below:

option 43 hex 010C4D532D55432D436C69656E7402056874747073031446453030312E6D79736B7970656C61622E636F6D040334343305252F4365727450726F762F4365727450726F766973696F6E696E67536572766963652E737663
option 120 hex 000546453030310A6D79736B7970656C616203636F6D00

These settings can be inputted directly into your DHCP pool settings in Cisco IOS!
An example of a basic configuration might look like this:

Router(config)# service dhcp
Router(config)# ip dhcp pool TEST-POOL
Router(dhcp-config)# network
Router(dhcp-config)# default-router
Router(dhcp-config)# dns-server
Router(dhcp-config)# lease 8
Router(config)# ip dhcp excluded-address
Router(config)# option 43 hex 010C4D532D55432D436C69656E7402056874747073031A32303133454E5446453030342E6D796C796E636C61622E636F6D040334343305252F4365727450726F762F4365727450726F766973696F6E696E67536572766963652E737663
Router(config)# option 120 hex 000C32303133454E544645303034096D796C796E636C616203636F6D00
Note: Other settings like NTP server, Time Offset, Config server, etc. may also be required depending on the device.

Server Scopes and Subnet Scopes

The tool allows you to access Server Scope or Subnet Scopes within the DHCP server. The server scope should be looked at as the fall-back settings for all scopes. If you apply settings to the server scope, then these will be used by default by all subnets in the DHCP server. If you apply Subnet level settings, then these will be used in preference to the Server Scope settings. Below is an example of Subnet level settings, however Option 120 in this case is a Server Scope level setting. Note the different icons used for the different scope types:

The Wrap Up

Congratulations, you are now an expert at configuring DHCP servers for Skype for Business and Lync phone devices! I hope you enjoy this new tool and that it brings you great joy and delight over the holiday season.

Read more →

Thursday, 1 October 2015

Skype for Business / Lync Polycom VVX Manager Version 2

Polycom’s VVX range of phones on Lync/Skype for Business have come a long way in the past few years. The release of version 5.4 has delivered further improvements and new features and moved them into a position of superiority over even Lync Phone Edition devices. As a result, the VVX range are now being taken much more seriously by businesses for large scale rollout. Version 5.4 of VVX software has now also brought about support for remote management features by way of a RESTful web service interface. This was music to my ears as my previous VVX Management Tool was built on a combination of hacked together legacy features of the phones and can now be replaced with a supported API. So with this new API at my disposal, I decided to rip the guts out of the old version of the tool and re-engineer it from the ground up for an all new version 2.0 release!

Polycom VVX Manager Version 2 Features

Polycom VVX Phone Manager 2

Phone discovery – Phones can be discovered either by automatically querying the Lync/Skype for Business Monitoring database (provided there is a monitoring role deployed in the environment) by pressing the “Discover from Monitoring DB” button. Alternatively, this can be done by entering IP Address ranges and “pinging” contiguous subnet ranges for phones using the “Discover from IP Range” button (format: "" OR "" OR add multiple with comma separation ","). During the discovery process, phones that are logged in to user accounts will be listed in the users list. If the tool finds a VVX handset that is not signed in, it will be added to the user list under the name “VVXNot@LoggedIn_<index number>”. This allows you to use the tool to access these devices even though they are not signed into the system.

Important Note: The VVX Phone Manager Tool uses the registration database within the Lync/Skype for Business monitoring database to determine the IP addresses of phones. However, registrations are only added to this database at the time when a user manually signs in with a PIN or with Domain authentication details. If a user moves a phone to a new subnet or the IP Address changes without signing it out/back in then its new IP Address will not be written to the Monitoring database. So, in some cases, the Monitoring database may not produce a complete list of registered VVX devices. The "Monitoring DB Query Time" value in the "Settings" dialog can be used to extend how far back the Monitoring DB query will go to find VVX registrations. This can help to find phones that haven't been manually signed in for an extended period of time. Or alternatively, the "Discover from IP Range" option can be used to do an exhaustive scan of all subnets if required. 

Export/Import Phone Info – This feature outputs a CSV file that contains all the Users, IPs, Firmware Version, Serial Numbers, Lync/Skype for Business Server, and MAC Address (if available) for all phones. If you select the "More" checkbox you will also get the additional Lync/Skype for Business policy settings for each user (this is slower).

Access Web Interface - Access the web interface of a VVX phone by selecting a user in the user list and clicking the “Web Config” button. This will automatically load the web browser to the phone's web interface.

Pin control – The “Pin…” button will load a dialog that will Set, Test, Lock, Unlock a user’s PIN number.

PIN Dialog

Send Text Messages - Send text messages to be displayed on a Polycom VVX phone. An example of this would be to send a message to warn before a system upgrade or a reboot. Messages are displayed on the screen for 30 seconds.

Example of Message Screen

Note: Sending messages relies on the PUSH interface being enabled on the phone in order to accept the message. See the VVX Requirements section for more detail of this configuration. 

Get More Info – By pressing the “More Info” button you can get extended information about a VVX phone including: Device Info, Call Status, Presence Info, Network Info, Line Info, SIP Status, Network Statistics.

Reboot/Restart Phones – You have the choice of Rebooting or Restarting a single, multiple, or All phones.

Reset Config – You have the option to Reset the Config or Factory Reset the configuration with one or many phones.

Get/Set Config - You can Get or Set any setting in the phone configuration. You simply need to enter the configuration setting name (as you would find in the configuration file eg. log.level.change.hset) and click the Get or Set buttons to view or change the setting's value.

Dial / End Call – You can choose to remotely dial a SIP URI (eg. or on a phone by entering a URI and pressing the “Dial” button. If the phone is on a call you can also choose to end the call using the “End Call” button.

Test FTP Config Server - Test your FTP Configuration File server by simply entering the IP address of the FTP server and pressing the “Test FTP” button. The tool will attempt to connect to the FTP server and download information about key files associated with a Polycom configuration server deployment. These include the base configuration file (000000000000.cfg), configuration files in the CONFIG_FILES tag, any MAC address files associated directly with phones, and firmware files (*.sip.ld). The tool will give feedback as to the state of the FTP server.

View Screen – The “Screen…” button will open a dialog that will show you the user's screen. Before the user's screen can be viewed the user must first manually allow access to the Screen Capture feature (this is a security measure so that the user is aware that someone is viewing their screen). This setting within the Basic->Preferences screen will only be made available while the VVX screen dialog is displayed (the tool automatically makes the setting "up.screenCapture.enabled" in the device to turn on this preference setting). When the dialog first loads you will see a screen that looks like this:

VVX Screen Dialog

At this point the user will have to enable the following setting in their phone preferences:

Settings -> Basic -> Preferences -> Screen Capture -> Enabled

Note: The Screen Capture option is only available to the user once you have open the screen dialog with the VVX Manager Tool (so don’t close the dialog until the user has turned on the manual preference setting).

Now you will be able to see the user's screen and save screenshots of the screen as JPG files if you so desire:

VVX Screen Dialog

Command Line Settings – If you would like to load the script with your own specific settings to save time, you can specify these in the command line when loading the script. The format of the parameters are as follows:

Script command line settings:
.\Skype4B-Lync-PolycomVVXManager2.00.ps1 -WebPortInput 443 -UseHTTPSInput false -AdminUsernameInput AdminUsername -AdminPasswordInput AdminPassword -PushUsernameInput PUSHUsername -PushPasswordInput PUSHPassword -IPRangeInput

Settings Dialog – The “Settings…” button allows you to configure your own passwords, web service port and HTTPS settings for the tool.

Note: Continue reading for definitions of these settings.


2.01 Enhancements
  • Fixed issue with the Get Config function
  • Increased the timeout for discovery ping from 200ms to 350ms to handle sites that might be over a higher latency connection. Also added a setting called "Discovery Wait Time" which allows you to tune the time that the tool will wait for responses from discovery messages sent to phones (setting between 200ms-1000ms).

2.02 Enhancements
  • Fixed issue with rescan on CSV import.
  • Included new Polycom MAC Address range 64:16:7F
  • Added a discovery summary at the end of IP Based discovery. This gives a useful summary when scanning multiple IP ranges.
  • The command line input for IPRangeInput now accepts muiltple ranges in comma separated format. eg. Skype4B-Lync-PolycomVVXManager2.02.ps1 -IPRangeInput ","

2.03 Bug Fix
  • There was an issue with detecting users when capital "SIP:" was used as part of their SIP URI. This has been fixed.
2.04 Bug Fix
  • Fixed a couple of typos that affected operation on Powershell 5
  • Added more VVX types when discovering logged out phones
2.05 Bug Fix
  • Added port number to screen viewing URL. Required when non-standard HTTP/HTTPS port is used.
2.10 Fixes and Enhancement! (28/7/2017) 
  • Replaced Invoke-RestMethods with shiny new .net web requests to fix annoying connection issues found in previous versions.
  • Added option in Send Message dialog to select the theme/style of the message displayed on the VVX. Default is to send the new SfB dialog style, the original Polycom theme and red/alarm themes are also available.
  • Updated Icon to new MySkypeLab icon.
  • Added some more detail in blog post about Push configuration.
2.20 More Fixes and Enhancements! (28/8/2017)
  • Fixed threading issue with discovery that could result in some devices not being listed.
  • Added support for RealPresence Trios.
  • Added support for VVXs and Trios configured as CsMeetingRoom devices.
  • Added Trio Filter checkbox to view only users with Trios.
  • When not logged in Trio is discovered it will be displayed as "TrioNot@LoggedIn"
  • Fixed discovery Instance name when default SQL instance is used.
  • Changed the "VVXNot@LoggedIn_<value>" name to end with the IP Address of the device rather than an incrementing number.
  • Fixed the IP Address discovery count text in Powershell window to make more sense
  • Fixed issue with listview scrolling and colored lines changing back to black. Clicking on the listview will refresh the colours.
  • Increased VVX and Trio list checkbox filter speed.
  • Fixed issues with setting and testing pins.

Available on the TechNet Gallery:


Polycom VVX Manager Configuration Requirements

Firmware Requirements

The VVX phone must be at firmware version 5.4 in order to be controlled by the VVX Phone Manager Tool because this version is the first to support the new REST based management API. If you select a user that has a phone with an older version of software, the tool will display a warning in the Powershell window and give you limited access to features for that user. Note: software version 5.4.0A is required for VVXs connecting to Skype for Business.

VVX Web Server Settings

Since version 5.1 of VVX software, there have some increased security enhancements added to the phones. This increased security will affect your ability to connect to the web interface and web services interface of VVX devices when you are running them in an out-of-the-box configuration. So in order to use this tool you will need to edit some basic configuration settings on your phones (usually done via configuration files).

The following web server settings were added in version 5.1 VVX firmware:

Web Config Mode

Different combinations of these setting will give you access to either HTTP, HTTPS or both at the same time. Below are examples of how to achieve all of these settings:

Example settings:

HTTP Web access only:
<!-- HTTP Admin Settings -->
<httpd httpd.enabled="1" httpd.cfg.enabled="1" httpd.cfg.port="80" httpd.cfg.secureTunnelEnabled="0" />

HTTPS Web access only:
<!-- HTTPS Admin Settings -->
<httpd httpd.enabled="1" httpd.cfg.enabled="1" httpd.cfg.secureTunnelPort="443" httpd.cfg.secureTunnelEnabled="1" httpd.cfg.secureTunnelRequired="1" />

Both HTTP and HTTPS web access: 
<!—HTTP and HTTPS Admin Settings -->
<httpd httpd.enabled="1" httpd.cfg.enabled="1" httpd.cfg.port="80" httpd.cfg.secureTunnelEnabled="1" httpd.cfg.secureTunnelPort="443" httpd.cfg.secureTunnelRequired="0" />

Note: If you would like to make the Web Admin harder for people to find, you can change the port number to something different from the default 80 or 443 settings. If you do this, you will need to change the Web Port setting in the settings screen of the tool to match your selected port.

In addition to enabling the web server in the phone you must also change the default password on the device as well. If you do not do this the phone will display errors/warnings on the phone display and web interface (“Default admin password is in use, please contact your administrator”). Passwords can be configured in the configuration file as follows:

<!-- Passwords and Security -->
<device device.auth.localAdminPassword="12345" device.auth.localUserPassword="12345" />

Note: Make these passwords whatever you want them to be, however, they must be different than the default of 456 in order to avoid the warning message being displayed on the phone screen.

After you have changed these settings the web login and phone screen login passwords will be changed. So if your support staff have been trained to enter the default “456” password, don’t forget to tell them that it has changed.

Enable REST API:

Config File Setting:

The following REST API setting must be enabled in order to use the Polycom VVX Manager Tool:

<apps apps.restapi.enabled="1" />

Web Interface Setting:

Settings -> Applications -> REST API

Note: If this setting is not configured you will receive "(404) Not Found" errors when trying to send commands to the phone.

Text Messaging Settings

In order to send messages to VVX phones you need to enable the Push settings in the configuration. You can do this with the following settings:

Config File Settings:
<apps.push apps.push.alertSound="1" apps.push.messageType="5" apps.push.serverRootURL="push" apps.push.password="vvxmanager" apps.push.username="vvxmanager" apps.push.secureTunnelEnabled="1" apps.push.secureTunnelPort="443" apps.push.secureTunnelRequired="0"></apps.push>

  • apps.push.messageType: This sets the level of messages that will be displayed for the phone. The VVX Manager always sets the messages as “critical” so they will always be received. The setting “5” means that all levels of messages will be displayed by the phone.
  • apps.push.serverRootURL: This setting needs to be set to "push". This is used as part of the URI for sending messages to the VVX.
  • apps.push.username: The phones use digest authentication for push connections. The username sent by the tool by default is “vvxmanager”. This can be changed in the Settings dialog in the tool.
  • apps.push.password: The phones use digest authentication for push connections. The password sent by the tool by default is “vvxmanager”. This can be changed in the Settings dialog in the tool.
  • apps.push.alertSound: Play a sound when the message is displayed. This is the standard Polycom sound that you hear when a phone reboots. This can help the user to see the message, as it will only be displayed for 30 seconds.
  • apps.push.secureTunnelEnabled: If 0, HTTPS is disabled for push. If 1, HTTPS is enabled for push.
  • apps.push.secureTunnelPort: Changes the HTTPS port number (default is 443).
  • apps.push.secureTunnelRequired: If 0, HTTPS is not required (ie. HTTP is also available). If 1, HTTPS is required for push (ie. HTTP connection is disabled). Note: if you try to connect using HTTP when this is set to 1 you will receive a "(405) Method Not Allowed" error.

Web Interface Settings:

Settings -> Applications -> PUSH

MAC Address Display

If you want to be able to remotely tell what the MAC address is of a phone (useful when building phone specific config files) from the VVX Phone Manager tool interface without having to open the web config, add the following setting:

<device sec.tagSerialNo="1">
   <prov device.prov.tagSerialNo="1"/>

This will result in the MAC address being included in the device string, eg: “VVX Version: PolycomVVX-VVX_500-UA/”. If you do this, the tool will also check the FTP server for individual MAC address files and tell you which phones have these when the “Test FTP” button is pressed.

Polycom VVX Manager Tool Settings

When connecting from the VVX Phone Manager you need to match the password that you configured in your phone with the tool. The settings can be entered into the tool by pressing the “Settings…” button:
  • REST Username: This setting is always set to “Polycom”.
  • REST Password: This setting needs to match the “device.auth.localAdminPassword” setting in your VVX phone. If the password is wrong and doesn't match your phone setting you will see "(401) Unauthorized" errors being returned from the phone when you try to send it commands.
  • PUSH Username: This setting needs to  match the “apps.push.username” setting in your VVX phone.
  • PUSH Password: This setting needs to match the “apps.push.password” setting in your VVX phone.
  • HTTPS: This needs to match your phone's configuration settings for “httpd.cfg.secureTunnelEnabled”
  • Web Port: This needs to match your phone's configuration settings for either “httpd.cfg.port” for HTTP or “httpd.cfg.secureTunnelPort” for HTTPS.
  • Monitoring DB Query Time: This setting determines how many months back in the monitoring database the tool will look for VVX phone registrations. By default this setting is 6 months, meaning that the IP Address of any VVX phone registered in the past 6 months will be scanned to see if it is still located at that IP Address. This setting can be increased if your VVX phones have not been manually signed out/in for longer than 6 months. Or if you have a site where users are frequently signing in and out of their VVX phones you can reduce this value to save time scanning old IP Addresses for VVXs. The setting can be set between 1-48 months (ie. from 1 month up to 4 years).
  • Discovery Wait Time: This setting allows you to tune the time that the tool will wait for responses from discovery messages sent to phones (setting between 200ms-1000ms). This can be helpful if you are trying to discover phones on a distant subnet with a high levels of latency.

SQL Requirements

In VVX Phone Manager 1.xx there was a requirement that SQL ports were opened on each Front End server for accessing information on phone IP Addresses (which work some of the time). This new version of the tool only requires access to the Monitoring database on the Lync / Skype for Business Backend SQL server in order to discover the IP Addresses of phones signed into the system.

Getting Started with a Polycom VVX Deployment

This article was written under the assumption that you already have VVX phones deployed, and you are now looking to manage them. If you need some more help with the initial deployment part of the process, I can point you to some useful resources:

Jeff Schertz' great post on the different ways to deploy Polycom phones is here: Provisioning Polycom SIP Phones. Greig Sheridan also has a nice post on Optimising the Polycom VVX for Lync that you might want to check out too.

If you would like to know more about what is supported on Lync with VVX phones and setting up a FTP server to support Polycom Configuration files on Lync, go to the Polycom VVX support page and grab a copy of the lovingly entitled: “Deploying Polycom® UC Software for use with Microsoft® Lync™ Server”.

An important recommendation that I can give you is to always test your configuration files on a real phone before deploying them into the wild, because subtle errors can cause things not to work as desired.

The Wrap Up

Well, that's it, my first version 2.0 script! Enjoy, and let me know if you have any issues, feedback or have any enhancement requests.

Read more →

Thursday, 2 July 2015

Skype for Business Address Book Normalisation Tool

The release of Skype for Business brings a new set of Powershell commands for controlling Address Book Normalisation rules. In previous versions of Lync, these rules were configured in the Company_Phone_Number_Normalization_Rules.txt file that was stored in the address book storage on the Lync share. This previous method was not particularly intuitive and prone to issues because of the text file format used.

So now in Skype for Business we have Powershell commands to make everything easier, right? Well, yes and no. I am not a big fan of having to memorise Powershell commands that will only be used rarely. Also, ideally it should be easy to see and change the priority order of the rules as well as test the rules with commands. However, the new commands don’t offer any testing facilities as yet; they require multiple list ups and are not intuitive for priority changes. So as Tim Allen used to say on Home Improvement: it’s Tool Time again…

Skype4B Address Book Normalisation Tool

Tool Features:
  • Import Existing “Company_Phone_Number_Normalization_Rules.txt” files into the system.
  • Add/Edit address book rules to the system. If the rule you are setting has a name that matches an existing rule, then the existing rule will be edited. If the rule’s name does not match an existing rule then it will be added as a new rule to the list.
  • Delete rules from the system.
  • Create new Site based Address Book Normalisation Rules policies.
  • Change the priority of rules.
  • Custom written rule testing code for testing pattern and translation matches as well as the resultant number.
  • Export rules back into a “Company_Phone_Number_Normalization_Rules.txt” file format.
  • Test the rules! Skype for Business currently (at the time of writing this) doesn’t have Address Book Normalisation testing capabilities. So I wrote a custom testing engine into the tool providing this feature. By entering a number into the Test textbox and pressing the Test Number button, the tool will highlight all of the rules that match in the currently selected Global/Site level Policy patterns in blue. The rule that has the highest priority and matches the tested number will be highlighted in red. The pattern and translation of the highest priority match (the one highlighted in red) will be used to do the translation on the Test Number and the resultant translated number will be displayed by the Test Result label.
Version 1.01 Update (13/10/2015):
  • Added warning message on the Remove policy button to save you from yourself :)
  • Removed second .txt from the export name.
Version 1.02 Update (20/1/2015):
  • Script now doesn't strip ";" char before applying regex. (Thanks Daniel Appleby for reporting)

Available on the TechNet Gallery:


Importing Company_Phone_Number_Normalization_Rules

The new Skype for Business address book normalisation Powershell commands offer a way to import previous Normalisation Rule files.  The command is called Import-CsCompanyPhoneNormalizationRules and will import the Pattern and Translation Rule directly into the new Skype for Business commands. In doing so, the import process will create a random GUID to be used as a unique name for each normalisation rule.

Import File Example:
# Internal 13 Extension numbers
# Internal 17 Extension numbers

Get-CsAddressBookNormalizationRule after import:
Identity    : Site:Melbourne/d8209928-5b07-44fa-9642-56285dbe72d1
Priority    : 0
Description :
Pattern     : ^13(\d{2})$
Translation : +6139999$1
Name        : d8209928-5b07-44fa-9642-56285dbe72d1

Identity    : Site:Melbourne/3cfd51ad-2be9-43ce-a87d-f223bdc755c6
Priority    : 1
Description :
Pattern     : ^(17\d{2})$
Translation : +6139999$1
Name        : 3cfd51ad-2be9-43ce-a87d-f223bdc755c6

The Address Book Normalisation Tool uses this same command to import address book files. As a result, you can expect to see the same operation as shown above. When the rules are imported into an existing scope that already contains rules the new normalisation rules will be added in addition to the existing rules. No existing rules will be deleted by the import process.

Rule Testing

In previous versions of Lync you used to be able to test rules using the Abserver.exe using the testPhoneNorm flag. The output of this command would tell you which Pattern in the Normalisation Rules file would be used by the system for the test number you supplied. The Address Book Normalisation Tool has a similar testing feature that will highlight all of the rules that match the tested number in blue and highlight the highest priority (ie. the actual rule the system will use to do the normalisation) rule in red. It will also show you the Pattern, Translation Rule, and exactly what the resultant number will be after translation.

Test Example:

The Wrap Up

Now Skype for Business Address Book Normalisation couldn't be any easier! I hope you find this tool useful and continue normalising for many years to come. Enjoy!

Read more →

Popular Posts