My Teams Lab

It’s time to update a classic tool that hasn’t had much love for a while. The tool was previously called the Skype for Business VVX Phone Manager Tool. Since this tool was originally created, many things have changed: VVX’s have been superseded by Poly CCXs, and Skype for Business by Microsoft Teams. It was time to get coding and bring this old tool forward to support some new scenarios like supporting CCX phones and Teams SIP Gateway for VVX/Trio devices. Here I present you, the Poly Phone Manager 4:

Poly Phone Manager 4

4.00 Release

Now works in conjunction with Teams SIP Gateway (see the Teams SIP Gateway section for more details).
Now works with Poly CCX Phones running on Skype for Business.
You now don't need access to Skype for Business PowerShell to discover devices with the Network Discovery method. You can discover devices from any Windows PC using IP Address discovery.
Updated to support both with PowerShell 5 and 7+
The Web Config button will now use the default browser for Windows rather than IE
Many other bug fixes and improvements

DOWNLOAD FROM GITHUB

Teams SIP Gateway

Teams SIP Gateway offers you the ability to connect certain Standards based SIP phones directly to the Microsoft Teams service. This includes all the Poly VVX phones and Trio 8500 and 8800.

The Poly Phone Manager 4 supports the ability to discover these devices over the network using network discovery. It is recommended that before running the tool in the PowerShell window you first run “Connect-MicrosoftTeams” and log the PowerShell window into a Teams PowerShell session with your tenant. If you do this you will get all of the User Information and Policy Information filled in in the details pane.

You can discover devices on your local network using the IP Address Range based network discovery method. If they are not signed into the Teams SIP Gateway then they will show up in the tool as a not logged in device (e.g VVXNotLoggedIn@10.0.0.238). If they are logged in then they will show up as their E.164 formatted phone number (e.g +61398736222@10.0.0.238) by default:

Example Phone Number Format:

You can also make Teams Standard SIP Gateway devices show up as the AAD Display Name if you choose to by changing the “Teams SIP Gateway Format” setting:

Run the discovery again and the phones will be displayed as the Display Name of the user from AAD:

Example User Name Format:

Once the tool has discovered the phone you can do all the usual functions available in the tool.

A fun thing you can also do with this tool is remotely sign in Teams SIP Gateway devices. When you initially connect the phone to the SIP Gateway it will be in a “Signed Out” state. From here you can use the “Screen..” button to look at the screen and press the “Sign In” button using the touch screen function of the tool. From here you will see the sign in code:

Note: This is not the most efficient way of doing this. If you want to do this more easily then use my Poly VVX – Teams SIP Gateway Tool (https://www.myteamslab.com/2022/02/poly-vvx-teams-sip-gateway-tool.html).

Teams Phone Software on CCX

Poly CCX phones support both Skype for Business and Microsoft Teams Phone Software modes. When in Teams Phone Edition mode, the phones do not (technically) support the REST API interface (which this tool uses for the majority of its functionality). In addition to this, the Teams Phone Edition doesn’t use SIP (it uses HTTP based signaling) and therefore cannot be discovered by the tool using its SIP based discovery method. As a result, don’t expect the tool to work with Poly CCX phones running in Teams mode (unless you were to do something silly like turn on the REST API using a config file and then load the Teams phones into the tool using the CSV import with rescan disabled… because it probably isn’t worth it).

Prerequisites for Using This Tool

Web Server Settings

In order to use this tool you will need to edit some basic configuration settings on your phones (usually done via configuration files but can also be done on individual devices via the phone interface). The following configuration file settings can be used to control web access to the phone:

Web Config Mode	httpd.cfg.enabled	httpd.cfg.secureTunnelEnabled	httpd.cfg.secureTunnelRequired
Disabled	0	0	0
HTTP Only	1	0	0
HTTPS Only	1	1	1
HTTP/HTTPS	1	1	0

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:

HTTPS Web access only:

Both HTTP and HTTPS web access:

<!—HTTP and HTTPS Admin Settings -->

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:

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. 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 Poly Phone Manager Tool:

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

To send messages to Poly phones using the tool 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 Poly Phone 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 phone.
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 Poly Phone Manager tool interface without having to open the web config, add the following setting:

</device>

This will result in the MAC address being included in the device string, eg: “Version: PolycomVVX-VVX_500-UA/5.0.0.6874_0004f28038f9”. 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.

Poly Phone Manager Features

Below is a description of the main features of the Poly Phone Manager Tool:

Phone discovery – Phones can be discovered either by automatically querying the 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: "192.168.0.1-192.168.0.20" OR "192.168.0.0/24" OR add multiple with comma separation "192.168.0.0/24,192.168.1.0/24"). During the discovery process, phones that are logged in to user accounts will be listed in the users list. If the tool finds a phone that is not signed in, it will be added to the user list under the name “<device type>NotLoggedIn@<IP Address>”. This allows you to use the tool to access these devices even though they are not signed into the system.

Important Note: The Poly Phone Manager Tool uses the registration database within the 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 phone 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 phone 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, Skype for Business Server, and MAC Address (if available) for all phones. If you select the "More" checkbox you will also get the additional Skype for Business policy settings for each user (this is slower).

Access Web Interface - Access the web interface of a Poly 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 on Skype for Business. This feature is not available on Teams SIP Gateway.

Send Text Messages - Send text messages to be displayed on a Poly 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.

Note: Sending messages relies on the PUSH interface being enabled on the phone in order to accept the message. See the “Prerequisites for Using This Tool” section for more detail of this configuration.

Get More Info – By pressing the “More Info” button you can get extended information about a Poly 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.

Sign in / Sign out devices - Selecting sign in will open a dialog that allows for either AD Authentication or PIN Authentication. Selecting sign out will sign out the phone from Skype for Business. This is not available for Teams SIP Gateway deployments (but you can use the Screen method mentioned earlier in this post).

Dial / End Call – You can choose to remotely dial a SIP URI (eg. john.smith@domain.com or +61395551111@domain.com) 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. The tool will automatically try and set the settings required in the device to allow the connection for displaying the screen. Once the window is closed, the tool will disable these settings so that the phone does not get overloaded by the screen display background processing.

When the phone screen is displayed, you can save screenshots of the screen as JPG files (If you want to make GIFs then use my other tool here: https://www.myteamslab.com/2020/10/teams-phone-screen-capture-tool.html) if you so desire. You can also click on the screen and do simulated swipes by clicking and dragging on the screen. For VVX phones have a home button available you will get this displayed as well. The key and text fields shown for some devices allow you to type inputs into text fields on the screen such as password dialogs:

VVX Screen

CCX Screen

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:

.\PolyPhoneManager4.00.ps1 -WebPortInput 443 -UseHTTPSInput false -AdminUsernameInput AdminUsername -AdminPasswordInput AdminPassword -PushUsernameInput PUSHUsername -PushPasswordInput PUSHPassword -IPRangeInput "192.168.0.1-192.168.0.200"

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

Note: Check out the Poly Phone Manager Tool Settings Screen for more detail on all these settings.

Bulk PIN Authentication

The bulk PIN authentication feature is only available for Skype for Business deployments and allows you to sign in multiple devices (that are currently signed out) using their respective extension and PIN numbers. This feature is useful for if you are deploying a site and require all the phones be logged in the day after the cutover before staff arrive at work. Another scenario might be that you want to sign in new starters phones at the time when you initially set their PIN number to allow them immediate access to their phone.

Phones that are signed out will be displayed in the interface as “<Phone Type>NotLoggedIn@<IP Address>”. Any Skype for Business phone that is in this state will be eligible to be displayed within the Bulk PIN Authentication window when it’s opened. Below is an example of what the Bulk PIN Authentication window looks like when it’s first opened:

Note: You will need the REST API enabled on devices that you want to be displayed in the Bulk Authentication interface.

Once the Bulk PIN Authentication window is open you need to assign Extension and PIN numbers to each device. To do this you can choose to import a CSV file with this information in it to fill in the table. Or you can manually do it with the Extension/PIN text fields and Update Row button. Once you have added Extension and PIN numbers to a row it will change colour to green. Lines that do not have an Extension and PIN will be ignored when you run the Bulk Authentication process.

To use the CSV import you need to create CSV file with the following headers:

MAC Address,Extension,PIN

0004f28038f9,1006,1234

64167f8023b1,1007,1234

0004f280df8b,1008,1234

You will need to know the MAC address of the phone devices to create the CSV file. So it’s important to have good records describing where devices are deployed within the organisation.

After Extensions and PIN numbers have been added for the required devices you click the “Run All” button and the sign in process will begin. The sign in process runs in parallel for all devices. The tool will poll the devices to check if the sign in process has completed. Once finished the results will be reported back for each device in the Result column.

The results can be exported with the “Export Results...” button in CSV format for future records.

Poly Phone Manager Tool Settings Screen

When connecting from the Poly 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 the 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 the phone.
PUSH Password: This setting needs to match the “apps.push.password” setting in the 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 Poly phone registrations. By default this setting is 6 months, meaning that the IP Address of any Poly 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 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 Poly phones you can reduce this value to save time scanning old IP Addresses for Poly phone. 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.
Teams SIP Gateway Format: The format that the devices are listed as (either Phone Number or User Name).

The Wrap Up

Okay, there we go, a big revamp to an old favourite. I hope you get some use out of this tool and it brings your everlasting joy and happiness.

My Teams Lab

Tuesday 16 August 2022

Poly Phone Manager 4