directories.rst 6.39 KB
Newer Older
1 2
.. _directories:

3 4 5 6
***********
Directories
***********

7
This page documents how to add and configure directories from custom sources. Directories added from
8
custom sources can be used for lookup via the directory feature of
9
phones or for :ref:`reverse lookup <reverse_lookup>` on incoming calls.
10

11
An example of `adding a source`_ and `configuring source access`_ is made for each type of source:
12

13 14
.. toctree::
   :maxdepth: 1
15

16
   xivo
17
   ldap/ldap
18 19 20
   csv_file
   csv_web_service
   phonebook
21
   dird_phonebook
22

23 24 25
.. note:: Phone IP should be in the authorized subnet to access the directories. See :ref:`remote-directory`.


26 27
Adding a source
===============
28

29
.. note:: See :ref:`ldap` for adding this source.
30

31
You can add new data sources via the :menuselection:`Configuration --> Management --> Directories`
32
page.
33

34 35
* :guilabel:`Directory name`: the name of the directory
* :guilabel:`Type`: there are 4 types of directory:
36

37 38 39 40
    * :ref:`XiVO<xivo-directory>`
    * :ref:`CSV File<csv-file-directory>`
    * :ref:`CSV Web service<csv-web-service-directory>`
    * :ref:`Phonebook<phonebook-directory>`
41

42 43
* :guilabel:`URI`: the data source
* :guilabel:`Description`: (optional) a description of the directory
44 45


Etienne Lessard's avatar
Etienne Lessard committed
46 47
.. _directory-definition:

48 49
Configuring source access
=========================
50

51 52
Go in :menuselection:`Services --> CTI Server --> Directories --> Definitions` and add a new
directory definition.
53

54 55 56 57 58
* :guilabel:`Name`: the name of the directory definition
* :guilabel:`URI`: the data source
* :guilabel:`Delimiter`: (optional) the field delimiter in the data source
* :guilabel:`Direct match`: the list used to match entries for direct lookup (comma separated)
* :guilabel:`Match reverse directories`: (optional) the list used to match entries for reverse
59
  lookup (comma separated)
60
* :guilabel:`Mapped fields`: used to add or modify columns in this directory source
61

62 63 64
  * :guilabel:`Fieldname`: the identifier for this new field
  * :guilabel:`Value`: a python format string that can be used to modify the data returned from a
    data source
65

66

67
.. _reverse_lookup:
68

69 70
Reverse lookup
--------------
71

72 73
It's possible to do reverse lookups on incoming calls to show a better caller ID name when
the caller is in one of our directories.
74

75
Reverse lookup will only be tried if at least one of the following conditions is true:
76

77 78
* The caller ID name is the same as the caller ID number
* The caller ID name is "unknown"
79

80
Also, reverse lookup is performed after :ref:`caller ID number normalization <callerid_num_normalization>` (since XiVO 13.11).
81

82
To enable reverse lookup, you need to add an entry in :guilabel:`Mapped fields`:
83

84 85
* :guilabel:`Fieldname`: ``reverse``
* :guilabel:`Value`: the header of your data source that you want to see as the caller ID on your
86
  phone on incoming calls
87 88


89 90
Example
^^^^^^^
91

92
* :guilabel:`Match reverse directories`:
93
  ``phonebooknumber.office.number,phonebooknumber.mobile.number,phonebooknumber.home.number``
94 95
* :guilabel:`Fieldname`: ``reverse``
* :guilabel:`Value`: ``phonebook.society``
96

97 98
This configuration will show the contact's company name on the caller ID name, when the incoming
call will match office, mobile or home number.
99

100
.. figure:: images/xivo_phonebook_reverse.png
101

102
   :menuselection:`Services --> CTI Server --> Directories --> Definitions`
103 104


105 106
Phone directory
---------------
107

108
Phone directory takes 2 :guilabel:`Fieldname` by default:
109

110 111
    * ``display_name``: the displayed name on the phone
    * ``phone``: the number to call
112 113 114 115 116


Examples:
---------

117 118 119
You will find below some useful configurations of :guilabel:`Mapped fields`.


120 121 122
Adding a name field from firstname and lastname
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

123
Given a configuration where the directory source returns results with fields firstname and lastname
124 125
. To add a `name` column to a directory, the administrator would add the following :guilabel:`Mapped
fields`:
126

127 128
* :guilabel:`Fieldname`: ``name``
* :guilabel:`Value`: ``{firstname} {lastname}``
129 130 131 132


Prefixing a field
^^^^^^^^^^^^^^^^^
133

134 135
Given a directory source that need a prefix to be called, a new field can be created from an exising
one. To add a prefix `9` to the numbers returned from a source, the administrator would add the
136
following :guilabel:`Mapped fields`:
137

138 139
* :guilabel:`Fieldname`: ``number``
* :guilabel:`Value`: ``9{number}``
140 141 142 143 144


Adding a static field
^^^^^^^^^^^^^^^^^^^^^

145
Sometimes, it can be useful to add a field to the search results. A string can be added without any
146
formatting. To add a `directory` field to the `xivodir` directory, the administrator would add the
147
following :guilabel:`Mapped fields`:
148

149 150
* :guilabel:`Fieldname`: ``directory``
* :guilabel:`Value`: ``XiVO internal directory``
151 152 153



154 155
Configuring source display
==========================
156

157 158
XiVO Client
-----------
159

160 161
Edit the default display filter or create your own in :menuselection:`Services --> CTI Server -->
Directories --> Display filters`.
162

163
.. figure:: images/display.png
164

165
   :menuselection:`Services --> CTI Server --> Directories --> Display filters`
166

167
Each line in the display filter will result in a header in your XiVO Client.
168

169 170
* :guilabel:`Field title`: text displayed in the header.
* :guilabel:`Field type`: type of the column, this information is used by the XiVO Client. (see
171
  :ref:`type description<dird-integration-views>`)
172
* :guilabel:`Default value`: value that will be used if this field is empty for one of the
173
  configured sources.
174
* :guilabel:`Field name`: name of the field in the directory definitions. The specified names
175 176
  should be available in the configured sources. To add new column name to a directory definition
  see above.
177

178

179 180
Phone
-----
181

182
The only way to configure display phone directory is through :ref:`dird-configuration-file`.
183 184


185 186
Adding a directory
==================
187

188
To include a directory in direct directory definition:
189

190 191 192 193
1. Go to :menuselection:`Services --> CTI Server --> Directories --> Direct directories`.
2. Edit your context.
3. Select your display filter.
4. Add the directories in the :guilabel:`Directories` section.
194

195
To include a directory in reverse directory definition:
196

197 198
1. Go to :menuselection:`Services --> CTI Server --> Directories --> Reverse directories`.
2. Add the directories to include to reverse lookups in the :guilabel:`Related directories` section.
199 200


201 202
Applying changes
================
203

Etienne Lessard's avatar
Etienne Lessard committed
204
To reload the directory configuration for XiVO Client, phone lookups and reverse lookups, use *one* of
205
these methods:
206

Etienne Lessard's avatar
Etienne Lessard committed
207
* :menuselection:`Services --> IPBX --> Control --> Restart Dird server`
208
* console ``service xivo-dird restart``