Grandstream Networks GXP2130 Series User manual

GXP2130/GXP2140/GXP2160 XML Phonebook Guide
Grandstream Networks, Inc.
GXP2130/GXP2140/GXP2160
XML Phonebook Guide

GXP2130/GXP2140/GXP2160 XML Phonebook Guide
GXP2130/GXP2140/GXP2160
XML Based Downloadable Phone Book Guide
Index
INTRODUCTION ........................................................................................2
WHAT IS XML........................................................................................................................................2
WHY XML ..............................................................................................................................................2
XMLAPI ARCHITECTURE....................................................................................................................2
XML PHONEBOOK CONFIGURATION.....................................................4
FIRMWARE............................................................................................................................................4
WEB CONFIGURATION........................................................................................................................4
LCD CONFIGURATION.........................................................................................................................6
PROVISIONING.....................................................................................................................................8
XML PHONEBOOK SYNTAX.....................................................................9
HEADER................................................................................................................................................9
PHONEBOOK XML STRUCTURE........................................................................................................9
PHONEBOOK XML ELEMENT ........................................................................................................... 11
ROOT ELEMENT <AddressBook>...............................................................................................11
<pbgroup> ELEMENT ..................................................................................................................11
<Contact> ELEMENT...................................................................................................................12
<Phone> ELEMENT.....................................................................................................................12
XML PHONEBOOK EXAMPLE................................................................13

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 1 of 15
Table of Figures
GXP2130/GXP2140/GXP2160 XML Based Downloadable Phone Book Guide
Figure 1: GXP2130/GXP2140/GXP2160 XML API via HTTP.......................................................................3
Figure 2: GXP2130/GXP2140/GXP2160 XML API Structure 1 ....................................................................3
Figure 3: GXP2130/GXP2140/GXP2160 XML API Structure 2 ....................................................................4
Figure 4: Web Configuration .........................................................................................................................5
Figure 5: Contacts->Local Phonebook..........................................................................................................7
Figure 6: XML Phone Book Download Soft Key ...........................................................................................7
Figure 7: Confirm to start XML Phone Book Downloading ...........................................................................8
Table of Tables
GXP2130/GXP2140/GXP2160 XML Based Downloadable Phone Book Guide
Table 1: <AddressBook> Element............................................................................................................... 11
Table 2: <pbgroup> Element.......................................................................................................................11
Table 3: <Contact> Element........................................................................................................................12
Table 4: <Phone> Element..........................................................................................................................13

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 2 of 15
INTRODUCTION
The Grandstream GXP2130/GXP2140/GXP2160 support XML based downloadable phone book for users
to share and maintain a phone book remotely easily.
For the ease of efficient deployment and management, the XML phone book file could be stored on a web
server for the phones to download. There are also applications that require a centralized directory server
and have all phones synchronized with the server periodically.
This document specifies the Grandstream XML based downloadable phone book configuration that will be
applied to GXP2130/GXP2140/GXP2160 firmware version 1.0.0.17 or newer. An example XML phone
book file is provided at the end of this guide. Users could start a phone book by adding contacts to the
example file or exporting the existed phone book file from phone's LCD.
WHAT IS XML
XML (eXtensible Markup Language) is a markup language* for documents and applications containing
structured information. This information contains both content (text, pictures, input box and etc.) and an
indication of what role that content plays (e.g. contents in a section header are different from contents in a
footnote). Almost all documents are structured.
*A markup language is a mechanism to identify structures in a document. The XML specification defines a
standard way to add markup to documents.
WHY XML
What benefits does XML provide to SIP endpoints? XML enables our SIP phones to serve as output
devices and allows the phones to interact with external applications in a flexible and programmable
manner.
XML API ARCHITECTURE
The XML based phone book downloading for the GXP2130/GXP2140/GXP2160 could use HTTP or TFTP
as the transport protocol. The following figure shows how it works via HTTP as an example. First, the
GXP2130/GXP2140/GXP2160 initiates the HTTP GET Request to the HTTP server and waits for the
response. Once the phone receives the response with XML content in BODY, it displays the information.

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 3 of 15
Figure 1: GXP2130/GXP2140/GXP2160 XML API via HTTP
Two types of XMLAPI architecture are introduced below, depending on whether the transaction is via LAN
or Internet.
1. A transaction in the LAN may exchange information in the following manner. The
GXP2130/GXP2140/GXP2160 sends a request to the web server via HTTP/TFTP and waits for a
response with the XML contents. The web server will handle the request and communicate with the
application server to get the information for the XML phone book content display. The following figure
shows downloading XML phone book file via HTTP within a LAN.
Figure 2: GXP2130/GXP2140/GXP2160 XML API Structure 1
2. If the above Web Server accesses Internet, it could interact with outside web server and respond with
real-time content to the GXP2130/GXP2140/GXP2160.

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 4 of 15
Figure 3: GXP2130/GXP2140/GXP2160 XML API Structure 2
As illustrated above, all the logic lies within the server side of the architecture. The
GXP2130/GXP2140/GXP2160 phone just receives the XML documents and displays it accordingly.
XML PHONEBOOK CONFIGURATION
FIRMWARE
Before the XML phone book is used on GXP2130/GXP2140/GXP2160, please make sure the firmware on
the phone is upgraded to the latest version. Please refer to the following link for firmware upgrading
information:
http://www.grandstream.com/support/firmware
WEB CONFIGURATION
User could configure phonebook download options by enter phone’s IP on web browser and go to
Phonebook->Phonebook Management.

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 5 of 15
Figure 4: Web Configuration
Enable Phonebook XML Download
The phone book XML file could be downloaded via HTTP or TFTP. Users could also set the option
“Enable Phonebook XML Download”to "Disabled" to disable phone book download.
XML Server Path
This specifies the path where the phone is going to download the XML phone book file. Since
download method is already specified in the previous selection, users do not have to provide this
information in the server path. The accepted formats are as follows:
IP_address[:port]/dir
Hostname[:port]/dir
Examples:
192.168.40.10/XMLphonebookdir
192.168.40.10:443/XMLphonebookdir
service.mycompany.com/XML/phonebook
mycompany.com:8080/phonebook
Note:
1. If "[:port]" is not specified, port 80 will be used as default for HTTP and Port 69 will be used as
default for TFTP;
2. The GXP2130/GXP2140/GXP2160 will always look for the phone book file phonebook.xml for
downloading if no file name is specified in the server path.

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 6 of 15
Phonebook Download Interval
This option specifies the phone book automatic download interval (in minutes). The valid value is 5 -
720. If it's set to 0, automatic download will be disabled.
Remove Manually-edited Entries on Download
If this option is set to “Yes”, when XML phonebook is downloaded, the manually-edited entries will be
deleted.
Download XML Phonebook
Click on Download button to download the XML phonebook from GXP2130/GXP2140/GXP2160 to
local PC. When the phonebook of GXP2130/GXP2140/GXP2160 is empty, the downloaded XML
phonebook will be in below format:
<?xml version="1.0" encoding="UTF-8"?>
<AddressBook>
<version>1</version>
</AddressBook>
Upload XML Phonebook
GXP2130/GXP2140/GXP2160 also support uploading XML phonebook from local PC.
Click on the button to choose XML file and upload.
Phonebook Key Function
This option controls the behavior of Phonebook Key. By default, Phonebook Key is the short cut to
enter the contacts sub menu. With this option, user can configure the Phonebook Key as LDAP
Search, Local Phonebook, Local Group or Broadsoft Phonebook.
LCD CONFIGURATION
To download the XML phone book file to GXP2130/GXP2140/GXP2160, go to LCD Menu-> Contacts->
Local Phonebook and press Download soft key to start downloading XML Phone Book.

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 7 of 15
Figure 5: Contacts->Local Phonebook
Figure 6: XML Phone Book Download Soft Key

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 8 of 15
Figure 7: Confirm to start XML Phone Book Downloading
PROVISIONING
Users may also use the config file to provision the phone with the above XML phone book downloading
options. In this case, the GXP2130/GXP2140/GXP2160 needs to be rebooted and provisioned. The
corresponding P values are as shown below.
P330: Enable Phonebook XML Download. Possible values: 1 (HTTP) / 2 (TFTP)/ 3 (HTTPS); other
values are ignored. The default value is 0.
P331: Phonebook XML Server Path. This is a string for the path to download the phonebook.xml file. It
MUST be in the host/path format.
P332: Phonebook Download Interval (in minutes). Valid range: 5 - 720; other values are ignored. The
default value is 0 (automatic download disabled).
P333: Remove Manually-edited Entries on Download. Possible values: 0 (No)/ 1 (Yes). The default
value is 1.
P1526: Phonebook Key Function. Possible values: 0 (Disable)/ 1 (LDAP Search)/ 2 (Local
Phonebook)/ 3 (Local Group)/ 4 (Broadsoft Phonebook); other values are ignored. The default value is
0.
The phone will be set up with the P values when the provisioning routine is completed. It will attempt to
download the phone book XML file specified in "Download Server" with configured interval and process it.
If the "Interval" is set to a non-zero value, a recurring timer will be activated periodically to check the phone
book file in the server and the phone will repeat this process automatically.

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 9 of 15
Note:
1. As you may know, it is also possible to enter the XML phone book file server path into a web
browser. In this way you’ll be able to see the exact XML document on your PC that your phone will
be receiving.
XML PHONEBOOK SYNTAX
HEADER
In the first line of the XML document, the following header can be set as XML declaration. It defines the
XML version and encoding. On the GXP2130/GXP2140/GXP2160, UTF-8 and GBK can be used as
encoding method for correct display. Example:
PHONEBOOK XML STRUCTURE
An XML phone book example for GXP2130/GXP2140/GXP2160 can be found in the last section of this
document. The main structure is represented as below.
<?xml version="1.0" encoding="UTF-8"?>
Group
Department
Phone
Frequent
LastName
FirstName
name
id
Contact
pbgroup
version
phonenumber
AddressBook
accountindex

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 10 of 15
<AddressBook>
<version>Enter version number here. Usually 1</version>
<pbgroup>
<id>Enter group id here</id>
<name>Enter group name here</name>
</pbgroup>
<pbgroup>
<!-- Enter another group information here, same format as above -->
</pbgroup>
<Contact>
<FirstName>Enter first name here</FirstName>
<LastName>Enter last name here</LastName>
<Frequent>Favorite contact or not</Frequent>
<Phone type="Specify phone type here">
<phonenumber>Enter phone number here</phonenumber>
<accountindex>Enter account index here</accountindex>
</Phone>
<Department>Enter department name here</Department>
<Group>Enter group ID here</Group>
</Contact>
<Contact>
<!-- Enter another contact information here, same format as above -->
</Contact>
</AddressBook>

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 11 of 15
PHONEBOOK XML ELEMENT
This section describes details of the XML element used in GXP2130/GXP2140/GXP2160 XML phone book
file. Please note that the element name is case-sensitive when being used in XML document.
ROOT ELEMENT <AddressBook>
<AddressBook> is the root element of the XML document. This element is mandatory.
Table 1: <AddressBook> Element
Object
Position
Type
Values
Comments
AddressBook
Root element
Mandatory
-
Root element of the XML document
version
Child element
Optional
Number
XML format version number. Usually 1.
pbgroup
Child element
Optional
-
Define groups.
Contact
Child element
Mandatory
-
Each contact is a phone book entry.
<pbgroup> ELEMENT
Table 2: <pbgroup> Element
Object
Position
Type
Values
Comments
pbgroup
Element
Optional
-
Each pbgroup is a group. More than 1
group can be defined
id
Child element
Optional
Number
To specify group ID.
name
Child element
Mandatory
String
Group name.
<AddressBook>
<!-- Enter phone book information here -->
</AddressBook>
<pbgroup>
<id>Enter group id here</id>
<name>Enter group name here</name>
</pbgroup>

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 12 of 15
<Contact> ELEMENT
Table 3: <Contact> Element
<Phone> ELEMENT
Note:
The possible values for <Phone> type are “Work”, “Home”and “Mobile”.
Object
Position
Type
Values
Comments
Contact
Element
Mandatory
-
Each contact is an entry
FirstName
Child element
Optional
String
Specify first name and last name. At least
one of them has to be specified.
LastName
Child element
Optional
String
Frequent
Child element
Optional
Number
0: Default
1: Mark this contact as frequent/favorite
Phone
Child element
Optional
-
Phone number information
Department
Child element
Optional
String
Specify Department name.
Group
Child element
Optional
number
Specify group ID for this contact.
<Contact>
<FirstName>Enter first name here</FirstName>
<LastName>Enter last name here</LastName>
<Frequent>Favorite contact or not</Frequent>
<Phone type="Specify phone type here">
<phonenumber>Enter phone number here</phonenumber>
<accountindex>Enter account index here</accountindex>
</Phone>
<Department>Enter department name here</ Department >
<Group>Enter group ID here</Group>
</Contact>
<Phone type="Specify phone type here">
<phonenumber>Enter phone number here</phonenumber>
<accountindex>Enter account index here</accountindex>
</Phone>

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 13 of 15
Table 4: <Phone> Element
Object
Position
Type
Values
Comments
Phone
Element
Mandatory
-
It has attribute "type".
type: Work/Home/Mobile/Fax/Other
phonenumber
Child element
Mandatory
Number
Phone number
accountindex
Child element
Mandatory
Number
From 0 to 5 for account 1 to account 6
XML PHONEBOOK EXAMPLE
<?xml version="1.0" encoding="UTF-8"?>
<AddressBook>
<version>1</version>
<pbgroup>
<id>1</id>
<name>Blacklist</name>
</pbgroup>
<pbgroup>
<id>2</id>
<name>Work</name>
</pbgroup>
<pbgroup>
<id>3</id>
<name>Friend</name>
</pbgroup>
<Contact>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<Frequent>0</Frequent>
<Phone type="Work">
<phonenumber>8001</phonenumber>
<accountindex>1</accountindex>
</Phone>
<Phone type="Home">
<phonenumber>3000001</phonenumber>
<accountindex>0</accountindex>
</Phone>

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 14 of 15
<Phone type="Mobile">
<phonenumber>1234567890</phonenumber>
<accountindex>0</accountindex>
</Phone>
<Department>Marketing</Department>
<Group>1</Group>
</Contact>
<Contact>
<FirstName>Michael</FirstName>
<LastName>Tsai</LastName>
<Frequent>0</Frequent>
<Phone type="Work">
<phonenumber>8002</phonenumber>
<accountindex>1</accountindex>
</Phone>
<Phone type="Home">
<phonenumber>3000002</phonenumber>
<accountindex>0</accountindex>
</Phone>
<Phone type="Mobile">
<phonenumber>1234567889</phonenumber>
<accountindex>0</accountindex>
</Phone>
<Department>Sales</Department>
<Group>2</Group>
</Contact>
<Contact>
<FirstName>Alex</FirstName>
<LastName>Smith</LastName>
<Frequent>1</Frequent>
<Phone type="Work">
<phonenumber>8003</phonenumber>
<accountindex>0</accountindex>
</Phone>
<Phone type="Home">
<phonenumber>3000002</phonenumber>
<accountindex>0</accountindex>
</Phone>
<Phone type="Mobile">
<phonenumber>2345678888</phonenumber>

XML BASED DOWNLOADABLE PHONEBOOK GUIDE Page 15 of 15
<accountindex>0</accountindex>
</Phone>
<Department/>
<Group>3</Group>
</Contact>
</AddressBook>
Note:
The maximum number of contacts supported on GXP2130/GXP2140/GXP2160 is 2000.