Просмотреть исходный

Миграция данных из Active Directory

Данный раздел необязателен, если необходима лишь работа с персональными адресными книгами или планируется импортировать адресную книгу CSV-формата.

Для того, чтобы импортировать данные из Active Directory (служба каталогов корпорации Microsoft для операционных систем семейства Windows Server), необходимо:

1. Отредактируйте файл settings.override.yaml:

<nano/vim/mcedit> address-book/stable/settings.override.yaml

Заполните значения полей в соответствии с вашей инфраструктурой и соблюдая структуру YAML:

sources:  #Здесь задаются источники откуда брать данные
  active_directory:
    - server: "example.com"
      source: "example.com"
      port: 389
      ssl: false
      timeout: 10000
      base_dn: "CN=Users,DC=example,DC=com"
      user_dn: "ivan.ivanov@example.com"
      password: "example_password"
      base_ou: "Имя компании"

# ============================
# ОБЩИЕ НАСТРОЙКИ
# ============================

additional_import_settings:
  common:
    include_incompletely_filled_contacts: false # | true   - если выключена, при импорте будут отброшены все контакты, у которых отсутствуют обязательные поля

    full_name_parsing:
      enabled: false
      pattern: "LFM" # L - last_name, M - middle_name, F - first_name
      fallback_enabled: true # если не удалось распарсить - класть всё в fallback_field
      fallback_field: "middle_name" # middle_name | first_name | last_name; по умолчанию middle_name

  ad:
    ignore_data: [""]
    object_name: ["object", "string"]

sources: active_directory:

port — Порт сервера AD;

server/source — Хост сервера AD;

base_dn — Базовый Distinguished Name (DN) для поиска пользователей и групп в AD;

ssl — Использовать ли SSL/TLS для защищенного подключения;

timeout — Таймаут для операций с сервером AD;

user_dn — Логин в формате user@domain или DN;

password — Пароль для аутентификации в AD;

base_ou — Название базовой организационной единицы (OU — Organizational Unit) верхнего уровня.

Для импорта из нескольких источников перечислите несколько источников AD:

sources:  #Здесь задаются источники откуда брать данные
   active_directory:
    - server: "example.com"
      source: "example.com"
      port: 389
      ssl: false
      timeout: 10000
      base_dn: "CN=Users,DC=example,DC=com"
      user_dn: "ivan.ivanov@example.com"
      password: "example_password"
      base_ou: "Имя компании"

     - server: "example2.com"
      source: "example2.com"
      port: 389
      ssl: false
      timeout: 10000
      base_dn: "CN=Users,DC=example,DC=com"
      user_dn: "ivan.ivanov@example.com"
      password: "example_password"
      base_ou: "Имя компании"

2. При необходимости поменяйте настройки маппинга, указав их в секции mappers. Данная настройка отвечает за сопоставление атрибутов Active Directory с полями Address Book при импорте.

# ============================
# КОНФИГУРАЦИЯ МАППИНГА
# ============================

# Конфигурация мапперов для трансформации данных из внешних источников в структуру контакта Address Book
#
# Доступные поля контакта: domain, external_id, birthday, common_name, first_name,
# last_name, middle_name, nickname, org, title, full_name, position, gender, avatar, addresses, emails, messengers,
# phones, additional_info
#
# Структура маппера:
#   <источник>:
#     <поле_контакта>: [<путь_к_данным_в_источнике>, <тип_данных>]
#     <поле_контакта>: [[<вложенный_путь>, <тип_данных>]]
#     additional_info:
#       <подполе>: [<путь_к_данным>, <тип_данных>]
#
# Поддерживаемые типы данных:
#   - string: строковые значения
#   - url: тип аватара; означает, что аватар хранится в виде пути
#   - jpeg: тип аватара; бинарные данные изображений
#   - email: адреса электронной почты
#   - phone: номера телефонов
#   - date: даты
#
# Особенности:
#   - Поле 'kind' автоматически устанавливается сервисом ('contact' или 'group')
#   - Поле 'additional_info' поддерживает только одноуровневую вложенность
#   - Вложенные структуры в 'additional_info' отбрасываются с записью в лог
#   - Для полей emails, phones, avatar поддерживается множественное отображение

mappers:
  ad:
    common_name: ["name", "string"]
    full_name: ["cn", "string"]
    first_name: ["givenName", "string"]
    last_name: ["sn", "string"]
    middle_name: ["initials", "string"]
    org: ["company", "string"]
    emails: ["mail", "email"]
    phones:
      [
        [["telephoneNumber"], ["phone", "work"]],
        [["othertelephoneNumber"], ["phone", "work"]],
        [["ipPhone"], ["phone", "work"]],
        [["homePhone"], ["phone", "home"]],
        [["mobile"], ["phone", "cell"]],
        [["otherMobile"], ["phone", "cell"]],
      ]
    avatar: [["jpegPhoto", "jpeg"], ["thumbnailPhoto", "url"]]

Все атрибуты, кроме phones и avatar, записываются в виде:

имя_поля_в_address_book : ["имя_атрибута_в_active_directory", "тип_атрибута]"
first_name : ["givenName", "string"]]

В Active Directory у импортируемого пользователя в атрибуте givenName хранится значение «Kuzma».

Eltex Documentation > Миграция данных из Active Directory > image-2025-5-5_17-56-33.png

В таком случае указанная строка ["first_name", ["givenName", "string"]] при импорте обработается следующим образом: из атрибута givenName будет взято значение имени «Kuzma» с типом «string» и произведена запись этого значения в поле «first_name» сервиса Address Book.

Поля «phones», «avatar» работают иначе.

Поле «phones» содержит несколько значений, каждое из которых записано в виде:

[["имя_атрибута_в_active_directory"], ["к_какому_общему_полю_в_AB_принадлежит", "тип"]]
[["telephoneNumber"], ["phone", "work"]]

В Active Directory у импортируемого пользователя в атрибуте «telephoneNumber» записано значение внутреннего телефонного номера абонента равное 700.

В таком случае указанная строка [["telephoneNumber"], ["phone", "work"]] при импорте обработается следующим образом: из атрибута «telephoneNumber» будет взято значение 700 и добавлено в поле «phones» в виде списка словарей.

Список словарей нужен, так как телефонов у пользователя может быть несколько (мобильный, рабочий, домашний).

"phones": [
            {
              "__typename": "Phone",       
              "number": "700",
              "type": "work"
            },
]

Eltex Documentation > Миграция данных из Active Directory > image-2025-5-5_17-57-3.png

Атрибут avatar импортируется аналогичным образом и служит для последующего отображения изображения (аватара) контакта в клиенте Elph. Аватар может быть задан в бинарном виде (jpeg) либо в текстовом (url). На рисунке ниже пример отдельно созданного для этих целей атрибута с именем «avatar». Можно использовать любое встроенное текстовое поле карточки пользователя, правильно сопоставив его при импорте.

Eltex Documentation > Миграция данных из Active Directory > image-2025-5-5_17-46-38.png

4. Выполните импорт, последовательно вводя указанные ниже команды:

docker exec -it address-book-stable-server-1 bash
./ecss_address_book remote --name ecss_address_book
EcssAddressBookCore.Actions.AdImport.import

Для выхода из iex нажмите Ctrl+C дважды. Затем введите exit.

При импорте выполняются дополнительные проверки:

1. Если у контакта заполнено хотя бы одно поле (фамилия, имя, отчество) и телефон, такой контакт импортируется в БД Address Book. В противном случае импорт не осуществляется;

2. Так же происходит удаление дублирующихся номеров по следующему принципу:

Если у контакта заполнено несколько идентичных номеров в одной категории (например 2 одинаковых рабочих (work) номера), то дубли удаляются;
Если дубли встречаются в категории «рабочий (work)» и в одной или обеих категориях «мобильный (cell)», «домашний (home)», то в приоритете дублирующийся номер сохранится в категории «рабочий (work)»;
Если дубли встречаются в категориях «мобильный (cell)», «домашний (home)», то в приоритете дублирующийся номер сохранится в категории «мобильный (cell)».

Eltex Documentation > Миграция данных из Active Directory > image-2025-5-6_15-39-19.png

Таким образом в базу данных Address Book попадают только уникальные номера каждого контакта.