Cloud PBX: Polycom VVX Master Directory

2017-09-10 6 min read Cloud PBX Microsoft Office 365 Powershell Skype For Business System Administration Uncategorized Zachary Loeber

Reverse number lookup in Skype for Business online (cloud PBX) doesn’t give you much control. If you are deploying Polycom VVX phones you can get around this with a directory file.

Introduction

Migrating from an on premise PBX to pure Cloud PBX solution can be a bit painful. If you are smart you are at least choosing physical phones that don’t lock you down to a specific solution and are able to be bent to your will (er.. I mean customized to your environment). The Polycom VVX series phones are a prime candidate for such a migration for a number of reasons;

They are widely supported across several different cloud and on premise PBX solutions, Skype for Business Online being one of them.
They are extremely customizable
They have several models with various price points and features but with the same underlying software on the same release cycle.

In this article I’ll cover a workaround I’ve put in place for a PBX migration to Skype for Business Online, or simply ‘Cloud PBX’.

Setting the Stage

You have been tasked with eliminating infrastructure, including your aging PBX servers and equipment. As such, you have scoped out several Cloud based PBX solutions and have opted to go with Microsoft’s Cloud PBX solution. You already have all users on Office 365 and using Skype for Business. At this point you are moving forward with some user acceptance testing (UAT). Some user’s have been migrated to Cloud PBX from your on premise PBX. Their numbers were ported and Skype for Business has become their primary business phone. As already mentioned, Polycom VVX phones (specifically the 400 series model) have been selected to be provisioned for users.

The Problem

Every solution starts with a problem. If you are a smart solutionist they are genuine business problems and aren’t simply fabricated to scratch an itch. In this case the problem manifested itself when testing end user experience for users in a hybrid state of migration. The main issue is that when users in Cloud PBX receive a call from user’s who are on-premise it will not say who they actually are. It didn’t matter that all the numbers in Active Directory were normalized and synced to o365 via AAD Sync either.

The (partial) Solution

I came up empty handed researching the reverse number lookup methodology used in Cloud PBX. I’m not entirely certain if it is even possible to force RNL for different inbound calls but I do know that I can setup a directory of numbers when provisioning VVX phones. So at the very least these devices will show appropriate users for inbound calls from the on premise users. Additionally, I can add user’s mobile numbers and other special numbers for both reverse number lookup. Another bonus of doing this is that these numbers can also be searched via the phone’s built-in directory lookup for outbound calls. Sweet.

A holistic solution would also include possibly creating contacts for every user for special numbers (front desk, hunt groups, et cetera). I’m not willing to go that far though as this is a temporary situation until the migration to Cloud PBX is completed anyway.

Anyway, we need to create a ‘master’ directory that will get loaded to the VVX phones to cover all of our users

Source Numbers

In order to create the xml file used for the VVX devices I pull the following numbers from AD:

User telephone number (AD Property: telephonenumber)
User mobile number (AD Property: mobile)
User first name (givenname)
User last name (sn)

Additionally I’ll add in a few manual numbers for different hunt groups or other special numbers in the organization from a plain csv file with the following columns that align with the xml elements that eventually all of the directory entries will need to have:

ct – Contact (telephone number)
fn – First name
ln – Last name
lb – Label

This csv file might look something like the following:

<td valign="top" width="100">
  fn
</td>

<td valign="top" width="100">
  ln
</td>

<td valign="top" width="100">
  lb
</td>

<td valign="top" width="100">
  Front
</td>

<td valign="top" width="100">
  Desk
</td>

<td valign="top" width="100">
  Front Desk
</td>

<td valign="top" width="100">
  Help
</td>

<td valign="top" width="100">
  Desk
</td>

<td valign="top" width="100">
  Help Desk
</td>

Creating the File

Of course I use PowerShell to do this part of the solution, this is the kind of thing PowerShell excels at (and I excel at for that matter). Getting the data from AD can be done any number of ways. Some would use the ActiveDirectory module but since I’m crazy I have my own ADSI based module that I use called PSAD (PowerShell Active Directory). If you are on Windows 10 you can install it with the following

Otherwise you can download and install it on your system with the following:

The project site is here if you want more information (or want to contribute).

Anyway, you need to get your mobile and default telephone numbers from AD. As such, I ‘d highly recommend normalizing them all to the same format (starting with a +). I’ll leave that task to the reader but you can accomplish that with PSAD as well if you like.

Once you are ready you can create the directory xml file with the following script:

Implementation

Once you have run this file and created your directory file you will need to provision a phone with it. This is a bit easier said than done and there are restrictions. A good thread on the VVX directory files can be found here. Here is what you need to know in a nutshell though;

The initial directory provisioning file is 000000000000-directory.xml
As of firmware version 5.4 and above this file gets downloaded to the phone when it resets. After that you have to send a special SIP notify signal with check-sync event to the device to force it to download the file again.
Any prior version of firmware only gets downloaded once, ever. After then only a factory reset will kick off a download of the directory file again.
If the directory is changed on the device by the local user it will be saved individually as -directory.xml on the provisioning server and be merged with the master directory file when (or if) it is reprocessed.

So if you want to use a master directory like this you will need to have a functioning provisioning server to host it on. And if you want to use this more long term than initial deployment then you will have to schedule some manner of sending the SIP NOTIFY check-sync event to all your devices after updating the master directory file. And, of course, you will have to be running firmware 5.4+ on your devices.

That being said, if you want to script out sending the check-sync event I’ve gone ahead and added another function to my PSVVX module called ‘Send-VVXSIPNotify’ for this very purpose. I recommend checking it out if you have a few free cycles.