stock_plugins.rst 12.7 KB
Newer Older
Sebastien Duthil's avatar
Sebastien Duthil committed
1 2 3 4 5 6 7 8 9 10 11 12
.. _stock-plugins:

===========================
Stock Plugins Documentation
===========================

View Plugins
============

default_json
------------

13 14
View name: default_json

15
Purpose: present directory entries in JSON format.
Sebastien Duthil's avatar
Sebastien Duthil committed
16

17 18 19 20 21 22 23
headers
-------

View name: headers

Purpose: List headers that will be available in results from ``default_json`` view.

Sebastien Duthil's avatar
Sebastien Duthil committed
24
personal_view
25 26
-------------

Sebastien Duthil's avatar
Sebastien Duthil committed
27
View name: personal_view
28

Sebastien Duthil's avatar
Sebastien Duthil committed
29
Purpose: Expose REST API to manage personal contacts (create, delete, list).
30

31 32 33 34 35 36 37
phonebook_view
--------------

View name: phonebook_view

Purpose: Expose REST API to manage xivo-dird's internal phonebooks.

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
38 39 40 41 42 43 44
aastra_view
-----------

View name: aastra_view

Purpose: Expose REST API to search in configured directories for Aastra phone.

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
45 46 47 48 49
cisco_view
----------

View name: cisco_view

50 51
Purpose: Expose REST API to search in configured directories for Cisco phone (see CiscoIPPhone_XML_Objects_).

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
52
.. _CiscoIPPhone_XML_Objects: http://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cuipph/all_models/xsi/8_5_1/xsi_dev_guide/xmlobjects.html
53

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
54 55
polycom_view
-------------
56

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
57
View name: polycom_view
58

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
59
Purpose: Expose REST API to search in configured directories for Polycom phone.
60

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
61 62
snom_view
---------
Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
63

Fran莽ois Blackburn's avatar
Fran莽ois Blackburn committed
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
View name: snom_view

Purpose: Expose REST API to search in configured directories for Snom phone.

thomson_view
------------

View name: thomson_view

Purpose: Expose REST API to search in configured directories for Thomson phone.

yealink_view
------------

View name: yealink_view

Purpose: Expose REST API to search in configured directories for Yealink phone.
81

82

Sebastien Duthil's avatar
Sebastien Duthil committed
83 84 85 86 87 88
Service Plugins
===============

lookup
------

89 90
Service name: lookup

Sebastien Duthil's avatar
Sebastien Duthil committed
91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
Purpose: Search through multiple data sources, looking for entries matching a word.

Configuration
^^^^^^^^^^^^^

Example (excerpt from the main configuration file):

.. code-block:: yaml
   :linenos:

   services:
       lookup:
           default:
               sources:
                   - my_csv
               timeout: 0.5

The configuration is a dictionary whose keys are profile names and values are configuration specific
to that profile.

For each profile, the configuration keys are:

113 114 115 116 117 118 119 120 121 122 123 124 125 126
sources
   The list of source names that are to be used for the lookup

timeout
   The maximum waiting time for an answer from any source. Results from sources that take longer to
   answer are ignored. Default: no timeout.

favorites
---------

Service name: favorites

Purpose: Mark/unmark contacts as favorites and get the list of all favorites.

127 128 129

.. _dird_services_personal:

Sebastien Duthil's avatar
Sebastien Duthil committed
130
personal
131 132
--------

Sebastien Duthil's avatar
Sebastien Duthil committed
133
Service name: personal
134

Sebastien Duthil's avatar
Sebastien Duthil committed
135
Purpose: Add, delete, list personal contacts of users.
136

137 138 139 140 141 142 143

phonebook
---------

Service name: phonebook

Purpose: Add, delete, list phonebooks and phonebook contacts.
144 145


146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
Configuration
^^^^^^^^^^^^^

Example (excerpt from the main configuration file):

.. code-block:: yaml
   :linenos:

   services:
       favorites:
           default:
               sources:
                   - my_csv
               timeout: 0.5

The configuration is a dictionary whose keys are profile names and values are configuration specific
to that profile.

For each profile, the configuration keys are:

Sebastien Duthil's avatar
Sebastien Duthil committed
166 167 168 169 170
sources
   The list of source names that are to be used for the lookup

timeout
   The maximum waiting time for an answer from any source. Results from sources that take longer to
171
   answer are ignored. Default: no timeout.
Sebastien Duthil's avatar
Sebastien Duthil committed
172 173


174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208
reverse
-------

Service name: reverse

Purpose: Search through multiple data sources, looking for the first entry matching an extension.

Configuration
^^^^^^^^^^^^^

Example:

.. code-block:: yaml
   :linenos:

   services:
       reverse:
           default:
               sources:
                   - my_csv
               timeout: 1

The configuration is a dictionary whose keys are profile names and values are configuration specific
to that profile.

For each profile, the configuration keys are:

sources
   The list of source names that are to be used for the reverse lookup

timeout
   The maximum waiting time for an answer from any source. Results from sources that take longer to
   answer are ignored. Default: 1.


Sebastien Duthil's avatar
Sebastien Duthil committed
209 210 211
Back-end Configuration
======================

212
This sections completes the :ref:`dird-sources_configuration` section.
Sebastien Duthil's avatar
Sebastien Duthil committed
213

214 215
.. _dird-backend-csv:

Sebastien Duthil's avatar
Sebastien Duthil committed
216 217 218
csv
---

219 220
Back-end name: csv

Sebastien Duthil's avatar
Sebastien Duthil committed
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237
Purpose: read directory entries from a CSV file.

Limitations:

* the CSV delimiter is not configurable (currently: ``,`` (comma)).

Configuration
^^^^^^^^^^^^^

Example (a file inside ``source_config_dir``):

.. code-block:: yaml
   :linenos:

   type: csv
   name: my_csv
   file: /var/tmp/test.csv
238
   unique_column: id
Sebastien Duthil's avatar
Sebastien Duthil committed
239 240 241
   searched_columns:
       - fn
       - ln
242 243
   first_matched_columns:
       - num
244 245 246 247
   format_columns:
       lastname: "{ln}"
       firstname: "{fn}"
       number: "{num}"
Sebastien Duthil's avatar
Sebastien Duthil committed
248 249 250 251 252 253

With the CSV file:

.. code-block:: text
   :linenos:

254 255 256 257
   id,fn,ln,num
   1,Alice,Abrams,55553783147
   2,Bob,Benito,5551354958
   3,Charles,Curie,5553132479
Sebastien Duthil's avatar
Sebastien Duthil committed
258 259 260 261 262


file
   the absolute path to the CSV file

263

264 265
.. _dird-backend-csv_ws:

266 267 268 269 270 271 272
CSV web service
---------------

Back-end name: csv_ws

Purpose: search using a web service that returns CSV formatted results.

273
Given the following configuration, *xivo-dird* would call
274
"https://example.com:8000/ws-phonebook?firstname=alice&lastname=alice" for a
275 276
lookup for the term "alice".

277 278 279 280 281 282 283

Configuration
^^^^^^^^^^^^^

Example (a file inside ``source_config_dir``):

.. code-block:: yaml
284 285 286 287
   :linenos:

   type: csv_ws
   name: a_csv_web_service
288 289 290
   lookup_url: "https://example.com:8000/ws-phonebook"
   list_url: "https://example.com:8000/ws-phonebook"
   verify_certificate: False
291 292 293 294 295 296 297 298 299 300
   searched_columns:
     - firstname
     - lastname
   first_matched_columns:
       - exten
   delimiter: ","
   timeout: 16
   unique_column: id
   format_columns:
       number: "{exten}"
301 302

lookup_url
303
    the URL used for directory searches.
304 305 306 307

list_url (optional)
    the URL used to list all available entries. This URL is used to retrieve favorites.

308 309 310
verify_certificate (optional)
    whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to True.

311 312
delimiter (optional)
    the field delimiter in the CSV result. Default: ','
313 314

timeout (optional)
315
    the number of seconds before the lookup on the web service is aborted. Default: 10.
316 317


318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337
.. _dird-backend-dird_phonebook:

dird_phonebook
--------------

back-end name: dird_phonebook

Purpose: search the xivo-dird's internal phonebooks

Configuration:
^^^^^^^^^^^^^^

.. code-block:: yaml
   :linenos:

    type: dird_phonebook
    name: phonebook
    db_uri: 'postgresql://asterisk:[email protected]/asterisk'
    tenant: default
    phonebook_id: 42
338
    phonebook_name: main
339 340 341 342 343 344 345 346 347 348 349 350 351 352
    first_matched_columns:
      - number
    searched_columns:
      - firstname
      - lastname
    format_columns:
        name: "{firstname} {lastname}"

db_uri
    the URI of the DB used by xivo-dird to store the phonebook.

tenant
    the tenant of the phonebook to query.

353
phonebook_name
354
    the `name` of the phonebook used by this source.
355

356 357
phonebook_id (deprecated, use phonebook_name)
    the `id` of the phonebook used by this source.
358 359


360 361
.. _dird-backend-ldap:

362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382
ldap
----

Back-end name: ldap

Purpose: search directory entries from an LDAP server.

Configuration
^^^^^^^^^^^^^

Example (a file inside ``source_config_dir``):

.. code-block:: yaml
   :linenos:

   type: ldap
   name: my_ldap
   ldap_uri: ldap://example.org
   ldap_base_dn: ou=people,dc=example,dc=org
   ldap_username: cn=admin,dc=example,dc=org
   ldap_password: foobar
383
   ldap_custom_filter: (l=qu茅bec)
Sebastien Duthil's avatar
Sebastien Duthil committed
384
   unique_column: entryUUID
385 386
   searched_columns:
       - cn
387 388
   first_matched_columns:
       - telephoneNumber
389 390 391 392
   format_columns:
       firstname: "{givenName}"
       lastname: "{sn}"
       number: "{telephoneNumber}"
393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413


ldap_uri
   the URI of the LDAP server. Can only contains the scheme, host and port part of an LDAP URL.

ldap_base_dn
   the DN of the entry at which to start the search

ldap_username (optional)
   the user's DN to use when performing a "simple" bind.

   Default to an empty string.

   When both ldap_username and ldap_password are empty, an anonymous bind is performed.

ldap_password (optional)
   the password to use when performing a "simple" bind.

   Default to an empty string.

ldap_custom_filter (optional)
414
   the custom filter is used to add more criteria to the filter generated by the back end.
415 416 417 418 419 420 421 422 423 424

   Example:

   * ldap_custom_filter: (l=qu茅bec)
   * searched_columns: [cn,st]

   will result in the following filter being used for searches. ``(&(l=qu茅bec)(|(cn=*%Q*)(st=*%Q*)))``

   If only the custom filter is to be used, leave the ``searched_columns`` field
   empty.
425 426 427 428 429 430 431 432 433 434

   This must be a valid `LDAP filter <https://tools.ietf.org/html/rfc4515>`_, where the string ``%Q`` will be replaced by the (escaped) search
   term when performing a search.

   Example: ``(&(o=ACME)(cn=*%Q*))``

ldap_network_timeout (optional)
   the maximum time, in second, that an LDAP network operation can take. If it takes more time than
   that, no result is returned.

435
   Defaults to 0.3.
436 437 438 439 440 441

ldap_timeout (optional)
   the maximum time, in second, that an LDAP operation can take.

   Defaults to 1.0.

442 443
unique_column (optional)
   the column that contains a unique identifier of the entry. This is necessary for listing and
444 445
   identifying favorites.

446 447 448 449 450
   For OpenLDAP, you should set this option to "entryUUID".

   For Active Directory, you should set this option to "objectGUID" and also set the
   "unique_column_format" option to "binary_uuid".

451
unique_column_format (optional)
452 453 454 455
   the unique column's type returned by the queried LDAP server. Valid values are "string" or
   "binary_uuid".

   Defaults to "string".
456

457

458 459
.. _dird-backend-phonebook:

460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479
phonebook
---------

Back-end name: phonebook

Purpose: search directory entries from a XiVO :ref:`phone book <phonebook>`.

Configuration
^^^^^^^^^^^^^

Example (a file inside ``source_config_dir``):

.. code-block:: yaml
   :linenos:

   type: phonebook
   name: my_phonebook
   phonebook_url: https://example.org/service/ipbx/json.php/restricted/pbx_services/phonebook
   phonebook_username: admin
   phonebook_password: foobar
480 481 482
   first_matched_columns:
       - phonebooknumber.office.number
       - phonebooknumber.mobile.number
483 484 485 486
   format_columns:
       firstname: "{phonebook.firstname}"
       lastname: "{phonebook.lastname}"
       number: "{phonebooknumber.office.number}"
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515


phonebook_url (optional)
   the phonebook's URL.

   Default to ``http://localhost/service/ipbx/json.php/private/pbx_services/phonebook``.

   The URL to use differs depending on if you are accessing the phone book locally or remotely:

   * Local: ``http://localhost/service/ipbx/json.php/private/pbx_services/phonebook``
   * Remote: ``https://example.org/service/ipbx/json.php/restricted/pbx_services/phonebook``

phonebook_username (optional)
   the username to use in HTTP requests.

   No HTTP authentication is tried when phonebook_username or phonebook_password are empty.

phonebook_password (optional)
   the password to use in HTTP requests.

phonebook_timeout (optional)
   the HTTP request timeout, in seconds.

   Defaults to 1.0.

To be able to access the phone book of a remote XiVO, you must create a web services access user
(:menuselection:`Configuration -> Web Services Access`) on the remote XiVO.


Sebastien Duthil's avatar
Sebastien Duthil committed
516
personal
517 518
--------

Sebastien Duthil's avatar
Sebastien Duthil committed
519
Back-end name: personal
520

Sebastien Duthil's avatar
Sebastien Duthil committed
521
Purpose: search directory entries among users' personal contacts
522

Sebastien Duthil's avatar
Sebastien Duthil committed
523 524 525
You should only have one source of type ``personal``, because only one will be used to list personal
contacts. The ``personal`` backend needs a working Consul installation. This backend works with the
personal service, which allows users to add personal contacts.
526

527
The complete list of fields is in :ref:`personal-contact-attributes`.
528

529 530 531 532 533 534 535 536
Configuration
^^^^^^^^^^^^^

Example (a file inside ``source_config_dir``):

.. code-block:: yaml
   :linenos:

Sebastien Duthil's avatar
Sebastien Duthil committed
537 538
   type: personal
   name: personal
539 540
   first_matched_columns:
       - number
541 542 543 544 545 546 547 548
   format_columns:
       firstname: "{firstname}"
       lastname: "{lastname}"
       number: "{number}"

``unique_column`` is not configurable, its value is always ``id``.


549 550
.. _dird-backend-xivo:

551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568
xivo
----

Back-end name: xivo

Purpose: add users from a XiVO (may be remote) as directory entries

Configuration
^^^^^^^^^^^^^

Example (a file inside ``source_config_dir``):

.. code-block:: yaml
   :linenos:

   type: xivo
   name: my_xivo
   confd_config:
569
       https: True
570
       host: xivo.example.com
571
       port: 9486
572
       version: 1.1
573 574
       username: admin
       password: password
575
       timeout: 3
576
   unique_column: id
577 578
   first_matched_columns:
       - exten
579 580 581
   searched_columns:
       - firstname
       - lastname
582 583 584
   format_columns:
       number: "{exten}"
       mobile: "{mobile_phone_number}"
585 586 587 588 589

confd_config:host
   the hostname of the XiVO (more precisely, of the xivo-confd service)

confd_config:port
590
   the port of the xivo-confd service (usually 9486)
591 592 593

confd_config:version
   the version of the xivo-confd API (should be 1.1)