Stock Plugins Documentation
View Plugins
default_json
View name: default_json
Purpose: present directory entries in JSON format.
Note
For purpose of alphabetic ordering in results, accented character are converted to unaccented.
Field used to order result
Field for ordering is selected based on configuration of view/display. First non-empty field with type name is used. If there is no relevant value available, the result goes to end.
Relevance of results in lookup
Lookup results are ordered in way to prefer more relevant results:
exact matches of whole word
exact matches at beginning of word
exact matches anywhere
matches similar to term
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.
yealink_view
View name: yealink_view
Purpose: Expose REST API to search in configured directories for Yealink 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):
1services:
2 lookup:
3 default:
4 sources:
5 - my_csv
6 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):
1services:
2 favorites:
3 default:
4 sources:
5 - my_csv
6 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:
1services:
2 reverse:
3 default:
4 sources:
5 - my_csv
6 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
):
1type: csv
2name: my_csv
3file: /var/tmp/test.csv
4unique_column: id
5searched_columns:
6 - fn
7 - ln
8first_matched_columns:
9 - num
10format_columns:
11 lastname: "{ln}"
12 firstname: "{fn}"
13 number: "{num}"
With the CSV file:
1id,fn,ln,num
21,Alice,Abrams,55553783147
32,Bob,Benito,5551354958
43,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
):
1type: csv_ws
2name: a_csv_web_service
3lookup_url: "https://example.com:8000/ws-phonebook"
4list_url: "https://example.com:8000/ws-phonebook"
5verify_certificate: False
6searched_columns:
7 - firstname
8 - lastname
9first_matched_columns:
10 - exten
11delimiter: ","
12timeout: 16
13unique_column: id
14format_columns:
15 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 type: dird_phonebook
2 name: phonebook
3 db_uri: 'postgresql://asterisk:proformatique@localhost/asterisk'
4 tenant: default
5 phonebook_id: 42
6 phonebook_name: main
7 first_matched_columns:
8 - number
9 searched_columns:
10 - firstname
11 - lastname
12 format_columns:
13 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
):
1type: ldap
2name: my_ldap
3ldap_uri: ldap://example.org
4ldap_base_dn: ou=people,dc=example,dc=org
5ldap_username: cn=admin,dc=example,dc=org
6ldap_password: foobar
7ldap_custom_filter: (l=québec)
8unique_column: entryUUID
9searched_columns:
10 - cn
11first_matched_columns:
12 - telephoneNumber
13format_columns:
14 firstname: "{givenName}"
15 lastname: "{sn}"
16 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
):
1type: phonebook
2name: my_phonebook
3phonebook_url: https://example.org/service/ipbx/json.php/restricted/pbx_services/phonebook
4phonebook_username: admin
5phonebook_password: foobar
6first_matched_columns:
7 - phonebooknumber.office.number
8 - phonebooknumber.mobile.number
9format_columns:
10 firstname: "{phonebook.firstname}"
11 lastname: "{phonebook.lastname}"
12 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 (
) 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
):
1type: personal
2name: personal
3first_matched_columns:
4 - number
5format_columns:
6 firstname: "{firstname}"
7 lastname: "{lastname}"
8 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
):
1type: xivo
2name: my_xivo
3confd_config:
4 https: True
5 host: xivo.example.com
6 port: 9486
7 version: 1.1
8 username: admin
9 password: password
10 timeout: 3
11unique_column: id
12first_matched_columns:
13 - exten
14searched_columns:
15 - firstname
16 - lastname
17format_columns:
18 number: "{exten}"
19 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)
xivo_meetingroom
Back-end name: xivo_meetingroom
Purpose: search directory entries among meetingrooms (static or personal)
You should only have one source of type xivo_meetingroom
.
Configuration
The configuration should be as follow (a file inside source_config_dir
):
1 type: xivo_meetingroom
2 name: xivo_meetingroom
3 db_uri: postgresql://asterisk:proformatique@localhost/asterisk
4 searched_columns:
5 - name
6 - display_name
7 - number
8 format_columns:
9 display_name: '{display_name}'
10 name: '{display_name}'
11 phone: '{number}'
12 get_all_rooms_keywords: conference, visio
- get_all_rooms_keywords
keywords used to return all meeting rooms (both static and relevant personal) - should be lowercase and separated by coma
,
unique_column
is not configurable, its value is always id
.