Archives

RFPS Remote Directory Import

Ringfree’s Provisioning System, known as RFPS, supports the ability to import a Remote Directory. The process itself is rather simple: from within the portal, navigate to the RFPS admin section for the VoIP Service you’re provisioning against. Once there, click the button labeled Import, and select Directories. A modal will appear asking to select a file. Select your file, then a preview will appear allowing you to confirm your data before sending it to the server. After verification,click the button labeled Import. If successful, you should see a green success banner in the upper left of your view.

While the process is incredibly simple, it’s imperative that the file to be imported is formatted in the proper manner. The importer requires a CSV file with a range of 3 to 5 columns in the following order and format:

  1. Directory Name: The name that will appear on the user’s phone for this directory.
  2. Contact Name: The name of the contact as it will appear in the phone’s directory.
  3. Phone Number: The primary contact number for the contact.
  4. Alternate Phone Number (OPTIONAL): An alternate contact number for the contact.
  5. Alternate Phone Number (OPTIONAL): An alternate contact number for the contact.
 You can download an example template here

Any additional fields will be ignored. Any rows with no value in an expected cell will also be ignored. Note that no fields should include any instances of the comma character as this will adversely affect the import and result in non-functioning extensions.

This file will only be applied to the current container, unlike the Bulk Extension Import function. You can, however, include multiple Directory Names to create multiple remote directories at once for that container.

There is a hard limit of 1,000 lines per Directory. If a customer has a contact list of 1,000 contacts or greater, it would be best to find logical break points to chunk the file into smaller bits.

RFPS Device Importing

Ringfree’s Provisioning System, known as RFPS, supports the ability to perform bulk configuration importing. The process itself is rather simple: from within the portal, navigate to the RFPS admin section for the VoIP Service you’re provisioning against. Once there, click the button labeled Import, and select Devices. A modal will appear asking to select a file. Select your file, then a preview will appear allowing you to confirm your data before sending it to the server. After verification,click the button labeled Import. If successful, you should see a green success banner in the upper left of your view.

While the process is incredibly simple, it’s imperative that the file to be imported is formatted in the proper manner. The importer requires a CSV file with 8 columns in the following order and format:

  1. Vendor: The maker of the device you are importing. e.g. Polycom, Yealink, etc.
  2. MAC Address: The MAC address of the phone. Use all lowercase letters where applicable and do not delimit the characters in blocks of 2 or 4.
  3. Phone Model: The model of the phone. Examples of acceptable values (sans quotes): ‘T18P’, ‘T19P’, ‘T21P’, ‘T40P’, ‘T41P’, ‘T42G’, ‘T46G’, ‘T48G’, ‘T49G’, ‘W52P’, ‘W56P’, ‘CP860’.
  4. Time Zone: The timezone name: eastern, central, mountain, or pacific.
  5. Extension: The extension number of the primary account on the phone.
  6. SIP Secret: The SIP Secret of the primary account on the phone.
  7. Label: The Label for the primary account on the phone as it appears on the device.
  8. Display Name: The Display Name for the primary account on the phone as it appears to other phones on the same PBX.

Any additional fields will be ignored. Any rows with no value in an expected cell will also be ignored. Note that no fields should include any instances of the comma character as this will adversely affect the import and result in non-functioning extensions.

Configuring a Yealink phone in the Yealink Configuration tool

Most new Yealink phones ordered from Ringfree authorized hardware vendors will come configured to work out of the box with the Yealink Configuration tool (We call it “YConf”). Or at the very least they’ll have the option available when the phones are being ordered. Phones that do not come configured for YConf will either need to be, or will require manual provisioning. Obviously its in the best interest of both Ringfree and the end user to have phones configured for YConf so that we can quickly and easily make provisioning changes in the future. Here are some example instances where phones would not be configured for YConf:

  • The phone is an obscure model that we don’t have a provisioning template for.
  • The customer already owned the hardware and is changing service to Ringfree.
  • The customer or IT partner sourced the hardware from a non-standard channel.

This article details how to take a Yealink phone and configure it for a particular CTID in the Yealink Configuration tool.


Obtaining the Phone’s IP Address and Accessing the Admin Interface

Connect the phone to the local network and power it on. Once the phone boots, locate and press the Menu key and then select the Status option, or, press OK in the middle of the directional pad. On most Yealink phones you should see the IPv4 address listed. Make a note of the address, enter it in the address bar of your preferred web browser, and navigate to it.

You should be presented with a login screen that notes the model of the phone and asks for a username and password. Enter the credentials as follows:

  • Username: admin
  • Password: admin

Click the Login button and you will be presented with the Yealink admin interface.

Note: The above credentials are ONLY for a factory reset phone.  Once a phone has been provisioned, the Username will be: ringfree , and the password will be shown in the configuration of the device, under heading Web UI Password.


Factory Reset and Necessary Security Settings

When setting up a new phone, its generally preferable to perform a factory reset. In fact you should always do this unless you’re explicitly instructed not to. The specific location of the factory reset option within the admin interface can vary depending on the specific model and firmware version but can generally be located by clicking the Settings option across the top and selecting the Upgrade option from the sidebar. The option is typically toward the center of the page.

Once the factory reset has completed, log back into the admin interface. At this point we need to adjust a security setting that will allow the phone to communicate with YConf. Click on the Security option across the top and select the Trusted Certificates option from the sidebar. On the resulting page, locate the setting labeled Only Accept Trusted Certificates, change it to Disabled, and then click the Confirm button to apply the change. The phone should reboot.


Obtaining and Applying the Provisioning Server Settings

Log back into the Admin Interface so we can address the provisioning server settings. Like the factory reset option, the specific location can vary according to model and firmware version, however the settings can generally be located by clicking on Settings across the top and selecting the Auto Provision option from the sidebar. The three settings we’re interested in on this page are labeled Server URLUser Name, and Password.

The Server URL is as follows: https://y.ringfree.biz/cfg/<CTID> with <CTID> being replaced by the customer’s PBX container ID. The CTID can be found at the top of the PBX Admin or Yealink Configuration view.  The User Name is just the customer’s PBX container ID. For example, the following settings would be entered to configure a phone for Ringfree’s PBX:

  • Server URL: https://y.ringfree.biz/cfg/1900027
  • User Name: 1900027

The password can, for established customers, be found in the Yealink Configuration tool at the large red Password button:

If you’re configuring a phone for a new customer you may need to establish a password within the Yealink Configuration tool. Please confirm with whomever is responsible for onboarding the customer prior to setting or changing the Yealink Configuration password.

Once the credentials have been entered, click the Confirm button at the bottom of the page. If you’ve already created an entry in Yealink Configuration for the phone, you may then click the Auto Provision Now button to provision the phone.

YConf Remote Directory Import

Ringfree’s internal Yealink provisioning tool, known as YConf, supports the ability to import a Remote Directory. The process itself is rather simple: from within YConf, click the button labeled Import, select Directory, select your file, and click the button labeled Import.

While the process is incredibly simple, it’s imperative that the file to be imported is formatted in the proper manner. The importer requires a CSV file with a range of 3 to 5 columns in the following order and format:

  1. Directory Name: The name that will appear on the user’s phone for this directory.
  2. Contact Name: The name of the contact as it will appear in the phone’s directory.
  3. Phone Number: The primary contact number for the contact.
  4. Alternate Phone Number (OPTIONAL): An alternate contact number for the contact.
  5. Alternate Phone Number (OPTIONAL): An alternate contact number for the contact.
 You can download an example template here

Any additional fields will be ignored. Any rows with no value in an expected cell will also be ignored. Note that no fields should include any instances of the comma character as this will adversely affect the import and result in non-functioning extensions.

This file will only be applied to the current container, unlike the Bulk Extension Import function. You can, however, include multiple Directory Names to create multiple remote directories at once for that container.

There is a hard limit of 1,000 lines per Directory. If a customer has a contact list of 1,000 contacts or greater, it would be best to find logical break points to chunk the file into smaller bits.

Yealink Centralized PhoneBook/SpeedDial

The Yealink series of phones support having a network-located repository of phone numbers used by a company or group of phones. There are two different types of directories that can be set up this way: a Remote Phonebook, or a network-stored Local Contacts. The term “Local” in this context can be a bit misleading since we are talking about a local copy on a server.

When To Use Each

There is one major difference between the two types; the network copy of the Local Contacts will overwrite the local copy of the Local Contacts, whereas the Remote Phonebook cannot be edited from the user’s phone. This immutability of the Remote Directory makes it easier to maintain and deploy at existing sites, while the Local Contacts may be a good fit for new installs that want to have a base directory of numbers on everyone’s phones.

General Configurations

At this time there is not an expedient way to just upload the XML file to the server, so you’ll need to use your ssh access to navigate there. Due to some security concerns, we’ve created a new file directory on the provisioning server for these centralized Phone directory files. Each container will have a folder in the /var/www/html/yealink/remdir/ location, e.g. /var/www/html/yealink/remdir/1900027/. Within this folder, you will create the XML files for the network-stored files.

Remote Phonebooks

The XML for the Remote Phonebooks is rudimentary and easy to recreate. Here is a sample of a Remote Phonebook XML file:

Yealink Remote PhoneBook XML Example

Once this file is created on the server, you will need to alter the configuration for the site’s phones. This can be done in each MAC address specific .cfg file or the common .cfg files that exist for each model of Yealink phone. Regardless of which file you decide to edit, the custom configurations will be the same. You will need to add the following to the configuration file:

features.remote_phonebook.enable = 1
remote_phonebook.data.1.url = https://remDir:aV29TxT@y.ringfree.biz/remdir/{containerID}/{PhonebookFileName}.xml
remote_phonebook.data.1.name = {PhonebookName}

You’ll need to replace the {containerID}, {PhonebookFileName}, and {PhonebookName} with the corresponding values.

Here is an image with the added custom configurations to illustrate:

Custom Configuration for Remote Phonebook

Network-Stored Local Contacts

The steps here are pretty much the same as for the Remote Phonebooks. You’ll create the XML file in the container inside /var/www/html/remdir/, e.g. /var/www/html/remdir/1900027/.
The XML content is different but still rather simplistic and looks something like this:

Yealink PhoneBook XML Example
You will then add the custom configurations to point to that newly created file by adding this line to the configuration file(s):

local_contact.data.url = https://remDir:aV29TxT@y.ringfree.biz/remdir/{containerID}/{PhonebookFileName}.xml

As before the {containerID} will need to be replaced with the container ID of the customer you are working with, and similarly, the {PhonebookFileName} will also need to be replaced. Once done, it should look something like this:

Custom Configuration Option for Yealink Phonebook

Once all of this has been completed, the phones will need a simple reboot/update. One thing to note is that the Remote Phonebook is a little bit buried in the menu. I will include an update soon to illustrate how to resolve that as well.

YConf Bulk Extension Importing

Ringfree’s internal Yealink provisioning tool, known as YConf, supports the ability to perform bulk configuration importing. The process itself is rather simple: from within YConf, click the button labeled Bulk Import, select a file, and click the button labeled Import.

While the process is incredibly simple, it’s imperative that the file to be imported is formatted in the proper manner. The importer requires a CSV file with a minimum of 9 columns in the following order and format:

  1. CTID: The numeric container ID of the PBX.
  2. Host name: The host name of the PBX. Do not prefix this with http:// or suffix it with a trailing slash.
  3. MAC Address: The MAC address of the phone. Use all lowercase letters where applicable and do not delimit the characters in blocks of 2 or 4.
  4. Phone Model: The model of the phone. Acceptable values are (sans quotes): ‘T18P’, ‘T19P’, ‘T21P’, ‘T40P’, ‘T41P’, ‘T42G’, ‘T46G’, ‘T48G’, ‘T49G’, ‘W52P’, ‘W56P’, ‘CP860’.
  5. Time Zone: The GMT offset time zone. For example Eastern Standard Time is ‘-5’.
  6. Extension: The extension number of the primary account on the phone.
  7. SIP Secret: The SIP Secret of the primary account on the phone.
  8. Label: The Label for the primary account on the phone as it appears on the device.
  9. Display Name: The Display Name for the primary account on the phone as it appears to other phones on the same PBX.

Any additional fields will be ignored. Any rows with no value in an expected cell will also be ignored. Note that no fields should include any instances of the comma character as this will adversely affect the import and result in non-functioning extensions.

Also note that you can import a configuration file for any PBX from anywhere within YConf. For instance you can import a file for 1900123 from the page for 1900027.

Yealink Provisioning in Papal and NetXUSA

Yealink phones support remote provisioning via a system Yealink calls Auto Provision. This can be configured in a number of ways. Here at Ringfree we have a Yealink provisioning server set up and configured to use HTTPS for Auto Provision. The provisioning server makes use of HTTP Basic Authentication in order to secure the configuration details.


netxusa.com

When ordering new Yealink phones from NetXUSA, the provisioning options can (and should) be specified prior to placing the order. To do this, after adding the phone(s) to your cart, but prior to checkout, use the Services dropdown on the cart page and select Configuration. This will bring you to the page with the provisioning options.

netx01

The precise location of the necessary provisioning options varies among the various phone models but are functionally all the same. Be sure that the selected template includes the words disable trusted, locate the option labeled PROVISIONING_SERVER and enter the following replacing <CTID> with the appropriate value:

https://y.ringfree.biz/cfg/<CTID>

Next location the PROVISIONING_SERVER_USERNAME field and enter the CTID. Finally locate the PROVISIONING_SERVER_PASSWORD and enter the password set on the provisioning server as described above. You may then save your changes and proceed with the order as normal.

netx02


Configuring a Yealink Phone Sourced Elsewhere

To configure a Yealink phone for Ringfree’s provisioning server that has been sourced from somewhere besides NetXUSA, steps need to be taken in order to ensure that the phone and the server can communicate properly. It is highly recommended that a phone sourced elsewhere be reset to factory settings and upgraded to the latest firmware version prior to proceeding with the following steps.

Most notably Yealink phones are, by default, configured to only communicate with trusted servers identified by loading a certificate into the phone. Given the relative inconvenience of loading a copy of the provisioning server certificate into each phone and the absence of any serious security threat, the option within the phone labeled Only Accept Trusted Certificates needs to be disabled. To do this, perform the following:

  1. Access the phone’s web interface by navigating to the phone’s IP address in a browser
  2. Log into the phone; the default username is admin and the default password is admin
  3. Click on the Security tab across the top
  4. Click on the Trusted Certificates option in the right sidebar
  5. Locate the Only Accept Trusted Certificates option and set it to Disabled
  6. Click the Confirm button to save the change and reboot the phone

Once completed, return to the phone’s web interface where you’ll now need to input the settings for the Auto Provision service:

  1. Click on the Settings tab across the top
  2. Click on the Auto Provision option in the right sidebar
  3. Locate the Server URL option and input the PROVISIONING_SERVER value from above; using Ringfree’s PBX as an example, the value would be https://y.ringfree.biz/cfg/1900027
  4. Enter the CTID into the field labeled User Name
  5. Enter the password as configured on the provisioning server into the field labeled Password
  6. Click on the Confirm button to save the changes

At this point the phone should be able to communicate with Ringfree’s provisioning server presuming that configuration files for that device have been generated.


Generating Configuration Files Within Papal

Papal contains a tool called YConf for generating configuration files for Yealink phones. To access YConf, navigate to the pbxadmin or pbxuser interface for the appropriate CTID and click the link in the header. Alternatively you can navigate directly to YConf using the following by replacing <CTID> with the appropriate CTID:

https://papal.ringfree.biz/pbx/<CTID>/yconf

papal01

Once loaded, you will have the option to add a new device configuration or you may click the appropriately labeled buttons to set a password or edit an existing configuration. If a password has not already been established for this CTID, please proceed to set one. Note that the passwords are encrypted when they’re stored so please make a note of the password somewhere reasonably accessible such as within the customer’s account notes. Setting a new password after one has already been established can prevent previously provisioned phones from being able to update so if you’re unsure as to whether or not a CTID has a password established already, please consult with John Knight or Kendall Weaver.

If adding a new configuration you will need to first input the device MAC address and specify the device model. The MAC address field is not case sensitive, but please enter it sans punctuation or delimiters.

papal02

Next enter the account information. It is advisable to follow any established conventions for the customer regarding the Label and Display Name fields. If there is no data for the Label and Display Name fields, simply enter the extension number into one or both as needed.

Scroll to the bottom and click the Submit button to save the configuration thus far. Once you’ve done so, you will see the option to configure additional accounts and/or Line Keys depending upon the particular options supported by the specific phone model. There is also a text area for custom configuration that is beyond the scope of this article.

papal04

The number of accounts is dependent upon phone model with some models supporting up to 16 accounts. Due to the relative rarity of needing multiple accounts, you may only enter up to one new account at a time.

When configuring the Line Keys, there are a number of options, not all of which are relevant to all line key types. To briefly describe the line key types:

  • Disabled – This disables the key, the remaining fields will be ignored.
  • Line – This key type instantiates a new phone call on the specified account or allows the user to quickly switch between multiple phone calls on the same or different accounts. This type accepts a Label but ignores the contents of the Value field.
  • Speed Dial – This key type instantiates a new call from the specified account to the number specified in the Value field. This number can be any valid number the account is capable of dialing. The Label field is also used.
  • BLF -The Busy Lamp Field key type is used to monitor the call status of the extension specified in the Value field and also works as a speed dial for that extension. The extension must be on the same PBX as the account specified. The Label field is also used.
  • Zero Touch – This key type is used to initiate the Auto Provision function and will cause the phone to download the current configuration files from the provisioning server. This type accepts a Label but ignores the Acct and Value fields.
  • Directory – This key type opens the directory stored on supported phone models. This type accepts a Label but ignores the Acct and Value fields.

Line keys can be dragged and dropped in the YConf interface. At present there is a bug in Firefox’s JavaScript engine which prevents changing the key type. This bug is not known to be present in other browsers.

Adding a Persistent Paging Button

Polycom phones using Ringfree service normally come with a Paging button that is available only while the phone is idle. Some users may occasionally find it inconvenient, impractical, or counter-intuitive to have the button only available while the phone is in an idle state, instead preferring to be able to pick up the handset prior to pressing the button. Fortunately Polycom phones support custom softkey configurations in such a capacity that the paging button can be made persistent in a variety of phone states.

Polycom phones using Ringfree service do not seem to support editing the softkey configuration using the .cfg files located within the PPT container as the local device configuration appears to override any softkey changes made there. Therefore in order to make changes to the device softkeys, it is necessary to log into the phone’s web interface. Once logged into the web interface, locate the Utilities menu and select the Soft Key Configuration option.

2016-03-14-123606_1249x870_scrot

Note that there are several default softkeys. Depending on configuration and firmware version there may be some combination of New CallTalkPagingForward, and *DND. Make a note as to whether or not there is a Paging button already as this will affect our configuration choices later on.

Click the Button labeled Add Soft Key and in the provided Label field, please enter Paging or another label as specified by the end user. Next locate the checkbox labeled Edit Macro Code and click to put a check in the box and reveal a field labeled Macro Code. In the Macro Code field, please enter the following:

$FPage$

Once done, click the Add Soft Key button a second time to add the soft key and click Yes in the confirmation box. The softkey configuation will then reload without the phone requiring a reboot.

At this point, go back to the Utilities menu and select the Import & Export Configuration option. When the page loads, locate and click the line labeled Export Configuration to expose the Export Configuration File option.

2016-03-14-125127_1249x870_scrot

From the Export Configuration File dropdown, please select All Configuration (except Device Settings) and click the Export button to download the file.

Once the file has been downloaded, open it with a text editor of your choice and search for softkey. You should find a section that appears similar to the following:

softkey.1.action="$FPage$"
softkey.1.enable="1"
softkey.1.label="Paging"
softkey.1.precede="1"
softkey.1.use.idle="1"

Note that the softkey may be identified by an integer other than 1 if there are other custom softkeys configured on the phone. Also note that the softkey.1.label field may contain a different string if you entered a different name for the button in the web interface.

The field that we’re most interested in here is the softkey.1.use.idle. Thought not immediately available within the file, there are a number of other softkey.1.use fields that define the availability of the button during the various states of the phone. If the phone you are configuring already has a Paging button, then we only need to add the new button to states other than idle, otherwise if the phone does not already have a Paging button, we can leave the idle state alone and simply add fields indicating additional states.

Here is a sample of what the config might look like with additional states if the phone already has a Paging button:

softkey.1.action="$FPage$"
softkey.1.enable="1"
softkey.1.label="Paging"
softkey.1.precede="1"
softkey.1.use.idle="0"
softkey.1.use.active="1"
softkey.1.use.alerting="1"
softkey.1.use.hold="1"
softkey.1.use.dialtone="1"
softkey.1.use.proceeding="1"
softkey.1.use.setup="1"

Note the additional states: activealertingholddialtoneproceeding, and setup. A value of 1 indicates that the button is available during that state whereas a value of 0 indicates that the button is not active during that state. Once you have adjusted the states to the required preferences, save the file and return to the phone’s web interface.

Locate the Import Configuration File field within the phone’s web interface and click the associated Choose File button. Browse your file system for the newly modified configuration file and then click the button labeled Import to upload the new configuration into the phone. Once the file is uploaded, the phone will reload the configuration and the newly configured button will be available. No reboot is required.

Setting the Default Transfer Method

The default transfer method for Polycom phones can be specified within the configuration files on the provisioning server. This feature was added to the Polycom firmware in version 5.3.0 so take care to note the firmware version for the CTID in question if you attempt to configure this. If the firmware version is not sufficient for supporting this feature, please consult with John Knight and/or Kendall Weaver to a firmware upgrade. An upgrade may not be feasible for all CTIDs as older phones may not support firmware version 5.3.0 or newer. You can verify the firmware version within the CTID home folder by running:

cat sip.ver

There are two options for setting the default transfer method: “Blind” and “Consultative”. Each can be set within the configuration using a single line of XML code. To set the default transfer method as “Blind” please use the following:

<call call.DefaultTransferType="Blind" />

To set the default transfer method as “Consultative” please use the following:

<call call.DefaultTransferType="Consultative" />

 

Either line of XML code can be injected into the appropriate configuration file for either an individual phone or for the entire CTID. There are a few best practices:

To set this in an individual phone, locate the file named with the extension number and the final six characters of the phone’s MAC address. Add the line of XML code on the second line from the end, directly above the </phone1> closing tag. Make sure the new line of XML code goes on its own line. You may then save and close the file and reboot the phone.

To set this across an entire CTID, locate and open the Config/site.cfg file. Add the line of XML code on the second line from the end, directly above the </polycomConfig> closing tag. Make sure the new line of XML code goes on its own line. You may then save and close the file and schedule a system-wide reboot of all the phones.

Occasionally you may find that the default transfer type has already been specified in individual phone configurations when you need to set the option system-wide or across multiple phones. In these cases it may be most beneficial to add a new configuration file. To do so, create a new file within the Config directory and name it appropriately:

nano Config/transfer-type.cfg

And place within it the following XML code adjusting the call.DefaultTransferType option as needed:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<polycomConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="polycomConfig.xsd">
 <call call.DefaultTransferType="Blind" />
</polycomConfig>

You may then add the new configuration file to the individual phones by editing the <mac>.cfg file for the intended phones and ensuring that the new configuration file is loaded last. Optionally you may use a text find/replace program such as sed to add the file to multiple phones simultaneously.