Device Provisioning

Device Provisioning using Templates

While configuration can be performed by entering data into each phone, it is more efficient to use Configuration Manager's auto-provisioning feature which creates the configuration files a phone can download together with the required firmware.

To create these files for each phone, Configuration Manager uses Provisioning Templates which are combined with each phone's specific information. You can install the templates for the phone models you use, together with the manufacturer's firmware as Template Bundles.

During provisioning, Configuration Manager processes all the templates defined for the specified phone model, replaces variables it finds, and places the resulting files in the provisioning directory. Phones can download these files and firmware based on the options defined in Provisioning Settings.

Creating and Customizing Provisioning Templates

If you wish to customize existing provisioning templates or create new templates, you can place them in the directory /etc/asterisk/user_provisioning. You can further customize templates for each Tenant by placing the templates in /etc/asterisk/user_providioning/tenantname.

Do not place your templates in /etc/asterisk/provisioning directory as they will be overwritten whenever Configuration Manager is updated.

Templates locations have the following precedence:

1. /etc/astetrisk/user_provisioning/tenantname
2. /etc/asterisk/user_provisioning
3. /etc/asterisk/provisioning.

In earlier versions of Configuration Manager, file models.txt described the composition of templates for all the supported phones. In most recent versions, Template Bundles installation creates a separate directory under /etc/asterisk/provisioning/models.d where it places a file with model description settings for each phone supported by the bundle.

Here is what model description settings look like for Ploycom VVX 350:

[polycom-vvx350]
label=Polycom VVX 350
lines=1
check_sync=polycom-check-cfg
translationmap=polycom
phone_template=polycom_phone.cfg
line_template=polycom_line.cfg
blf_template=polycom_blf.cfg
speeddial_template=polycom_speeddial.cfg
output=${mac}-registration.cfg
input_1=polycom_mac.cfg
output_1=${mac}.cfg
input_2=polycom_local_uc.cfg
output_2=${TENANT}-settings-uc.cfg
command_1=/usr/local/sbin/generate_compdir_polycom.py ${TENANT}

Fields in the model description settings are as follows:

label. Phone model used to select this device model in Configuration Manager when setting defaults or when creating User Extensions.

lines. Number of lines this device supports.

check_sync. Command that will be sent to the phone after the provisioning files are generated.

translationmap. Translation Map used by this phone.

phone_template. Contains all the general phone information, i.e. other than the line or button specific entries.

line_template. The name of the file containing a template processed for each line. For example, if 3 lines are defined, then 3 copies of the entries in the line_template will be included in the final output file.

blf_template. The name of the file containing a template processed for each button designated as a BLF (Busy Lamp Field).

speeddial_template. The name of the file containing a template processed for each button designated as a Speed Dial.

output. The name of the generated configuration file for each provisioned device. Note that variables can be used as part of the file name.

The following entries can be specified more than once:

input_x. Any additional files that need to be processed.

output_x. The name of the file resulting from processing input_x. Note that variables can be used as part of the file name.

required_x. Specifies any files that Configuration Manager will simply move in the output directory without any substitutions. Typically, contains system wide configuration settings.

command_x. Command to be executed at the end of the provisioning for each device. This can be used to run special applications required by some phone manufacturers to load the configuration files. Note that variables can be used as part of the command.

Variables in model description and in the Provisioning Templates are specified as ${VARIABLE_NAME}` and are case sensitive.

The ${MAC} variable will be substituted by the MAC address in uppercase, while ${mac} will be in lowercase.

Here is the polycom_phone.cfg template referenced in the model description settings for Ploycom VVX 350 above:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <!-- $Polycom Revision: 1.67 $  $Date: 2005/03/11 17:05:46 $ -->
<PHONE_OVERRIDES>
  <OVERRIDES
${LINES}
${BLFS}
${SPEEDDIALS}
  />
</PHONE_OVERRIDES>

Note the ${LINES}, ${BLFS} and ${SPEEDIALS} variables. These will be replaced by the combined content of processed templates - line_template (polycom_line.cfg), blf_template (polycom_blf.cfg), and speeddial_template (polycom_speeddial.cfg) for each button configured.

You can add support for any phones not currently supported by Thirdlane or customize the templates as follows:

1. If adding a new model create a models.txt file in /etc/asterisk/user_provisioning directory and add an entry for the device model you want to add.
2. Create the templates (or change the existing templates) and place them in the same directory. Note that you are not required to create blf_template and speeddial_template files unless you use them.

Here is a list of variables that can be specified in model descriptions and the provisioning templates, and how they will be substituted:

${MAC}. Device MAC address in uppercase.

${mac}. Device MAC address in lowercase.

${SERVER}. Server address.

${TENANT}. Tenant name (Multi-Tenant only).

${TENANT_ID}. Internal tenant id (Multi-Tenant only).

${LABEL}. Usually first name and the last name from the User Extension screen.

${COMPANY_NAME}. Name on the license (Licensed to).

${LINE_KEYS}. Number of lines specified in model description.

${LINES}. Content of processed line_templates.

${BLFS}. Content of processed blf_templates.

${SPEEDDIALS}. Content of processed speeddial templates.

${STATION_NAME}. Caller id name.

${VOICEMAIL_NUMBER}. Extension.

${USERID}. Line name as specified in User Extensions.

${PASSWORD}. Phone password as specified in User Extensions.

${DISPLAY_NAME}. Caller id name.

${EXTENSION}. Extension.

${NAT_MAPPING}. Yes'/'No'' depending on NAT setting in User Extensions.

${NAT_KEEPALIVE} 'Yes'/'No' depending on NAT setting in User Extensions.

${BUTTON}. Button number as specified in Tools -> Auto-Provisioning.

${LINE}. Button number as specified in Tools -> Auto-Provisioning (it is the same as $ {BUTTON} and is kept for backward compatibility. You should use $ {BUTTON} for new templates.

${BUTTON_ZERO_BASED}. Button number - 1. This is useful when buttons are zero based as in snom phones.

${DISPLAY_NAME}. Caller id name.

${LINE_LABEL}. Line label as per Managed Device screen below.

${LABEL}. Line label if non blank (if specified on the Managed Device screen below ) or caller id number.

${BLF_LABEL}. Label for a BLF button as per Managed Device screen below.

${BLF_TARGET}. BLF target as per Managed Device screen below.

${SPEEDDIAL_LABEL}. Label for a Speed Dial button as per Managed Device screen below.

${SPEEDDIAL_TARGET}. Speed Dial target as per Managed Device screen below.

Managed Devices

If MAC address is specified when User Extensions are created either in Bulk Generator or individually, the configuration files are generated automatically, and MAC is added to the Managed Devices.

If you use Bulk Generator, you must specify the default Phone Model in Default Values or in Tenants if using Multi Tenant.

To generate configuration files and provision devices in bulk, select them using the check box on the left and click on "Provision Selected".

Create/Edit Managed Device

The screen allow you to further refine auto-provisioning information and assign behavior to phones' buttons as needed.

MAC Address. Phone' s MAC address.

Description. Short description.

Phone Model or Extended Phone Template. Select Phone Model from the list of supported models or Extended Phone Templates.

Time Zone. Time zone for this phone. Time zone will be translated based on the Translation Map for this Phone Model.

Template Variables. Allows you to specify values for the variables defined in the Translation Map for this Phone Model. These variables will be converted to internal values based on Translation Map for selected Phone Model

Add Account. Add a line to this phone.

Assign. Assign functionality to a phone button. Note that in order to assign various button types such as BLF, Speedial, etc you must have corresponding template files (blf_template, speeddial_template, etc) for the selected Phone Model.