Page History

Excerpt
This tutorial will help you generate provisioning files for many phones using SystemAPI.

Table of Contents

maxLevel	3

Why Generate Provisioning Files

By using VoipNow's provisioning feature, you can set and maintain identical configurations for a large amount of equipment.

Suppose your office uses the same phone model for all employees. Automating the generation of provisioning files through SystemAPI would be an easy and elegant method to configure those phones.

Let's say you are the network administrator of an office with 15 employees. You're supposed to configure 15 Cisco terminals for them. Wouldn't it be nice to use a single script to generate provisioning files for all those phones?

You could very easily do that if you follow the steps below. Additionally, a report with the configuration link for every phone will be be generated for your own use.

Requirements

To generate bulk provisioning files for multiple phones using this example you need:

An access token; add an app to the VoipNow Platform following these instructions, then follow the steps described here to obtain the access token;
Set the provisioning system IP as detailed here;
A Phone Terminal extension for each employee;
The MAC address of every phone you want to provision;
The country code of your office.

How to Setup

Download the attached example and follow the steps below.

Column

width	20%

4psadownload

filename	generate_provisioning_files.php

STEP 1: Configure connection and Auth details.

To make a request to the VoipNow Platform API, a few variables need to be configured:

$IP - IP of the VoipNow server (including port);
$VERSION - Version of the VoipNow product;
$TOKEN - Authentication token;

Expand

title	Click here to see the code sample.

Code Block

language	php

/* IP of the VoipNow server (including port) */
$IP = "192.168.14.244"; //CHANGE
/* Version of the VoipNow product */
$VERSION = '3.0.0'; //CHANGE
/* Authentication token*/
$TOKEN= '1|y_J5vqVg4D.8qORSXbT-qnK3GHVB_XOM|1|1365672971|0-t01mDDGG_BXGJ8nwQ-wBMWXtjU~QO2'; //CHANGE

STEP 2: Set map of extensions to phone MAC addresses.

The map can be kept in an array that uses the extension number as key and the phone's MAC address as value.

Expand

title	Click here to see the code sample.

Code Block

language	php

/* Create an array having as key the extension number and as value the MAC address of each phone terminal */
$mac_array = array(
					'0003*001' => '00:18:B9:AA:BB:01',
					'0003*002' => '00:18:B9:AA:BB:02',
					'0003*003' => '00:18:B9:AA:BB:03'
			);

STEP 3: Configure country code.

Assuming your office is located in Rome, Italy, you should set $country_code to IT. The script will use the SystemAPI GetTimezone method to find the timezone ID.

Code Block

language	php

 $country_code='IT';

STEP 4: Set phone model.

Perform a SystemAPI request to get the phone model. Assuming you have to configure Cisco 7940 phones with firmware version 8.x, you should perform a request to GetEquipmentList method and obtain the required data from the response.

Code Block

language	php

$phone_model = X //Equipment unique ID
$firmware = Y  //Firmware unique ID
$protocol = Z  //Firmware protocol

Here is a snapshot from the GetEquipmentList response which contains explanations on how to get the required data according to the phone model:

Expand

title	Click here to see GetEquipmentList response

Code Block

language	html/xml

<!-- The response of GetEquipmentList SystemAPI method for a phone model: -->
...
<ns2:uniqueID>gmf6izchfvd14fg4xwc1pz9kv20t8eko</ns2:uniqueID>  <!-- This is the value for X in our example -->
<ns2:model>Cisco 7940</ns2:model>
<ns2:firmware>
    <ns2:uniqueID>sq8uondpcyzcf776sev7sv6vt8o82k1u</ns2:uniqueID>
    <ns2:name>7.x</ns2:name>
    <ns2:protocol>TFTP</ns2:protocol>
</ns2:firmware>
<ns2:firmware>
    <ns2:uniqueID>a9pzw3o92omhwtno7jwzf2v8ajhd3j8e</ns2:uniqueID> <!-- This is the value for Y in our example -->
    <ns2:name>8.x</ns2:name>
    <ns2:protocol>TFTP</ns2:protocol> <!-- This is the value for Z in our example -->
</ns2:firmware>
...

How It Works

STEP 1: Using the connection and auth details provided, create and authenticate the SoapClient.

STEP 2: Using the country_code variable, retrieve the needed timezone ID.

Expand

title	Click here to see a code example of how to get timezoneID.

Code Block

language	php

//example how to get timezone id

$country_code='IT'; // country code for Italy is IT
try {
	$request_timezone = array(
 							'code' => $country_code 
							 );
  	$timezone_result = $client->GetTimezone($request_timezone); // call SystemAPI GetTimezone method
 	$timezone_id = $timezone_result->timezone->ID;
} catch (SoapFault $exception) {
 	echo "ERROR: <br/>" . $exception->getMessage() . "<br/><br/>";
 	echo "REQUEST:<br/>" . htmlentities($client->__getLastRequest()) . "<br/><br/>";
 	echo "RESPONSE:<br/>" . htmlentities($client->__getLastResponse()) . "<br/>";
}

STEP 3: Get the phone model, firmware, and protocol.

Expand

title	Click here to see a code example of how to parse GetEquipmentList response.

Code Block

language	php

 /* Use GetEquipmentList method to find the code for your phone:*/
try {
    $equipment_list_result = $client->GetEquipmentList();
    
	/* Get an array of all equipments */
    $all_phones = $equipment_list_result->equipment;

	/* The data for Cisco 7940 phones */
    $cisco_phones = (array)$all_phones[6];

    /* Get Phone Model, Firmware and Protocol for model 8.x */
    $phone_model = $cisco_phones['uniqueID'];
    $firmware = $cisco_phones['firmware'][1]->uniqueID;
    $protocol = $cisco_phones['firmware'][1]->protocol;
    
} catch (SoapFault $exception) {
    echo "ERROR: <br/>" . $exception->getMessage() . "<br/><br/>";
    echo "REQUEST:<br/>" . htmlentities($client->__getLastRequest()) . "<br/><br/>";
    echo "RESPONSE:<br/>" . htmlentities($client->__getLastResponse()) . "<br/>";
}

STEP 4: Generate the provisioning files.
Iterate through each extension & MAC pair and generate the provisioning files for each device using SetProvision SystemAPI method:

Expand

title	Click here to see a usage example of the SetProvision method.

Code Block

language	php

 try {
		$request_provision = array(
                                        'extendedNumber' => $extension, //The provisioned extension
                                        'provision' => true, //Use provisioning
                                        'name' => 'provision for extension '.$extension, //Friendly name
                                        'phoneModel' => $phone_model, //Manufacturer
                                        'firmware' => $firmware,     //Model
                                        'protocol' => $protocol,     //Update protocol 
                                        'phoneMAC' => $mac,          //MAC address
                                        'timezoneID' => $timezone_id,          //Phone time zone
                                        'connectionType' => 'dhcp',  //phones connect using DHCP
                                    );
                  
                $provisioning_result = $client->SetProvision($request_provision);
                
                $file = $provisioning_result->location;  //The provisioning file address

            } catch (SoapFault $exception) {
                echo "ERROR: <br/>" . $exception->getMessage() . "<br/><br/>";
                echo "REQUEST:<br/>" . htmlentities($client->__getLastRequest()) . "<br/><br/>";
                echo "RESPONSE:<br/>" . htmlentities($client->__getLastResponse()) . "<br/>";
            }

STEP 5: Display links for the locations of the provisioning files.

Once the script has run a page listing each extension, the provisioning file is created. The list looks as shown below:

Expand

title	Click here to see how the report page is created.

Code Block

language	php

....
/* Construct the content of report page */
    $html = '<table border="1">
                <tr>
                    <th>Extension</th>
                    <th>MAC</th>
                    <th>File</th>
                </tr>
            ';
....
/* Create a row in table for each provisioned extension */
    $html .= '<tr>
                    <td>'.$extension.'</td>
                    <td>'.$mac.'</td>
                    <td>'.$file.'</td>
              </tr>'; 
....
$html .= '</table>';        

/* Write the content of $html variable in a file. Create a link towards this file */
$handle = fopen("phones_provisioning_files.html", "w");            
fwrite($handle, $html);
fclose($handle);
echo "The report was successful generated. You can find it <a href=\"http://".$_SERVER["SERVER_ADDR"]."/".dirname($_SERVER["SCRIPT_NAME"])."/phones_provisioning_files.html\">here</a>";

Panel

bgColor	#FFFFE0
titleColor	#FFFFFF
titleBGColor	#3c8501

Tips and Tricks

The country code is used to get the timezone ID so that the provisioned phones display the hour accurately.

Need Help?

Ask a question in our GetSatisfaction community.

Show all results

Space shortcuts

Page tree

Versions Compared

Old Version 6

New Version 7

Key

Why Generate Provisioning Files

Requirements

How to Setup

How It Works

Tips and Tricks

Need Help?