GXP Series - XML Phonebook Guide

  • Updated on June 10, 2022

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.

Figure 1: GXP16xx/GXP17xx/GXP21xx XML API via HTTP

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.
Figure 2: GXP16xx/GXP17xx/GXP21xx XML API Structure 1

  1. 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.
Figure 3: GXP16xx/GXP17xx/GXP21xx XML API Structure 2

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.

Figure 4: GXP21xx Web Configuration
  • 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
Note

  • If “[:port]” is not specified, port 80 will be used as default for HTTP and Port 69 will be used as default for TFTP;
  • The GXP16xx/GXP17xx/GXP21xx will always look for the phonebook file phonebook.xml for downloading if no file name is specified in the server path.

  • 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.

Figure 5: GXP21xx Contacts->Local Phonebook
Figure 6: GXP21xx XML Phonebook Download Soft Key
Figure 7: GXP21xx Confirm to start XML Phonebook Downloading

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.

Note

As you may know, it is also possible to enter the XML phonebook 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

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>

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 phonebook entry.

<pbgroup> element

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

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.

<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>

Object

Position

Type

Values

Comments

Contact

Element

Mandatory

Each contact is an entry

Id

Child element

Optional

Number

Specify the contact id

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

Job Title

Child element

Optional

String

Specify the job title of the contact

Frequent

Child element

Optional

Number

0: Default

1: Mark this contact as frequent/favorite

Phone

Child element

Optional

Phone number information

Primary

Child element

Optional

Number

Specify If the number is primary

Department

Child element

Optional

String

Specify Department name.

Group

Child element

Optional

number

Specify group ID for this contact.

Job

Child element

Optional

String

Specify the job of the contact

Company

Child element

Optional

String

Specify the company of the contact

<Phone> element

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

The possible values for type are “Work”, “Home” and “Mobile”.

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>
<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>
Note

The maximum number of contacts supported on GXP16xx is 1000 and on GXP17xx/GXP21xx is 2000.

Was this article helpful?

Related Articles

Need Support?
Can’t find the answer you’re looking for? Don’t worry we’re here to help!
Contact Support

Leave a Comment

We use cookies in order to give you the best possible experience on our website. By continuing to use this site, you agree to our use of cookies.
Accept