Перейти к содержанию

Подключение организационной структуры

Назначение документа

Структура организаций — это сервис, который позволяет загружать, хранить, отображать и редактировать иерархии между организациями, подразделениями и сотрудниками.

В данном документе описано подключение структуры организации в случаях, когда:

Документ предназначен для использования администраторами организации.

Дополнительная документация

Структура организации — в документе описано управление структурой организации в панели администратора VK WorkSpace при наличии интеграции с Почтой VK WorkSpace.

Как работать в VK Teams — в документе описана работа пользователей со структурой организации в корпоративном мессенджере VK Teams — поиск сотрудников и организаций, просмотр иерархии отделов и иерархии между организациями.

Архитектура и описание системы VK Teams — в документе представлено описание сервисов, обеспечивающих работу функциональности оргструктуры. Не является частью публичной документации, обратитесь к представителю VK Tech, чтобы ознакомиться с документом.

Подключение структуры организации при наличии интеграции с Почтой VK WorkSpace

Шаг 1. Подключите функциональность структуры организации

Чтобы подключить функциональность оргструктуры в административной панели VK WorkSpace, обратитесь в техническую поддержку или к вашему персональному менеджеру.

Шаг 2. Создайте структуру организации

После подключения функциональности управление оргструктурой происходит в панели администратора VK WorkSpace в разделе Структура организаций.

Вы можете создать структуру организаций вручную или загрузить ее при помощи XLSX-файла. Подробные инструкции по управлению оргструктурой в панели администратора VK WorkSpace представлены в документации.

Шаг 3. Подключите функциональность в мессенджере

После создания оргструктуры в административной панели VK WorkSpace подключите структуру организации в корпоративном мессенджере VK Teams:

  1. В конфигурационном файле /usr/local/nginx-im/html/myteam/myteam-config.json произведите следующие настройки:

    1.1. Укажите настройки отображения мини-аппа структуры организации в секции orgstructure:

    "services": {
    "config": {
        "orgstructure": {
            "external": false,
            "needs_auth": true,
            "url": "https://webim.<YOUR_DOMAIN>/webapps/orgstructure/index.html",
            "url-dark": "https://webim.<YOUR_DOMAIN>/webapps/orgstructure/index.html",
            "staff-visible-part-index": 2,
            "new": true,
            "is-public": false,
            }

    где:

    • url — webim-ссылка вида https://webim.<YOUR_DOMAIN>/webapps/orgstructure/index.html.

    • url-dark —webim-ссылка вида https://webim.<YOUR_DOMAIN>/webapps/orgstructure/index.html.

    • staff-visible-part-index — количество пользователей, которые будут отображаться в оргструктуре подразделения над кнопкой «Показать всех». Значение по умолчанию — 2.

    • new — укажите true.

    • is-public — укажите false.

    1.2. Включите отображение вкладки оргструктуры в клиентском приложении:

    "services": {
    "disposition": {
            "desktop": { #включаем отображение сервиса оргструктуры в десктоп-версии
                "leftbar": [
                    "orgstructure"
                ]
            },
            "mobile": { #включаем отображение сервиса оргструктуры в мобильном приложении
                "services": [
                    "orgstructure"
                ]

    Примечание

    В секциях leftbar и services могут быть подключены другие сервисы. Не удаляйте их.

  2. Пересоздайте под админ-консоли:

    kubectl delete pod -n vkteams myteam-admin-\*

    где: * — уникальное имя пода. Имя пода необходимо получить с помощью вывода команды:

    kubectl get pods -A | grep myteam-admin

После данных настроек в разделе сервисов VK Teams появится иконка для работы со структурой организации.

Шаг 4. Выпустите SSL-сертификаты для поддоменов оргструктуры

Если вы не используете Wildcard-сертификаты, добавьте SSL-сертификаты для поддоменов files-n.<ваш домен> и files-n.<ваш домен>. Эти поддомены используются для функциональности оргструктуры в VK Teams.

Шаг 5. Настройте Nginx VK Teams

  1. На сервере VK Teams в конфигурационном файле /usr/local/nginx-im/conf/nginx.conf укажите IP-адрес сервера VK WorkSpace в случае инсталляции VK WorkSpace на одну виртуальную машину. Если у вас распределенная инсталляция VK WorkSpace, укажите IP-адреса серверов с ролью «фронт»:

    geo $prod_ip {
    127.0.0.0/8 1;
    10.32.0.0/16 1;
    default 0;
    }

  2. Перезагрузите сервер:

    nginx reload

Подключение структуры организации при отсутствии интеграции с Почтой VK WorkSpace

При отсутствии интеграции с Почтой VK WorkSpace функциональность оргструктуры в VK Teams обеспечивают сервисы:

  • Sys-org-adapt — наполняет оргструктуру мессенджера VK Teams, используя внешний источник данных о пользователях и организациях.
  • Org-nomail-adapt — заполняет поле «О себе» в профиле пользователя на основании внешнего источника данных о пользователях и организациях.

Более подробное описание сервисов представлено в документе «Архитектура и описание системы VK Teams» (не является частью публичной документации, обратитесь к представителю VK Tech, чтобы ознакомиться с документом).

API для наполнения оргструктуры в VK Teams

Сервис Sys-org-adapt работает с внешним источником данных о пользователях и организациях по описанному ниже API.

Получить подразделения

Метод позволяет получить информацию о подразделениях:

  • название подразделения;
  • уровень вложенности подразделения в иерархии оргструктуры;
  • почта руководителя.

Входные данные

Get <DOMAIN>/api/v2/units/

где <DOMAIN> — домен внешнего источника данных о пользователях и организациях.

Ограничения

Данный метод требует авторизации.

Для авторизации сервис Sys-org-adapt передает в заголовке Authorization авторизационный токен, который можно настроить в конфигурационном файле сервиса. Чтобы сделать это, перейдите в /usr/local/etc/sys-org-adapt-1.yaml и укажите в поле api_key авторизационный токен:

sys:
  api_key: "TOKEN"

Параметры

Имя Тип Описание
page
*required		 string Номер страницы
per_page
*required		 string Количество подразделений на странице
exclude_hidden boolean Если в запросе передано это значение, то в ответе не передаются подразделения, которые должны быть скрыты в оргструктуре VK Teams

Пример запроса для получения подразделений

curl https://<DOMAIN>/api/v2/units/?page=1&per_page=100&exclude_hidden=true

Формат ответа

{
  "objects": [
    {
      "id": 2, # идентификатор подразделения
      "parent_id": 1, # идентификатор родительского подразделения
      "email": "i_ivanov@YOUR_DOMAIN.ru", # почта руководителя подразделения
      "level": 7, # уровень вложенности подразделения при отсчете от корневого подразделения (level: 0)
      "name": "Юнит № 1", # название подразделения
    },
  ],
  "meta" : {
    "next": 2 # следующая страница
  }
}

Получить пользователей

Метод позволяет получить информацию о пользователях:

  • название должности;
  • название подразделения, в котором работает пользователь;
  • почта пользователя.

Также позволяет ограничивать добавление в оргструктуру технических аккаунтов и неактивных пользователей.

Входные данные

Get <DOMAIN>/api/v2/users

где <DOMAIN> — домен внешнего источника данных о пользователях и организациях.

Ограничения

Данный метод требует авторизации.

Для авторизации сервис Sys-org-adapt передает в заголовке Authorization авторизационный токен, который можно настроить в конфигурационном файле сервиса. Чтобы сделать это, перейдите в /usr/local/etc/sys-org-adapt-1.yaml и укажите в поле api_key авторизационный токен:

sys:
  api_key: TOKEN

Параметры

Имя Тип Описание
page
*required		 string Номер страницы
per_page
*required		 string Количество подразделений на странице
end_of_work__isnull boolean Если в запросе значение true, то в ответе передаются только те сотрудники, которые еще работают в компании

Пример запроса для получения пользователей

curl https://<DOMAIN>/api/v2/users/?page=1&per_page=100&end_of_work__isnull=true

Формат ответа

{
  "objects": [
    {
      "appointment_name": 1, # название должности пользователя
      "unit_id": 2, # подразделение, в котором работает пользователь
      "email": "i_ivanov@YOUR_DOMAIN.ru", # почта пользователя
      "is_technical_account": false # если аккаунт технический, он не будет добавлен в оргструткуру
      "is_active": true # будут добавлены только активные пользователи 
      "end_of_work": "2023-01-01" # если пользователь уволен уже не работает, то он не будет добавлен в оргструткуру
    },
  ],
  "meta" : {
    "next": 2 # следующая страница
  }
}

Шаг 1. Реализуйте API

Реализуйте методы API, описанные выше.

Шаг 2. Включите синхронизацию

Чтобы сервис Sys-org-adapt начал обходить внешний источник данных о пользователях и организациях, необходимо включить синхронизацию в etcd:

etcdctl --endpoints [ХОСТ_ETCD]:[ПОРТ_ETCD] put /vars/services/sys_org_adapt/production/public/service/unit_tree_updater_enabled true

Пример команды:

etcdctl --endpoints etcd.im-etcd.svc.cluster.local:2379 put /vars/services/sys_org_adapt/production/public/service/unit_tree_updater_enabled true

Шаг 3. Включите дополнительные настройки (опционально)

Заполнение поля «О себе»

Чтобы выгружать значение поля «О себе» из внешнего источника оргструктуры в профиль пользователя VK Teams, необходимо:

  1. В конфигурационном файле /usr/local/etc/nomail-1.conf добавить следующие строчки:

    nomail.connector.additional.extra.fields.enabled "true"
nomail.keycloak.additional.extra.fields organization,department,position,mobile
nomail.keycloak.about.fields [$sys:organization](vkteams://miniapp/orgstructure/?unitId=$sys:organizationid)\n[$sys:department](vkteams://miniapp/orgstructure/?unitId=$sys:departmentid)\n$sys:position\n$sys:syslink\n\nРуководитель:\n[$sys:leadfullname]({https://u.{DOMAIN}/}/profile/$sys:leademail)
nomail.connector.url {адрес org-nomail-adapt}
nomail.connector.method query
nomail.keycloak.compound.about.connectors.enabled false

  2. Перезапустить сервис Nomail:

    systemctl restart nomail-*

Отображение номера телефона отдельным полем

Чтобы номер телефона пользователя отображался в карточке контакта отдельным полем, необходимо:

  1. В конфигурационных файлах сервиса Front

    /usr/local/etc/front-1.conf

    /usr/local/etc/front-2.conf

    /usr/local/etc/front-3.conf

    /usr/local/etc/front-4.conf

    указать для поля userInfo.phone_from_prof_st значение true:

    userInfo.phone_from_prof_st: true

  2. Перезапустить сервис Front:

    systemctl restart front-*

  3. В конфигурационном файле сервиса Nomail /usr/local/etc/nomail-1.conf указать для поля user.phone_filed значение "mobile":

    user.phone_filed: "mobile"

  4. Перезапустить сервис Nomail:

    systemctl restart nomail-*

  5. В конфигурационный файл сервиса Prof-st /usr/local/etc/prof-st-1.conf добавить следующие строчки:

    app_anketa_phone_can_be_string true
app_fb_sync_create true
user.phone_filed "mobile"

  6. Перезапустить сервис Prof-st:

    systemctl restart prof-st-*

  7. В конфигурационный файл сервиса Feedog /oap/feedog_srv_post.tcl добавить строчку:

    set enableValidatePhone 0

  8. Перезапустить сервис Feedog :

    cpsh 4322
restart_job feedog