Introduction

HTTP provisioning of phone sets is useful for an administrator as it helps to automate the process of configuring the phone set for a particular extension. The administrator creates the extension as usual, and in addition specifies the MAC address of the phone. 3CX includes ready phone provisioning templates for the most popular IP Phones in the market. However, in some cases companies wish to use other IP Phones and still use phone provisioning. In these cases you can create your own phone provisioning templates. This article explains how

Once the extension is created, a configuration for the specified phone set is created using the MAC address as the file name in the following directory:

For Windows XP / 2003:
%allusersprofile%\application data\3cx\data\http\interface\provisioning

For Windows Vista / 2008:
%allusersprofile%\3cx\data\http\interface\provisioning

The phone is then configured to download the configuration from this directory via the 3CX HTTP server on next start-up. During start-up no user action is required.

Note: This chapter describes the background to be able to customize phone provisioning templates. Information for users how to actually provision a phone is documented in the relevant phone configuration guide, for example http://www.3cx.com/sip-phones/Snom-provisioning.html

The Process

1. When a new extension is created, the following list of details should be entered in the “General” tab for the phone’s configuration files to be generated correctly:

• Extension Number (e.g. 100)
• First Name (e.g. John)
• Last Name (e.g. Doe)
• Authentication ID (e.g. 100)
• Authentication Password (e.g. 100)

2. When the “Phone Provisioning” tab is selected, the web server will look for the phone provisioning templates in the following folder:

For Windows XP / 2003: %allusersprofile%\application data\3cx\data\http\templates\phones
For Windows Vista / 2008: %allusersprofile%\3cx\data\http\templates\phones

Note that the 3CX Management Console includes an editor to adjust the template to customize the behaviour for all the phones. This will be discussed later in the section “Creating a Phone Provisioning Template”.

3. In the “Phone Provisioning” tab, you will need to enter

• The phone’s MAC Address (e.g. 000413246672)
• The phone model (e.g. Snom 320)
• The PBX’s IP Address which is on the same LAN as the phone (e.g. 10.172.0.2)
• Optionally, you can also configure up to 16 BLF entities for each extension

4. Click the “OK” button, and the 3CX Management Console will use the template to generate a configuration file (or files) specific to the phone, which will contain the information specific for this extension.
Once the user confirms the details and clicks “OK”, the details are passed to an XML template configuration and the 3CX Parser interprets the following variables as follows:

• Extension Number = %%extension_number%%
• First Name = %%extension_first_name%%
• Last Name = %%extension_last_name%%
• Authentication ID = %%extension_auth_id%%
• Authentication Password = %%extension_auth_pw%%
• Phone MAC Address = %%mac_address%%
• Phone model = <description>Snom 320 SIP Phone</description>
• PBX interface IP = %%pbx_ip%%
• …and possibly other variables as features are introduced from time to time

How to Build a Template File

The 3CX Management Console expects the template file to be in a particular format (XML), containing some compulsory elements, and some optional elements.

For this example, we will be creating a template file for a Snom 320 with Firmware version 8.x.
Please note that the template files supplied with the 3CX PhoneSystem are longer, containing more features, however the techniques used are identical.

The Baseline

This is, very simply, the bare minimum content to create a template file that simply creates a file containing “Hello World!” when used to provision a phone. This will not create a usable configuration file yet, but it describes the starting point.

Agenda:

• The portions highlighted in red are static content which must always be present.
• The portion highlighted in blue is the filename which the template will create inside the provisioning folder.
• The portion highlighted in pink is the actual content which will be placed inside the file created by the template, after parsing.
  Note that in the Baseline Template a “<![CDATA[" starting tag and a "]]>” ending tag is being used to encapsulate the contents to avoid the need to “escape” the contents – as would normally be required by HTML parsing mechanisms.

<?xml version=”1.0″?>
<doc xmlns:tcx=”http://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>

<model>MyPhone Model 111</model>

</models>

</header>
<data>
<device>
<type>phone</type>

<deviceconfig filename=“cfg%%mac_address%%“>
<![CDATA[Hello World!]]>

</deviceconfig>
</device>
</data>
</doc>

This Baseline Template file should be saved inside the phone provisioning templates folder with a unique filename that ends with “.ph.xml” – for example with filename “mysnom.ph.xml”.

.

The <models> Tag

1. The <models> tag encloses a list of all the phone models that the template will list in the “Model” dropdown in the “Phone Provisioning” tab of the Extension Configuration page.
2. There MUST be only 1 <models> tag.
3. The <models> tag can contain only 1 type of tag within it – the <model> tag.
4. Inside the <models> tag, there MUST be AT LEAST 1 <model> tag.
5. The <model> tag MUST contain the name of the Phone Model which will be added to the “Model” dropdown in the “Phone Provisioning” tab of the Extension Configuration page.
6. The <model> tag MUST NOT contain a name that conflicts with a <model> tag of another template which is already present in the phone templates folder.

.

The <deviceconfig> Tag

1. Each <deviceconfig> tag contains the specification of a configuration file which will be created in the provisioning folder for this extension.
2. There MUST be AT LEAST 1 <deviceconfig> tag.
3. Each <deviceconfig> tag MUST also specify a “filename” attribute. The value of the “filename” attribute MUST contain the filename which will be created in the provisioning folder.
4. The value of the “filename” attribute MAY contain 3CX-specific variables which will be substituted in the filename before creating the file in the provisioning folder. Note that the file created will overwrite any previously created file with the same name in the provisioning folder, so care is needed especially when using the “filename” attribute with a static value.Example of a <deviceconfig> tag with a dynamic “filename” value:
   <deviceconfig filename=”cfg%%mac_address%%”>
   …
   </deviceconfig>

   Example of a <deviceconfig> tag with a static “filename” value:
   <deviceconfig filename=”cfg_file”>
   …
   </deviceconfig>

• Anything contained INSIDE the <deviceconfig> tag WILL be the contents of the file that will be created in the provisioning folder.
• The contents of the <deviceconfig> tag MAY contain 3CX-specific variables which will be substituted inside the file content when creating the file in the provisioning folder.
• The contents of the <deviceconfig> tag MAY be encapsulated inside a “<![CDATA[" starting tag and a "]]>” ending tag to avoid issues with characters which would normally need escaping, such as “<” and “&”. This approach is recommended for its simplicity.

.

Commonly-Used 3CX-Specific Variables

3CX-specific variables all start and end with “%%”. Here follows a list of the 3CX-specific variables available for substitution within the “filename” attribute of the <deviceconfig> tag, or within the actual contents of the <deviceconfig> tag.

• %%rebootip%% – the IP Address of the phone. Using this variable is only recommended if the phones are assigned a Static IP Address, or have an IP Address reservation set on the DHCP server. If the phone can have different IP Addresses from time to time (typically in a DHCP environment without reservations), the %%rebootip%% variable may point to an invalid IP Address
• %%mac_address%% – the MAC Address of the phone as configured in the “Phone Provisioning” tab of the Extension. Typically used for generating device-specific filenames.
• %%pbx_ip%% – the IP Address of the 3CX PhoneSystem machine. Typically used, for example, to tell the phone where (to which IP address) to register with the PBX.
• %%pbx_http_port%% – the HTTP port and root folder. Typically used, for example, to tell the phone which HTTP URL to retrieve its configuration files from.
• %%extension_number%% – the phone’s extension number as configured in the “General” tab of the Extension. Typically used, for example, to tell the phone which identity it will use when registering with the PBX.
• %%extension_auth_id%% – the Authentication ID as configured in the “General” tab of the Extension. Typically used, for example, to tell the phone which credentials it will use to authenticate when registering with the PBX.
• %%extension_auth_pw%% – the Authentication Password as configured in the “General” tab of the Extension. Typically used, for example, to tell the phone which credentials it will use to authenticate when registering with the PBX.
• %%extension_first_name%% – the user’s First Name as configured in the “General” tab of the Extension. Typically used, for example, to tell the phone the name to display on its LCD.
• %%extension_last_name%% – the user’s Last Name as configured in the “General” tab of the Extension. Typically used, for example, to tell the phone the name to display on its LCD.
• %%vm_number%% – the Voice Mail Menu Extension Number as configured in the “General” tab of the “Settings -> General” page in the 3CX Management Console. Typically used to configure the voicemail button of a phone, when available.
• %%blf1%% … %%blf16%% – the Extension Numbers of the dropdowns boxes labeled 1 to 16 in the “Phone Provisioning” tab of the Extension. Typically used to set the BLF lamps for the phone, where available.

.

Creating A Real-Life Working Example for a Snom 320

This example will explain how to use the “Baseline” template specified above as a starting point, and build it up to a simple but functional phone template.
Documentation for setting a Snom configuration file is available from the Snom wiki site.

Starting with the Baseline Template for this model

For this example, we will assume that we want to name the model “MySnom 320″ – so the Baseline Template file would start looking like this:

<?xml version=”1.0″?>
<doc xmlns:tcx=”http://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>

<model>MySnom 320</model>

</models>

</header>
<data>
<device>
<type>phone</type>

<deviceconfig filename=”cfg%%mac_address%%“>
<![CDATA[Hello World!]]>

</deviceconfig>
</device>
</data>
</doc>

Checking the value of the “filename” attribute

The Snom phones allow you to use any filename for it to retrieve its configuration settings. So in this case we can choose any filename combination.

To ensure that each phone retrieves its own personalized settings, we should include inside the filename some variable that uniquely identifies the phone. The MAC Address of the phone is a perfect candidate for this, so the value of the “filename” inside the Baseline Template is fine for this. So if, for example, the phone’s MAC Address is “001122334455″, and this value has been set correctly in the “MAC Address” field in the “Phone Provisioning” tab for the Extension, the 3CX Management Console will create, inside the provisioning folder, a file called “cfg001122334455″ – after having substituted the %%mac_address%% variable.

.

Changing the contents of the <deviceconfig> tag

For a phone to successfully register and exchange calls with the PBX, the phone must have its first identity configured with, as a minimum:

• The Extension Number
• The Extension Authentication ID
• The Extension Authentication Password
• The IP Address of the PBX with which it will register and exchange calls

For the purposes of this example, we will also add an optional setting
The User’s First Name and Last Name to be displayed on the phone’s LCD

.

Settings for this Example

We will assume for this example that the information entered in the 3CX Management Console for this extension is:

• Extension Number – 113
• Extension Authentication ID – id_113
• Extension Authentication Password – pw_113
• The PBX IP Address – 10.0.0.11
• The User’s First Name – John
• The User’s Last Name – Doe

.

Correct Settings for the Configuration File

The Snom documentation states that the configuration file should contain the following:

• For the Extension Number: “user_name1$: 113″
• For the Authentication ID: “user_pname1$: id_113″
• For the Authentication Password: “user_pass1$: pw_113″
• For the IP Address of the Registrar (the PBX): “user_host1$: 10.0.0.11″
• For the LCD Display: “user_realname1$: John Doe”

.
Creating the <deviceconfig> tag for this Extension

Putting together the information from the previous section to build a <deviceconfig> tag, we can set:

<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[

user_name1$: 113

user_pname1$: id_113

user_pass1$: pw_113

user_host1$: 10.0.0.11

user_realname1$: John Doe

]]>

</deviceconfig>

…and the full template would look like this:

<?xml version=”1.0″?>
<doc xmlns:tcx=”http://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>
<model>MySnom 320</model>
</models>
</header>
<data>
<device>
<type>phone</type>
<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[
user_name1$: 113
user_pname1$: id_113
user_pass1$: pw_113
user_host1$: 10.0.0.11
user_realname1$: John Doe
]]>
</deviceconfig>
</device>
</data>
</doc>

However, since the above is static information, leaving the template file as-is will basically set all phones provisioned with this template to all have the same identity, with same extension number and all displaying “John Doe” on the LCD!

.

Converting a Static Template to a Dynamic Template

This is the final step – where we replace the static values with the 3CX-specific variables.

This will give us an updated <deviceconfig> tag:

<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[

user_name1$: %%extension_number%%

user_pname1$: %%extension_auth_id%%

user_pass1$: %%extension_auth_pw%%

user_host1$: %%pbx_ip%%

user_realname1$: %%extension_first_name%% %%extension_last_name%%

]]>

</deviceconfig>

…and the final template would therefore look like this:

<?xml version=”1.0″?>
<doc xmlns:tcx=”http://www.3cx.com”>
<header>
<type>phone-template</type>
<name></name>
<models>
<model>MySnom 320</model>
</models>
</header>
<data>
<device>
<type>phone</type>
<deviceconfig filename=”cfg%%mac_address%%”>
<![CDATA[
user_name1$: %%extension_number%%
user_pname1$: %%extension_auth_id%%
user_pass1$: %%extension_auth_pw%%
user_host1$: %%pbx_ip%%
user_realname1$: %%extension_first_name%% %%extension_last_name%%
]]>
</deviceconfig>
</device>
</data>
</doc>

Congratulations – you have created your first customized template file.

All that you need to do to use this template to create the settings file for your phone is to go to the relevant extension in the 3CX Management Console, go to the “Phone Provisioning” tab, enter the phone’s MAC Address and select the Model in the dropdown to be “MySnom 320″

.

Getting the phone to retrieve its settings file

You can get the phone to retrieve its settings automatically by following the instructions here

If you want to manually provision the phone, you should follow the instructions here