Snom Service Hub

Space shortcuts

Content

Page tree

Introduction

The directory settings XML tag (<tbook> or <phone-book) contains a list of contact entries to be provisioned into the internal phone directory.


Syntax

NOTE: The tags <tbook> and <phone-book> are equivalent: These XML tags can be used either

  • inside the <settings> tag:

    <tbook complete="true">
  <item context="<outgoing_SIP_identity>" type="<contact_category>" index="<contact_index(0)>">
   <name><contact_name</name>
   <number><contact_name></number>
  </item>
  ...
  <item context="<outgoing_SIP_identity>" type="<contact_category>" index="<contact_index(n)>">
   <name><contact_name</name>
   <number><contact_name></number>
  </item>
 </tbook>

  • or as an individual XML file whose URL is listed inside <setting-files> tag

    <?xml version="1.0" encoding="utf-8"?>
 <tbook complete="true">
  <item context="<outgoing_SIP_identity>" type="<contact_category>" index="<contact_index(0)>">
   <name><contact_name</name>
   <number><contact_name></number>
  </item>
  ...
  <item context="<outgoing_SIP_identity>" type="<contact_category>" index="<contact_index(n)>">
   <name><contact_name</name>
   <number><contact_name></number>
  </item>
 </tbook>

Where...

the following attributes are used:

  • e="2" defines that unicode-values inside xml-escapes (e.g. & # 6 4 ;) may be greater than 255.
  • complete="true" (since version 8.2.x), when this is provisioned, the phones knows that the provided tbook is complete and thus the previous one can be deleted (this is the only way to delete entries from the internal tbook via provisioning).
  • each item tag defines one directory contact entry and requires the following parameters:
    • context string defines the SIP identity (line/account) this contact should be called with, valid values are described in the formerly used configuration parameter "to"
    • type string defines the contact's category, valid values are described in the formerly used configuration parameter "tc"

    • index
      Since version 8.2.20 the index provided is used to change the specific entry at that index. Previously the tbook tried to match the entries provided to the internal entries via the given number string(and still does so when no index is provided), which allowed the provisioner to change everything but this phonenumber. Now with the help of the index even that can be done.
      Previously the tbook tried to match the entries provided to the internal entries via the given number string (and still does so when no index is provided), which allowed the provisioner to change everything but this phonenumber. Now with the help of the index even that can be done.

    • name string defines the contact's name, valid values are described in the formerly used configuration parameter "tn"
    • number string defines the contact's number, valid values are described in the formerly used configuration parameter "tu"
    • action_url (since 8.7.3.19) string defines the action URL to request when the phone receives or places a call with this directory entry.
  • Since 8.2.16 all snom phones have an enlarged tbook, which has new descriptions and more records (D120 = 2000; D3xx & D7xx= 2000). The minimal required parameter is the number, all other parameters are optional. Apart from those available in older versions,
    • these new parameters were added:
      • first_name providing a persons first name
      • last_name providing a persons family name
      • title providing a persons company title "like Head of Finances"
      • organization defines the organisation/company the person works for
      • email the persons email address
      • note a note
      • group either one of ""/"work"/"colleague"/"family"/"friend"
      • birthday the birthday in either dd.mm.yyyy or mm/dd/yyyy format
    • changed/new item-tag attributes:
      • type only provides either one of these contact types: ""/"VIP"/"DENY"
      • fav marks a person as favorite
      • number_type either one of ""/"sip"/"mobile"/"fixed"/"home"/"business"""
    • multiple numbers per person are achieved by defining a Master-entry, which sets up certain attributes that hold true for all its telephone numbers (like first_name and last_name) and 2 or more Member-entries. Please also look here to find an explanation on which attributes are valid for Masters and which for Members.
      • The Master-entry is defined through:
        • type="MASTER"
        • number=AnyUniqueNumber - must be one of the telephone-numbers of one of the members
        • Masters cannot define a context.
      • The Member-entries are defined by:
        • first_name=Member_Alias
        • last_name=UniqueNumberOfMaster
        • Members cannot define neither birthday nor fav-attribute.


Example

  • Example file name: http://domain/snomD3xx/directory.xml

    <?xml version="1.0" encoding="utf-8"?>
 <tbook>
  <item context="line1" type="none" index="0">
   <name>Adrian</name>
   <number>42965</number>
  </item>
  <item context="active" type="colleagues" index="1">
   <name>Roland</name>
   <number>16424</number>
  </item>
  ...
  <item context="line12" type="friends" index="99">
   <name>Suzy</name>
   <number>78371</number>
  </item>
 </tbook>

  • Example with master and member entries:

    <?xml version="1.0" encoding="utf-8"?>
<tbook e='2' complete="true">
  <item context="active" type='master' fav="false" mod="true">
    <!-- 
        the following tags can reside only in the master entry:
        * first_name
        * last_name
        * birthday
        * fav
    -->
    <!--
        the following tags can reside both in the master or in a member entry:
        * group
        * title
        * organisation
        * email
        * note
    -->
    <!--

        the following tags can reside only in a member entry:
        * name (this is just an alias for the number, not the person)
        * number
        * type
        * context (attribute of the 'item' tag meaning the outgoing identity)
    -->
    <name>Johnny</name>
    <!-- the number in the Master entry is used as an identifier linking referred by the Member entries -->
    <number>123</number>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <title>Mr.</title>
  </item>
  <item context="active" context="line2" type='' fav="false" mod="true">
    <!-- Member entry of the Master entry with number 123 -->  
    <last_name>123</last_name>
    <number>003912345678</number>
    <!-- in Member Entry should be "Member_Alias" -->
    <first_name>Member_Alias</first_name>
    <number_type>home</number_type>
    <title>Boss</title>
  </item>
  <item context="active" type='' fav="false" mod="true">
    <!-- Member entry of the Master entry with number 123 -->  
    <last_name>123</last_name>
    <number>003933812345</number>
    <!-- in Member Entry should be "Member_Alias" -->
    <first_name>Member_Alias</first_name>
    <number_type>business</number_type>
  </item>
  <item context="active" type='' fav="false" mod="true">
    <!-- Member entry of the Master entry with number 123 -->  
    <last_name>123</last_name>
    <number>003987654321</number>
    <!-- in Member Entry should be "Member_Alias" -->
    <first_name>Member_Alias</first_name>
    <number_type>mobile</number_type>
  </item>
  <item context="active" type='' fav='false' mod="true">
    <name>Adrian</name>
    <number>42965</number>
    <number_type>fixed</number_type>
  </item>
</tbook>

Alternatives to provisioning the internal directory

You may also use the XCAP capabilities of our phones which allow synchronizing the internal tbook with one from the net using simple http requests, see tbook-xcap-synchronization.


Further Information


Related articles