Snom Service Hub

Content

Page tree



Provisioning Local Directory (NEW XML FORMAT)

Provisioning the local directory can be done in two ways when utilizing xml files.

  1. Create a regular settings file and included a <tbook> inside it. Please set the version to 2.0 for the new format.

    Inside <Settings> tag 
    <settings> 
<tbook complete="true" e='2' version='2.0'>
  <contact fav="true" vip="true" blocked="false">
    <first_name>Anne</first_name>
    <last_name>Meyer</last_name>
    <title>Dr</title>
    <organization>MSW</organization>
    <email>ann@msw</email>
    <note>a note</note>
    <group>work</group>
    <source_id>A value between 1-12, please see below</source_id>
    <photo>a base64 encoded photo image</photo>
     <numbers>
      <number no="444" type="business" outgoing_id="0">
        <action_url>action-url</action_url>
      </number>
      <number no="445" type="extension" outgoing_id="0">
        <action_url>action-url2</action_url>
      </number>
      <number no="446" type="fixed" outgoing_id="0">
        <action_url>action-url3</action_url>
      </number>
    </numbers>
  </contact>
  <contact fav="false" vip="false" blocked="true">
    <first_name>Paul</first_name>
    <last_name>Meyer</last_name>
    <title>Dr</title>
    <organization>MSW</organization>
    <email>paul@msw</email>
    <note>a note</note>
    <source_id>4</source_id>
    <numbers>
      <number no="334" type="home" outgoing_id="0">
      </number>
      <number no="335" type="sip" outgoing_id="0"/>
    </numbers>
  </contact>
 </tbook> 
</settings>

  2. Create a separate xml settings file and included in your list of <settings-files>

    Individual XML file whose URL is listed inside <setting-files> tag 
    <?xml version="1.0" encoding="utf-8"?> 
<tbook complete="true" e='2' version='2.0'> 
etc.
</tbook>

Explanation of Local Directory XML Tags and Attributes

Attribute / TagValid ValuesExplanation
<tbook>
The tbook tag defines the directory itself.
e2Defines that unicode-values inside xml-escapes (e.g. &#64;) may be greater than 255.
completetrue / falseWhen this is provisioned, it indicates 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.
version2.0Indicates the new XML format
<contact>
Each contact tag defines one local directory contact
attribute: fav
  • true
  • false
Defines whether the current contact is a Favorite or not. This affects the list when filtering for favourite contacts.
attribute: vip
  • true
  • false
Defines whether the current contact is a VIP or not. 
attribute: blocked
  • true
  • false
Defines whether the current contact is a blocked one or not. 
<first_name>
Specifies the first name of the contact.
<last_name>
Specifies the family name of the contact.
<nick_name>

Specifies the Nickname of the contact.  The nick_name is not supported any more (Versions  > 10.1.162.1).

If the nick_name is present, and first_name and last_name are empty, the nick_name will be interpreted like this:

What was previously entered in the field is now separated at the last space and stored in first_name/last_name. If there is no space in the name, the name is interpreted as a last name.
I.e., Name: Klaus Maria Brandauer: -> first_name Klaus Maria, last_name: Brandauer
    Name: Helena Bonham Carter:  -> first_name Helena Bonham, last_name: Carter
    Name: Elan -> last_name : Elan
    Name: Musk -> last_name: Musk
This change is not visible until a contact is open for editing. (Since the name is put together on display the same way)    

If a first_name or last_name is set at the same time, the nick_name is discarded.

<title>
Specifies the title e.g. "Head of Finances" of the contact.
<organization>
Specifies the organization of the contact.
<email>
Specifies the E-Mail address of the contact.
<note>
Adds a note to the contact that can be viewed in the contact details.
<group>
  • <empty>
  • work
  • colleague
  • family
  • friend
Specifies the group the contact belongs to. This is relevant when any of the sorting methods is applied.
<source_id>

A unique server id

These are the currently possible numbers:

  kTbook = 1,
  kProvisioned = 2,
  kLdap = 3,
  kMetaswitchContacts = 4,
  kMetaswitchExtensions = 5,
  kMetaswitchShortCode = 6,
  kXsiEnterprise = 7,
  kXsiEnterpriseCommon = 8,
  kXsiGroup = 9,
  kXsiGroupCommon = 10,
  kXsiPersonal = 11,
  kXmpp = 12,
<photo>

Only one tag can be present.

<photo> contains a base64 encoded photo string

<numbers>
Contains all number tags belonging to that contact
<numbers/number>
Contains all number data to one number of a contact. A contact can have multiple numbers. Please look at the XML example above
<numbers/number/alias>
An number alias  Not supported any more. The alias was the nick_name copied in each entry of the number field. Please see nick_name for more info.
<numbers/number/action_url>valid URLSpecifies the action URL that is requested when the phone receives or places a call from/to this contact.
number attrib: no
Specifies the number of the contact.
number attrib: type
  • sip
  • mobile
  • fixed
  • home
  • business
  • extension
Number type
number attrib: outgoing_id0: active, otherwise identityoutgoing identity


Creating and provisioning a contact with more than one number

This is now done directly inside the <contact> via the <numbers> subtag. Please expand the XML - tree example above. 

Provisioning Local Directory (OLD XML FORMAT)

Provisioning the local directory can be done in two ways when utilizing xml files.

  1. Create a regular settings file and included a <tbook> inside it.

    Inside <Settings> tag 
    <settings> 
<tbook complete="true" e='2'> 
<item context="line1" type="vip" fav="true" mod="false" index="0"> 
<name>Nickname</name> 
<number>Number</number> 
<number_type>mobile</number_type> 
<first_name>First Name</first_name> 
<last_name>Family Name</last_name> 
<title>Title</title> 
<organization>Organization</organization> 
<email>E-Mail</email> <note>Note</note> 
<photo>(Base64 Encoded Photo)</photo> 
<action_url>http://action.url:80</action_url> 
<group>work</group> </item> 
</tbook> 
</settings>

  2. Create a separate xml settings file and included in your list of <settings-files>

    Individual XML file whose URL is listed inside <setting-files> tag 
    <?xml version="1.0" encoding="utf-8"?> 
<tbook complete="true" e='2'> 
<item context="line1" type="vip" fav="true" mod="false" index="0"> 
<name>Nickname</name> 
<number>Number</number> 
<number_type>mobile</number_type> 
<first_name>First Name</first_name> 
<last_name>Family Name</last_name> 
<title>Title</title> 
<organization>Organization</organization> 
<email>E-Mail</email> <note>Note</note> 
<photo>(Base64 Encoded Photo)</photo> 
<action_url>http://action.url:80</action_url> 
<group>work</group> </item> 
</tbook>

Explanation of Local Directory XML Tags and Attributes

Attribute / TagValid ValuesExplanation
<tbook>
The tbook tag defines the directory itself.
e2Defines that unicode-values inside xml-escapes (e.g. &#64;) may be greater than 255.
completetrue / falseWhen this is provisioned, it indicates 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.



<Item>
Each item tag defines one local directory contact it requires the attributes below to properly function
context

<empty>

line1-line12

Defines the SIP identity (line/account) this contact should be called with. Leaving this empty always chooses the currently active identity.
type
  • none
  • vip
  • deny
  • MASTER
  • Defines the contact's category for special phone states.
  • Contacts that have set their type to VIP can bypass certain phone blocking states such as DND.
  • Contacts that have set their type to deny are permanently blocked from calling the user.
  • Contacts that have set their type to MASTER are contacts containing more than one number.
index<number>Represents the contact's visual position within the list of entries in case of no sorting options. This value must be unique for each item.
fav
  • true
  • false
Defines whether current contact is a Favorite or not. This affects the list when filtering for favorite contacts.



<first_name>
Specifies the first name of the contact.
<last_name>
Specifies the family name of the contact.
<name>
Specifies the Name of the contact. Please see under 'nick_name' of the new format how this field is interpreted.
<number>
Specifies the number of the contact.
  • The minimal required parameter is number, all other parameters are optional. Apart from those available
<title>
Specifies the title e.g. "Head of Finances" of the contact.
<organization>
Specifies the organization of the contact.
<email>
Specifies the E-Mail address of the contact.
<note>
Adds a note to the contact that can be viewed in the contact details.
<group>
  • <empty>
  • work
  • colleague
  • family
  • friend
Specifies the group the contact belongs to. This is relevant when any of the sorting methods is applied.
<number_type>
  • <empty>
  • sip
  • mobile
  • fixed
  • home
  • business
Specifies the number type of the contact <number>.
<photo>Photo, Base64 EncodedYou have to encode a photo first to base64 (For example here online) and paste it to the XML File.
<action_url>valid URLSpecifies the action URL that is requested when the phone receives or places a call from/to this contact.
<birthday>00/00/0000deprecated


Creating and provisioning a contact with more than one number

In order to provision the local directory with contacts that contain more than one number, certain attributes have to be configured in order for the extra numbers to be properly recognized.

Contact with more than one number 
<tbook e='2'>
  <item context='' type="MASTER" fav="false" mod="true" index="0">
    <name>Name</name>
    <number>0123456789</number>
    <number_type>sip</number_type>
    <first_name>First Name</first_name>
    <last_name>Family Name</last_name>
    <title>Title</title>
    <organization>Organization</organization>
    <email>E-Mail</email>
    <note>Note</note>
    <action_url>http://action.url:80</action_url>
    <group>work</group>
  </item>
  <item context='' type="none" fav="false" mod="false" index="1">
    <number>0123456789</number>
    <number_type>home</number_type>
    <first_name>Member_Alias</first_name>
    <last_name>0123456789</last_name>
  </item>
  <item context="active" type="vip" fav="false" mod="false" index="2">
    <number>909090</number>
    <number_type>mobile</number_type>
    <first_name>Member_Alias</first_name>
    <last_name>0123456789</last_name>
  </item>
</tbook>


  • What defines a contact with more than one item is that there is an item with type="Master" that is linked to all numbers of that specific contact. Master contacts cannot define a context

    Contact with more than one number
    <item context='' type="MASTER" fav="false" mod="true" index="0">

  • <number> must be one of the telephone numbers of one of the members and has to be unique and not used by another contact

    Contact with more than one number 
    <tbook e='2'>
  <item context='' type="MASTER" fav="false" mod="true" index="0">
    <number>0123456789</number>

[...]

  <item context='' type="none" fav="false" mod="false" index="1">
    <number>0123456789</number>

  • The member entries have to define their <first_name> as "Member_Alias" and the <last_name> as the unique number of the master that is also present on one of the members. Members cannot define neither birthday nor favorite attribute.

    Contact with more than one number 
    <tbook e='2'>
  <item context='' type="MASTER" fav="false" mod="true" index="0">
    <number>0123456789</number>
[...]
 
 <item context='' type="none" fav="false" mod="false" index="1">
    <number>0123456789</number>
[...]
    <first_name>Member_Alias</first_name>
    <last_name>0123456789</last_name>
  </item>
  <item context="active" type="vip" fav="false" mod="false" index="2">
[...]
    <first_name>Member_Alias</first_name>
    <last_name>0123456789</last_name>
  </item>
 
[...]

Manually adding an entry in the web interface

DescriptionScreenshot
To add a new entry to the phone book, enter the name and the phone number in the "Add or Edit Entry" window.


IMPORTANT: you can have only one contact associated with a number. If you add a new contact with an already existing phone number the old contact will be deleted.

If you want to, you can choose a contact type from the pull-down menu. Please note that calls from a phone number you have defined as "VIP" will ring on your phone even when you have turned on DND mode. Press "Add/Edit" to save the entry to the phone book.


Editing an entry

DescriptionScreenshot
To add or change an existing entry, click on its "Edit" symbol. The current data of that particular phone book entry is displayed in the "Add or Edit an Entry" window where you can then edit/change it. Press "Add/Edit" to save the changes to the phone book.


Delete address book

DescriptionScreenshot
If you want to delete the entire address book, click onto the “Delete” button on the web interface page of the address book.


Export

DescriptionScreenshot
To save your address book onto your PC or server, click on “XML File”. The file is then saved in xml format.


Import

DescriptionScreenshot
To load a phone book from a file, click on the Browse button in the “Import Directory (CSV)” window of the page. Select the CSV file from the storage medium.

Files to import must be in UTF-8 unicode format in order to display special characters properly.


Example of a contact in csv format with more than one phone number:

"","0123456789","MASTER","","Max","Musterman","","","","","","","false","","sip",""
"","0123456789","none","","Member_Alias","0123456789","","","","","","","false","","home",""
"","00112233","none","active","Member_Alias","0123456789","","","","","","","false","","mobile",""
"","333444","none","active","Member_Alias","0123456789","","","","","","","false","","business",""


Preview

DescriptionScreenshot
A preview feature is available when importing CSV files for the phone book. A CSV file has entries separated by a comma (without spaces between the comma and the preceding and following entry). It could look like the file in the screenshot.

The first line represents the header, which shouldn’t be imported. Select the option “without header” in the “Import Directory (CSV)” window. Press the ‘Load’ button.

Name,Line,City,Street,Phone number,Type
Kate,active,New York,21 Street,278139232,family
George,line1,Tokyo,Mainroad,13153243,friends
Harry,active,Berlin,Pankestr,112984382,colleagues
Now assign the four possible data types (name, number, contact type, outgoing identity) to the columns in the preview representing those kinds of data. Once satisfied with the preview, press “Save” to save the file contents to the phone book

After saving the phone book could look like this:


Creating a Contact with Multiple Numbers per Person

DescriptionScreenshot

A Person with e.g. three telephone numbers consists of four records. One (the master) describes the attributes that are common for all its telephone number records (its members). The (three) members must set a telephone number and a name but may also define several other attributes. Some of them they share with the master, when a member doesn't define one of these attributes, it'll automatically set to be the same as what the master has defined there. The member can also overwrite attributes from the master to have for example a different group associated with one telephone number (e.g. for a colleague who you also consider your friend you may define the master record as friend and change the group in his office telephone number(s) to colleague).


  1. Open the Directory in the web interface
  2. Create the contact with one of the several phone numbers of the contact and press "Add"
  3. In the Overview of the contact press "Edit"
  4. Replace the original number with the second phone number of the contact and change the number type. Afterwards press "Add Sub"
  5. From this point on in order to edit a number of the contact the sub entries have to be accessed via "Edit". General properties of the contact like the "First Name" or "Family Name" have to be edited in the main contact
  6. In order to add a third or fourth number the main contact has to be selected again and "Edit" pressed. Afterwards, Step 4 has to be repeated.


The attributes shared in the described way between master and members are:

- Group
- Title
- Organization
- Email
- Note
- Photo

There are also attributes that may exclusively be set for the master:

- First Name(s)
- Family Name
- Favorite

Finally, some Attributes can only make sense in connection with a number:

- Name (naming the number, not the person. e.g. "office", "cell", ..)
- Number
- Contact Type
- Outgoing Identity


Further Information


Related articles