Directories

Whenever you search a user on XiVO using any of its Web Apps or a registered phone, it uses the module Dird to query sources named Directories. If you have a custom source, such as a LDAP, that you would like XiVO to know about and rely on, you must first register it as a Directory. Then you must write the right configuration, so XiVO is able to query it and render the right informations from it.

These are the steps to do so:

• Add the Directory itself

• Add the Directory Definition

• Register the Directory to Direct Search and/or Reverse lookup

• Restart Dird

There are 5 different Directory Types, each having some specific configurations. You will find some exampes in those pages, but you must follow the procedure here.

Note

Phone IP should be in the authorized subnet to access the directories. See Remote directory.

I. Add a Directory

You define where the data source that will become a Directory is located and what is its type.

Default configuration

In Configuration ‣ Management ‣ Directories:

• Directory name: the directory name

• Type: select among:

  • XiVO

  • CSV File

  • CSV Web service

  • Phonebook

• URI: the data source location

• Description: (optional) a description of the directory

Warning

Editing the URI later requires you to save again the Directory Definition because the corresponding URI on Definition will be broken. After that you shall restart Dird

LDAPs (specific)

LDAP Directories are created differently.

Under LDAP Server you specify the location of your LDAP, and under LDAP Filters you set how you navigate it.

See LDAP for adding this Directory, then continue here with the remaining steps starting with II. Add a Directory Definition.

II. Add a Directory Definition

Under Definition, you define:

• the Directory Source Name

• the Directory Fields that will be used for the search. Directory Fields are values that shall be available on the source. If you’re configuring your own custom source, you know what they are.

• the mapping between the Directory Fields and a the DisplayFilter Fields (see Display Filter)

In Services ‣ CTI Server ‣ Directories ‣ Definitions:

• Name: the Directory Source Name

• URI: the data source, one linked to the Directory you defined above will appear

• Delimiter: (optional) the field delimiter in the data source

• Direct match: the list used to match entries for direct lookup (comma separated)

• Match reverse directories: (optional) the list used to match entries for reverse lookup (comma separated) - see Reverse lookup

• Mapped fields: the mapping between your Directory Fields and the DisplayFilter Fields

  • Fieldname: your Directory Fields (the values you want to read from it)

  • Value: the associated DisplayFilter Fields

Important

The Directory Source Name cannot contain special characters, use a-z, A-Z, 0-9

III. Register the Directory

Your Directory is defined but not activated. It has to be selected, through its Directory Source Name, for direct search and/or for reverse lookup.

Register Directory for direct search

1. In Services ‣ CTI Server ‣ Directories ‣ Direct directories.

2. Edit your context (usually default)

3. Select your display filter (usually Display, see Display Filter)

4. Add the directories in the Directories section.

Register Directory for reverse lookup

See Reverse lookup to configure the directory for reverse lookup.

1. In Services ‣ CTI Server ‣ Directories ‣ Reverse directories.

2. Add the directories to include to reverse lookups in the Related directories section.

IV. Restart Dird

Use one ofthese methods:

• Services ‣ IPBX ‣ Control ‣ Restart Dird server

• console service xivo-dird restart on XiVO PBX

You may want to follow closely Dird logs there, so you are sure no Directory fails to reload.

Directory Types

• XiVO Directory
  • Available Fields
  • Example
    • Adding Directory
    • Adding Directory Definition
• CSV File Directory
  • Available fields
  • Example
    • Adding Directory
    • Adding Directory Definition
• CSV Web service directories
  • Available fields
  • Example
    • Adding a source
    • Configuring source access
• LDAP
  • Add a LDAP Server
    • Notes on SSL/TLS usage
  • Add a LDAP Filter
    • Use a Custom Filter
  • Add a Directory Definition
• Phonebook directories
  • Available fields
    • General phone book section
    • Phone numbers
    • Addresses
      • Locations
      • Fields
  • Example
    • Adding a source
    • Configuring source access

Display Filter

Location

In Services ‣ CTI Server ‣ Directories ‣ Display filters.

Use the default Display or create your own on its model.

The DisplayFilters are chosen by context under III. Register the Directory.

Default

Fields types and Fields variables name are fixed in the default Display.

You may update the field title to better match your needs. See Contact modal for the visual rendering.

Attributes

Each line in the display filter will result in a header in your Web Apps.

• Field title: text displayed in the header.

• Field type: type of the column, this information is used by the Web Apps. (see type description)

• Field name: names of the variables to map in Directory Definitions to Directory Fields reverse_lookup

Reverse lookup

Reverse lookup aims to show a better caller ID name on incoming calls when the caller is in one of our directories, based on the incoming caller ID number.

It will only be tried if at least one of the following conditions is true:

• The caller ID name is the same as the caller ID number

• The caller ID name is “unknown”

Important

Reverse lookup is performed after Caller Number Normalization (since XiVO 13.11).

To enable reverse lookup for a directory, you need to add in its definition (Services ‣ CTI Server ‣ Directories ‣ Definitions):

• a columns list in Match reverse directories where the incoming caller ID number is searched

• an entry in Mapped fields with:

  • Fieldname: reverse

  • Value: how you want the caller ID name to be displayed (for instance {phonebooknumber.society})

Warning

When you update this, xivo-dird must be restarted, see IV. Restart Dird.

Important

The directory must also be added as Reverse Lookup Directory, see Register Directory for reverse lookup.

Example

For internal directory:

• Match reverse directories: mobile_phone_number,exten

• Fieldname: reverse

• Value: {firstname} {lastname} - rewritten

This configuration will show the contact’s firstname, lastname then - rewritten on the caller ID name, when the incoming call callerid number will match its mobile or default number.

This makes the following difference:

Merge Contacts

Previously, if as a company you had your employees registered in a LDAP but wanting to provide them an internal number on XiVO, you had to create XiVO users for your employees with this number.

Then when searching for them in the XiVO Web Apps (UC Assistant, CC Agent, POPC), they would appear twice in the search.

You would see this:

Starting with Orion, the XUC Server comes with a way to merge Dird results with a common email.

So instead, you will see this:

• Given you have several different registered Directories containing users having common emails.

• Given those Directories have for Directory Source Name: internal, ldap1, phonebook, CsvFileOne

• Define the Merge Order in xivocc’s custom.env with DIRECTORY_SOURCES_PRIORITY and the sources you want to merge, separated by , :

DIRECTORY_SOURCES_PRIORITY="ldap1,internal,phonebook"

DIRECTORY_INTERNAL_SOURCE applies a different order for merging the phone (precisely contact_1_callable according to the default Display).

The common use case is that we trust LDAP informations for everything but when it comes to calling we need the internal number, defined on XiVO.

DIRECTORY_INTERNAL_SOURCE="internal,phonebook"

• DIRECTORY_INTERNAL_SOURCE can only contain members of DIRECTORY_SOURCES_PRIORITY. Any other member won’t be read.

• DIRECTORY_INTERNAL_SOURCE merging happen after the DIRECTORY_SOURCES_PRIORITY merging, updating the object.

Important

If DIRECTORY_SOURCES_PRIORITY is not provided nothing is done. Duplicates are then maintained.

Important

If a Source provides several times a contact with the same email (for instance several people use a service email), then these won’t be merged.

Important

The merge contact is case insenstive with mails. The case sensitivity can be restablished by adding the following key to xivocc’s custom.env: MERGE_CONTACTS_CASE_SENSITIVITY=true

Important

You need to restart XUC for this configuration to apply: xivocc-dcomp up -d xuc

Warning

The merge appears only on xivo-dird results. If the search term does not lead xivo-dird to retrieve all contacts you want to merge, the merge will be uncomplete. An example of this will be searching contacts by service name, where most likely, only the ldap entries will be found by xivo-dird and not be mergeable with their internal counterpart.

Advanced Dird Configuration

• Advanced Dird Configration.