Customising Polycom button configuration

26 Apr
April 26, 2015

One of the pieces of work I’ve been doing recently has been to reconfigure our standard Polycom handset template for our sales team. I was asked for a few specific features for them and some specific button layouts to make life easier. We then couple this with a little bit of training and they then get access to some of the power of the BroadWorks system that we run.

Unfortunately, configuring customised button layouts for Polycom phones are neither simple nor fun and there’s not a lot of information out there, so this post is all about some of the work I did.

This is going to be a long blog post so I’ve hidden the detail below, click down to read on.

For reference the handset I was using was a Polycom Soundpoint IP 450 running the Polycom UCS firmware version 4.0.7. This is interworking with a BroadWorks R20 platform.

I won’t go through the basics of configuring DMS or how to get the basic SIP side working – all that is already working in our templates.

If you’re not familiar with the Polycom template format then read the documentation first – you can start with this BCP on configuring using the Master Configuration File, but ultimately you’ll end up at the Administrator Guide for the firmware you’re running.

Let’s assume you’ve got the basics set up and the device configured in BroadWorks; your phone is pulling a configuration down and you don’t have any local files on the phone that conflict or override. What next?

Well, if you open your config files you’ll notice that it’s kind-of XML, just not very logical:

An example of the polycom configuration file format.

Example of the Polycom configuration format


Essentially, everything is stored in attributes. Once those XML purists among us have finished ranting, the rest is actually quite readable. The configuration files can be split up to whatever scheme suits your application and there’s no particular order for the XML attributes – more than that, there’s no particular requirement for the XML tag to be anything in particular. For example, here’s another piece of configuration I tidied up:


Screen Shot 2014-10-01 at 17.03.04

As you can see, I’ve used XML tags that make it easier for the maintainer to understand what the values are used for. The Polycom software doesn’t seem to care, giving you quite a lot of artistic license here (even though it leaves a bad taste in my mouth, but hey, you work with what you’ve got right?).

Each model is slightly different depending on the capabilities of that phone, for example the IP450 has four soft keys and three line keys. With the exception of the IP 331, most of the functionality is similar – the 331 is missing some buttons that the higher phones have and as a result certain functions work differently.

First of all, we need to understand the states that a phone can be in – there are seven possible states for the display depending on what you’re doing at that time. Here’s a little diagram depicting the states and transitions:

A flow diagram showing the various states that a Polycom IP phone screen transitions through.

For each of these states, you need to decide what buttons you want to appear. Before you start, however, go through each of these states and see what’s there already. The defaults are normally quite reasonable so it’s good to see if you can use them. There are a number of settings that can influence the defaults – they’re documented in detail in the manual, so I won’t go through them here.

So, having looked over your buttons, you decide that you want to add a button that uses the BroadWorks Group Pickup function. You want it to only appear on the idle screen and you want it to appear on the far left, before any other button. Here’s the config that you end up with:


So, what’s going on here?

The action keyword here defines the macro that’s going to get executed. In BroadWorks terms, that’s quite simple – it’s just a FAC that BroadWorks sets for us. The enable and label attributes are pretty obvious. Precede is a little interesting – Polycom has a defined order in which keys are presented, but precede overrides them all. Precede places this function on the first available button. The next 7 attributes correspond to the statuses in the diagram above – you can turn this button on or off for each status. This is pretty useful, right? Define it once and re-use it? Absolutely, however it does make reading the config pretty complicated.

The power here is in the actions attribute – you can define several different types of actions such as Macros, actions, digits, a contact entry or a chained list of actions and dial strings. The possibilities here are endless and they’re surprisingly well documented – you should read through all the possible options before deciding how you’re going to proceed – there’s quite a few ways of achieving what you’re going to try to do, normally.

The one key piece of information that’s missing though is something that will make you very carefully review your  options  –  the number of possible softkey definitions you have in your config is limited to 12. With 4 EFK buttons and 7 states on an IP450, we’re already up to 28 buttons if you want to fill out the buttons. The template I started creating above ran into this limit pretty quickly, so I had to shuffle things around a little.

There is one ray of sunshine here – Polycom provides a set of commonly used buttons which you can enable or disable. They appear before other softkeys configured, but after any softkeys set with “precede”.


The phone will drop those in the appropriate menus where they make sense, saving you a softkey slot for your own custom settings.

I hope this has been useful – the Polycom config can be a bit of a beast to get your head around. If you’ve had similar experiences, feel free to leave a comment below.




0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.