How do I create a phone provisioning template?

Introduction

If you have a phone for which no provisioning template is available, you can create your own template to be used by the provisioning system. Once the template is created, this will be used by the 3CX Phone system provisioning options.

Obtaining the text configuration file

The first step is to obtain the text configuration file for the phone that you want to provision. Generally, default phone configurations can be downloaded from the phone manufacturer’s site (e.g. GrandStream) or from the phone’s web interface (e.g. Snom). The configuration is usually a simple text file which also includes enough description to understand all the values listed in the configuration. If description is not provided with the default configuration, reference can be found or in the phone’s manual or in the phone manufacturer’s website.

Creating the template

Once you have such configuration, create the template as follows:

  1. Open another phone’s configuration template from [pbx install path]\Data\Http\templates\phones\[phonename.ph.xml], e.g. grandstream_gxp2000.ph.xml. Do not edit this xml file directly, but make a copy of it and edit the copy. Editing the text file directly could result in incorrect functionality of the provisioning and configuration generation.
  2. Optionally edit the following fields in the xml file:
    <version>3931</version>                            <-Template version number
    <time>2007-11-08 09:30:00</time>             <- Date of template generation
    <url>http://www.0tk.net</url>                      <- URL to manufacturer
    <image>grandstream.png</image>              <- Logo of manufacturer
    <description>GrandStream</description>      <- For reference use only
  3. In the xml file, replace the phone name to the new phone in the field  <name>. The name specified in this field, will be shown in the provisioning options in the PBX web interface.
    <name>GrandStream GXP-2000</name>
  4. It is possible to specify a parser that will pre process the templates. You can switch this off in most cases. Delete the following lines:
    <parsers>
    <parser>Grandstream</parser>
    </parsers>
  5. Field <deviceconfig filename> specifies the filename of the configuration which will be generated. Typically, phones requests a configuration named the same as their MAC address. In the example below, the configuration file generated is named cfg000413246674 (used from GrandStream), where 000413246674 is the MAC address of the phone entered in the provisioning configuration when creating a new extension. To check what filename your phone tries to retrieve in provisioning, please refer to the user manual.
    <filename="cfg%%mac_address%%">
  6. Now replace the current configuration between <![CDATA[ fields in the xml file with the default configuration of the new phone. Then replace the default values provided with the configuration with the variables listed below.
    • %%pbx_ip%%                        <-IP of PBX
    • %%apache_port%%                <- Port of 3CX Web Server
    • %%extension_number%%       <- Extension number
    • %%extension_auth_id%%        <- Authentication ID
    • %%extension_auth_pw%%      <- Authentication password
    • %%extension_first_name%%   <- First Name
    • %%extension_last_name%%    <- Last Name
  7. Now save the new template file and copy it to [pbx install path]\Data\Http\templates\phones\[phonename.ph.xml], where ideally the phonename in filename, should be the replaced by the model name of the phone. e.g. grandstream-gxp2000.ph.xml.
  8. When creating a new extension, now you can choose the new phone model from the list of models in the provisioning options.

Example

Below is an example from a GrandStream configuration and how it should look like, so when a new extension using provisioning is created, the PBX replaces the variable names with the actual data inputted by the user when creating the extension. For documentation purposes, only related data is shown in the below example.

<![CDATA[
P237= %%pbx_ip%%:%%apache_port%%/provisioning
P270 = %%extension_number%%
P47 = %%pbx_ip%%
P48 = %%pbx_ip%%
P35 = %%extension_number%%
P36 = %%extension_auth_id%%
P34 = %%extension_auth_pw%%
P3 = %%extension_first_name%% %%extension_last_name%%
]]>

Assuming that the new created extension is 100, the authentication ID and password are 100, first name and last name are John Doe and the PBX ip is 10.172.0.1, the generated configuration will be like the below.

  •P237= 10.172.0.1:5481/provisioning <- Where to retrieve configuration.
  • P270 = 100                                      <- Account name
  • P47 = 10.172.0.1                             <- Registrar
  • P48 = 10.172.0.1                             <- Outbound Proxy
  • P35 = 100                                        <- Extension Number
  • P36 = 100                                        <- Authentication ID
  • P34 = 100                                        <- Authentication Password
  • P3 = John Doe                                  <- First name and last name
 

General 3CX Phone System FAQs