Page tree
Skip to end of metadata
Go to start of metadata

Overview

The provisioning feature offered by VoipNow allows you to automatically set up the SIP equipments that have Phone terminal extensions assigned to their line(s) using specific templates. This important functionality helps setting and maintaining identical configurations for a large number of remote devices.

VoipNow includes the configuration settings for all the supported brands, models and firmware versions in the Server default provisioning template. Using the available controls, you can customize an existing device's preferences according to your own requirements by modifying its corresponding configuration template and, if necessary, you can add new devices by importing their setup .xml files.

This knowledge base article describes the steps that you have to follow when you want to create a configuration template for a new device.

Requirements

Before you start, make sure you meet the following requirements:

  • VoipNow Professional 2.5.1 or any subsequent version.
  • Good XML knowledge.
  • Awareness of the device's specific settings.

Configuration templates usage

The Server default provisioning template contains the configuration templates of all the devices supported by VoipNow.

You can add new device models by importing their configuration templates directly from the web interface. These templates contain, besides the device's configuration options, all the other parameters required to provision the equipment.

You can also use the import tools to update the existing devices' configuration templates with your own customized versions. To do so, you simply have to download an existing template, modify it according to your requirements and upload it again from the VoipNow web interface. To download a certain template, follow the next steps:

STEP 1: Go to the Unified Communications > Provisioning templates page.

STEP 2: Click the icon available in the E(dit) column corresponding to the Server default provisioning template.

STEP 3: Choose from the list the device whose configuration parameters you want to customize or the one closest to the new model you want to add to the system and click its corresponding icon from the E(xport) column.

STEP 4: Save the configuration .xml file on your disk.

How to create a configuration template

All the configuration templates can be imported only if they follow the default format as detailed in this example and in the online help.

When the upload is unsuccessful, VoipNow displays an error message that points to the exact problem, helping you address it efficiently.

The steps you have to follow are:

STEP 1: Open your favorite text editor (e.g. Notepad++, jEdit).

STEP 2: In order to be able to upload a customized configuration template in the system, you must make sure that the .xml file will have the default structure:

 

<provision>
  <template>
    <file>	
      <name>tpl_name.xml</name>
      <default>0/1</default>

      <body>	
      <![CDATA[  
       .
       .
       . 
      ]]>
      </body>
    </file>
		
    <equipment>
     .
     .
     .					
    </equipment>
  </template>    	
</provision>

Each one of the two main sections contains specific information that have to be provided:

    • The template name, its type and all the configuration parameters specific to the device that you want to provision are included between the <file> </file> tags.
    • The device identification details like brand, model, number of supported lines, time zone, firmware are grouped between the <equipment> </equipment> tags.

STEP 3: The following parameters must be present in the first section:

    • <name>tpl_name.xml</name> - The template name, usually related to the device type/model that it is using these settings (e.g. spa508g.xml).
    • <default>1/0</default> - This parameter shows if the template is the default one (0) or it was customized (1). In our case, it must be set to 1.
    • <body> </body> - All the configuration settings (e.g. NAT and SIP settings, call features, subscriber information, audio configuration, etc.) specific to the chosen device must be included in this section.

      The <body> </body> section content depends on the device type. Make sure you are aware of all the required settings or else the provisioning might be unsuccessful!

      The settings specific to each device and required for the automatic configuration can be found on the internet.

      Below you can find a schematic example for a Cisco SPA-508G phone device:

      <file>
        <name>spa508g.xml</name>
        <default>1</default>
      
        <body>	
        <![CDATA[  
          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <flat-profile> 
      
          <!-- Cisco SPA-508G Configuration Parameters --> 
           .	
           .
           .
          </flat-profile>
        ]]>
        </body>
      </file>

STEP 4: All the parameters from the second section must be present in all the configuration files, regardless the device type:

    • Each device has an unique identification number stored in the database, included in the <equipment> tag (e.g. cddb32b1f7f86472ac200d10106f1094).

      You do not have to manually add this if not present as it is automatically generated for each device when the template is uploaded in the system!

    • <brand>device_brand</brand> - The device manufacturer (e.g. Cisco).
    • <model>device_model</model> - The device model (e.g. SPA-508G).
    • <type>device_type</type> - The device type (e.g. phone).
    • <vendor>vendor_id</vendor> - The label that identifies the device manufacturer, usually the first three letters of his name (e.g. cis).
    • <oui>device_id</oui> - The device's identification number (e.g. 002699).
    • <lines>lines_number</lines> - The maximum number of extensions that can be assigned to the device (e.g. 8).
    • <web_access>1/0</web_access> - You must set this parameter to 0 if the device cannot access the internet and to 1 if it can.
    • <vn_timezone> </vn_timezone> - The mapping between the VoipNow extension(s)' time zones and the phone device's time zones is done using this structure. You must include it in the configuration template only if you want to provide time zone support in the VoipNow web interface. The following parameters are required:
      • <timezone_option>1/0</timezone_option> - This option controls the availability of the time zone selector. If set to 0, the time zone selector will not be displayed in the VoipNow web interface.
      • <phone_timezones> </phone_timezones> - These are all the valid time zones available on the phone device and that can be selected in the interface. The parameters for each time zone are included between the <phone_timezone> </phone_timezone> tags:
        • <phone_tag> </phone_tag> - The time zone's identification details. A time zone description can be also added in order to be displayed in the interface. The following details are available:
          • <template_var name="TIMEZONE">time_zone_code </template_var> - The name of the template variable that will be replaced, usually the three letters time zone code (e.g. CET).

            The <template_var> parameter is different based on the template you want to generate, for example, for Aastra devices, you can have:

            <template_var name="AASTRA_TZ_NAME">NL-Amsterdam</template_var>
            <template_var name="AASTRA_TZ_CODE">NLX</template_var>
            <template_var name="AASTRA_TZ_MINUTES">60</template_var>
            
          • <vn_mappings> </vn_mappings> - The standard time zone key. If it is missing, the interface cannot provide any hints:
            • <vn_map>region</vn_map> - It is possible that a phone tag to be valid for multiple standard time zones and therefore you must specify all of them thin these tags.

      If enabled, you can find the time zone options in the VoipNow interface as follows:

      • When adding a new SIP device for which the time zone support was included in its configuration template (in the Unified Communications >> Manage SIP devices >> Add new device >> Device Settings section).
      • When provisioning a device with time zone support directly from the Provisioning and SIP Preferences page of the Phone terminal extension to which you want to assign it.
    • The details about the device's firmware are grouped between the <firmware> </firmware> tags:
      • Each device has an unique firmware version identification number stored in the database, included in the <equipment> tag (e.g. 51731d509ffc7ece8ccd5a03576a84b7).

        You do not have to manually add this if not present as it is automatically generated for each device when the template is uploaded in the system!

      • <name>firmware_version</name> - The device's firmware version (e.g. 7.4.4).
      • <interface>protocols</interface> - The protocols used by the selected device to access the configuration files on the provisioning server.

      Below you can find an example for the same Cisco SPA-508G phone device:

      <equipment id="cddb32b1f7f86472ac200d10106f1094">
      <brand>Cisco</brand>
      <name>Cisco</name>
      <model>SPA-508G</model>
      <type>phone</type>
      <vendor>cis</vendor>
      <oui>002699</oui>
      <lines>8</lines>
      <web_access>1</web_access>
      <vn_timezone>
        <timezone_option>1</timezone_option>
        <phone_timezones>
          .
          .
          .
          <phone_timezone>
            <phone_tag description="GMT+02:00 Athens, Rome EET (Eastern European Time),
            MEST (Middle European Summer Time), ">
            <template_var name="TIMEZONE">EET</template_var>
              <vn_mappings>
                <vn_map>Europe/Berlin</vn_map>
                <vn_map>Europe/Zürich</vn_map>
                <vn_map>Europe/Gibraltar</vn_map>
                <vn_map>Europe/Rome</vn_map>	
                 .
                 .
                 .
              </vn_mappings>
            </phone_tag>
          </phone_timezone>
          .
          .
          .
        </phone_timezones>
      </vn_timezone>
      <firmware id="51731d509ffc7ece8ccd5a03576a84b7">
      <name>7.4.4</name>
      <interface>tftp,http</interface>
      </firmware>
      </equipment>

STEP 5: After you have defined all the required parameters, you can save the data as a .xml file (e.g. spa508g.xml).

How to upload the configuration template

Now that you have defined the preferences for your desired SIP device, in our example Cisco SPA-508G, you can upload the template from the VoipNow web interface:

STEP 1: Log in to your administrator account.

STEP 2: Go to the Unified Communications > Provisioning Templates page.

STEP 3: Click the icon available in the E(dit) column corresponding to the Server default provisioning template.

STEP 4: Next, click the Import template icon.

STEP 5: Use the Browse button to locate the recently created configuration template.

STEP 6: Once decided, click OK to upload the file in the system.

If the file you are trying to upload does not match the default template structure, then it will not be saved to the database. A warring message will be displayed:

Failed to import the templates due to error: {error_cause}

Also, if you try to import a file different than .xml, you will be informed that:

Failed to import the templates because the file type is incorrect. Only XML files are allowed.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.