Stock Plugins Documentation

View Plugins

default_json

View name: default_json

Purpose: present directory entries in JSON format.

headers

View name: headers

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

personal_view

View name: personal_view

Purpose: Expose REST API to manage personal contacts (create, delete, list).

phonebook_view

View name: phonebook_view

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

aastra_view

View name: aastra_view

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

cisco_view

View name: cisco_view

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

polycom_view

View name: polycom_view

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

snom_view

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.

Service Plugins

lookup

Service name: lookup

Purpose: Search through multiple data sources, looking for entries matching a word.

Configuration

Example (excerpt from the main configuration file):

1
2
3
4
5
6
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:

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.

personal

Service name: personal

Purpose: Add, delete, list personal contacts of users.

phonebook

Service name: phonebook

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

Configuration

Example (excerpt from the main configuration file):

1
2
3
4
5
6
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:

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.

reverse

Service name: reverse

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

Configuration

Example:

1
2
3
4
5
6
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.

Back-end Configuration

This sections completes the Sources Configuration section.

csv

Back-end name: csv

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
type: csv
name: my_csv
file: /var/tmp/test.csv
unique_column: id
searched_columns:
    - fn
    - ln
first_matched_columns:
    - num
format_columns:
    lastname: "{ln}"
    firstname: "{fn}"
    number: "{num}"

With the CSV file:

1
2
3
4
id,fn,ln,num
1,Alice,Abrams,55553783147
2,Bob,Benito,5551354958
3,Charles,Curie,5553132479
file
the absolute path to the CSV file

CSV web service

Back-end name: csv_ws

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

Given the following configuration, xivo-dird would call “https://example.com:8000/ws-phonebook?firstname=alice&lastname=alice” for a lookup for the term “alice”.

Configuration

Example (a file inside source_config_dir):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
type: csv_ws
name: a_csv_web_service
lookup_url: "https://example.com:8000/ws-phonebook"
list_url: "https://example.com:8000/ws-phonebook"
verify_certificate: False
searched_columns:
  - firstname
  - lastname
first_matched_columns:
    - exten
delimiter: ","
timeout: 16
unique_column: id
format_columns:
    number: "{exten}"
lookup_url
the URL used for directory searches.
list_url (optional)
the URL used to list all available entries. This URL is used to retrieve favorites.
verify_certificate (optional)
whether the SSL cert will be verified. A CA_BUNDLE path can also be provided. Defaults to True.
delimiter (optional)
the field delimiter in the CSV result. Default: ‘,’
timeout (optional)
the number of seconds before the lookup on the web service is aborted. Default: 10.

dird_phonebook

back-end name: dird_phonebook

Purpose: search the xivo-dird’s internal phonebooks

Configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 type: dird_phonebook
 name: phonebook
 db_uri: 'postgresql://asterisk:proformatique@localhost/asterisk'
 tenant: default
 phonebook_id: 42
 phonebook_name: main
 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.
phonebook_name
the name of the phonebook used by this source.
phonebook_id (deprecated, use phonebook_name)
the id of the phonebook used by this source.

ldap

Back-end name: ldap

Purpose: search directory entries from an LDAP server.

Configuration

Example (a file inside source_config_dir):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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
ldap_custom_filter: (l=québec)
unique_column: entryUUID
searched_columns:
    - cn
first_matched_columns:
    - telephoneNumber
format_columns:
    firstname: "{givenName}"
    lastname: "{sn}"
    number: "{telephoneNumber}"
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)

the custom filter is used to add more criteria to the filter generated by the back end.

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.

This must be a valid LDAP filter, 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.

Defaults to 0.3.

ldap_timeout (optional)

the maximum time, in second, that an LDAP operation can take.

Defaults to 1.0.

unique_column (optional)

the column that contains a unique identifier of the entry. This is necessary for listing and identifying favorites.

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

unique_column_format (optional)

the unique column’s type returned by the queried LDAP server. Valid values are “string” or “binary_uuid”.

Defaults to “string”.

phonebook

Back-end name: phonebook

Purpose: search directory entries from a XiVO phone book.

Configuration

Example (a file inside source_config_dir):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
type: phonebook
name: my_phonebook
phonebook_url: https://example.org/service/ipbx/json.php/restricted/pbx_services/phonebook
phonebook_username: admin
phonebook_password: foobar
first_matched_columns:
    - phonebooknumber.office.number
    - phonebooknumber.mobile.number
format_columns:
    firstname: "{phonebook.firstname}"
    lastname: "{phonebook.lastname}"
    number: "{phonebooknumber.office.number}"
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 (Configuration ‣ Web Services Access) on the remote XiVO.

personal

Back-end name: personal

Purpose: search directory entries among users’ personal contacts

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.

The complete list of fields is in Personal contacts.

Configuration

Example (a file inside source_config_dir):

1
2
3
4
5
6
7
8
type: personal
name: personal
first_matched_columns:
    - number
format_columns:
    firstname: "{firstname}"
    lastname: "{lastname}"
    number: "{number}"

unique_column is not configurable, its value is always id.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
type: xivo
name: my_xivo
confd_config:
    https: True
    host: xivo.example.com
    port: 9486
    version: 1.1
    username: admin
    password: password
    timeout: 3
unique_column: id
first_matched_columns:
    - exten
searched_columns:
    - firstname
    - lastname
format_columns:
    number: "{exten}"
    mobile: "{mobile_phone_number}"
confd_config:host
the hostname of the XiVO (more precisely, of the xivo-confd service)
confd_config:port
the port of the xivo-confd service (usually 9486)
confd_config:version
the version of the xivo-confd API (should be 1.1)