GXP Series - XML Phonebook Guide

The Grandstream GXP16xx/GXP17xx/GXP21xx support XML based downloadable phonebook for users to share and maintain a phonebook remotely easily.

For the ease of efficient deployment and management, the XML phonebook 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 phonebook configuration that will be applied to GXP16xx/GXP17xx/GXP21xx. An example XML phonebook file is provided at the end of this guide. Users could start a phonebook by adding contacts to the example file or exporting the existed phonebook 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 phonebook downloading for the GXP16xx/GXP17xx/GXP21xx could use HTTP or TFTP as the transport protocol. The following figure shows how it works via HTTP as an example. First, the GXP16xx/GXP17xx/GXP21xx 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.

Two types of XML API 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 GXP16xx/GXP17xx/GXP21xx 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 phonebook content display. The following figure shows downloading XML phonebook file via HTTP within a LAN.

2. If the above Web Server accesses Internet, it could interact with outside web server and respond with real-time content to the GXP16xx/GXP17xx/GXP21xx.

As illustrated above, all the logic lies within the server side of the architecture. The GXP16xx/GXP17xx/GXP21xx phone just receives the XML documents and displays it accordingly.

XML Phonebook Configuration

Firmware

Before the XML phonebook is used on GXP16xx/GXP17xx/GXP21xx, please make sure the firmware on the phone is upgraded to the latest version. Please refer to the following link for firmware upgrading information:

https://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.

• Enable Phonebook XML Download

The phonebook XML file could be downloaded via HTTP or TFTP. Users could also set the option “Enable Phonebook XML Download” to “Disabled” to disable phonebook download.

• HTTP/HTTPS Username

The username of the http/https server.

• HTTP/HTTPS Password

The Password of the http/https server.

• XML Server Path

This specifies the path where the phone is going to download the XML phonebook 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 or Hostname{:port]/dir

Examples:

• 192.168.40.10/XMLphonebookdir
• 192.168.40.10:443/XMLphonebookdir
• service.mycompany.com/XML/phonebook
• mycompany.com:8080/phonebook

• Phonebook Download Interval

This option specifies the phonebook 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.

• Import Group Method

When set to “Replace”, the existing groups will be completely replaced by imported one. When set to “Append”, the imported groups will be appended to the current one.

• Sort Phonebook by

Configures to sort phonebook based on the selection of first name or last name.

• Download XML Phonebook

Click on Download button to download the XML phonebook from GXP16xx/GXP17xx/GXP21xx to local PC. When the phonebook of GXP16xx/GXP17xx/GXP21xx 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

GXP16xx/GXP17xx/GXP21xx 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.

• Default Search Mode

Configures the default phonebook search mode.

LCD configuration

To download the XML phonebook file to GXP16xx/GXP17xx/GXP21xx, go to LCD Menu-> Contacts-> Local Phonebook and press Download soft key to start downloading XML Phonebook.

Provisioning

Users may also use the config file to provision the phone with the above XML phonebook downloading options. In this case, the GXP16xx/GXP17xx/GXP21xx 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.
• P6713: HTTP/HTTPS Username, empty by default.
• P6714: HTTP/HTTPS Password, empty by default.
• 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.
• P8462: Import group method, default is 0- Replace.
• P2914: Sort Phonebook, default is 0-sort by last name.
• 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.
• P2970: Default search mode, default is 0 – Quick match.

The phone will be set up with the P values when the provisioning routine is completed. It will attempt to download the phonebook 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 phonebook file in the server and the phone will repeat this process automatically.

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 GXP16xx/GXP17xx/GXP21xx, UTF-8 and GBK can be used as encoding method for correct display. Example:

<?xml version="1.0" encoding="UTF-8"?>

Phonebook XML structure

An XML phonebook example for GXP16xx/GXP17xx/GXP21xx can be found in the last section of this document. The main structure is represented as below.

<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

Phonebook XML element

This section describes details of the XML element used in GXP16xx/GXP17xx/GXP21xx XML phonebook 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.

<AddressBook>
<!-- Enter phonebook information here -->
</AddressBook>

<pbgroup> element

<pbgroup>
<id>Enter group id here</id>
<name>Enter group name here</name>
</pbgroup>

<Contact> element

<Contact>
<id>Enter-contact-Id-here</id>
<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>
<Primary>Enter-value-here</Primary>
<Department>Enter department name here</ Department >
<Group>Enter group ID here</Group>
<Job>Enter-job-here</Job>
<Company>Enter-company-here</Company>
</Contact>

<Phone> element

<Phone type="Specify phone type here">
<phonenumber>Enter phone number here</phonenumber>
<accountindex>Enter account index here</accountindex>
</Phone>

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>
<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>
<accountindex>0</accountindex>
</Phone>
<Department/>
<Group>3</Group>
</Contact>
</AddressBook>