Интеграция с Яндекс Календарем

Сервер BOOCO Meteor (v 1.x) / Настройка интеграций с календарными системами

Введение

Интеграция BOOCO с Яндекс.Календарем с помощью микросервиса caldev-sync позволяет:

  • отображать расписание переговорных комнат из Яндекс.Календаря в Календаре на сервере BOOCO;
  • запускать сценарии автоматизации по началу, завершению и другим событиям календаря.

Микросервис caldav-sync предназначен для синхронизации с календарными системами, которые работают по стандарту CalDAV.

caldav-sync по заданному интервалу времени считывает список событий и добавляет их в BOOCO. Если он обнаружил новый календарь, то под него создается переговорная комната (может быть отключено в настройках).

Требования

Сервер BOOCO 1.x или 2.x, развернутый в Docker.

Быстрый старт (на примере Яндекс Календаря)

Для синхронизации с Яндекс Календарем потребуется учетная запись в Яндекс или Яндекс 360 для бизнеса (с любым тарифом). Для каждого помещения нужно создать свой календарь.

image

Подготовительные шаги

  1. Перейдите по ссылĸе. В пунĸте Создать пароль приложения выберите Календарь.
    2. ❗
    Пароль приложения отображается тольĸо один раз, поэтому следует сĸопировать его и сохранить.
  2. В BOOCO создайте пользователя и назначьте ему следующие права
    • read:any (booking) — чтение бронирований;
    • create:any (booking) — создание новых бронирований;
    • update:any (booking) — обновление существующих бронирований;
    • read:any (venue) — чтение списка помещений;
    • create:any (venue) — создание новых помещений;
    • create:own (log) — журналирование сообщений.
  3. Установите микросервис caldav-sync:
    • Войдите на сервер по SSH.
    • Создайте папку /opt/caldav-sync:
      • sudo mkdir /opt/caldav-sync
cd /opt/caldav-sync
    • Скачайте docker-compose.yml:
      •  sudo curl https://www.booco.ru/install/caldav-sync/docker-compose.yml --output docker-compose.yml
    • Скачайте шаблон файла с переменными окружающей среды .env:
      • sudo curl https://www.booco.ru/install/caldav-sync/template.env --output .env
    • В редакторе (nano, vi, vim, …) заполните необходимые параметры:
      • sudo nano .env

      Параметры BOOCO_HOST, CALENDAR_LOGIN CALENDAR_PASSWORD, BOOCO_LOGIN, BOOCO_PASSWORD обязательны к заполнению. Остальные можно оставить по умолчанию.

      BOOCO_HOST=https://demo.booco.ru/api
CALENDAR_LOGIN=
CALENDAR_PASSWORD=
BOOCO_LOGIN=
BOOCO_PASSWORD=
BUILD=latest
BOOCO_TOKEN_LOCATION='key/token.json'
BOOCO_TIMEOUT_READ=5000
BOOCO_TIMEOUT_WRITE=5000
BOOCO_TIMEOUT_CONNECT=3000
BOOCO_TIMEOUT_RESPONSE=10000
BOOCO_RETRY_COUNT=2
BOOCO_RETRY_INTERVAL=2500
SYNC_LOGGING=INFO
SYNC_PREFIX=YA
SYNC_DELAY=10000
SYNC_DELAY_BETWEEN=60000
SYNC_DELAY_INITIAL=10000
SYNC_SCHEDULED=true
FUTURE_DAYS=10
PAST_DAYS=0
CREATE_NEW_VENUES=true
TZ=Europe/Moscow
    • Создайте сеть web для работы загруженного docker-compose.yml. Запустите контейнер и посмотрите логи (чтобы выйти из просмотра логов, нажмите Ctrl + C):
      • sudo docker network create -d bridge web
sudo docker compose up -d
sudo docker logs caldav-sync -f

Отладка и рекомендации

  • Рекомендуем следующий подход:
    • Создайте все необходимые календари в Яндексе.
    • В каждом календаре создайте хотя бы одно событие.
    • Запустите caldav-sync c CREATE_NEW_VENUES=true в .env.
    • Дождитесь синхронизации и убедитесь, что все помещения созданы.
    • Остановите сервис и удалите лишние помещения в BOOCO (если они будут).
    • Установите CREATE_NEW_VENUES=false в .env.
    • Запустите caldav-sync.
  • Синхронизация вручную доступна через Swagger API: http://<имя сервера>:8080/api/sync/calendar.
  • Для поиска ошибок может потребоваться установить SYNC_LOGGING=DEBUG.

Описание переменных окружающей среды (.env)

  • BOOCO_HOST — адрес REST-клиента Booco (по умолчанию http://localhost:3000/api)
  • BOOCO_LOGIN — имя пользователя Booco
  • BOOCO_PASSWORD — пароль пользователя Booco
  • BOOCO_TOKEN_LOCATION — расположение и имя файла, где будет сохранён токен авторизации (по умолчанию — key/token.json)
  • BOOCO_TIMEOUT_READ — таймаут получения данных от клиента Booco в мс (минимум — 5 с, по умолчанию — 5 с)
  • BOOCO_TIMEOUT_WRITE — таймаут передачи данных клиенту Booco в мс. (минимум - 5 с., по умолчанию - 5 с.)
  • BOOCO_TIMEOUT_CONNECT — таймаут подключения к клиенту Booco в мс (минимум — 3 с, по умолчанию — 3 с)
  • BOOCO_TIMEOUT_RESPONSE — таймаут ответа от клиента Booco в мс. (минимум — 10 с, по умолчанию — 10 с)
  • BOOCO_RETRY_COUNT — количество повторных запросов к клиенту Booco в мс (минимум — 1 раз, по умолчанию — 2 раза)
  • BOOCO_RETRY_INTERVAL — задержка перед повторным запросом к клиенту Booco в мс (минимум — 2.5 с, по умолчанию — 2.5 с)
  • CALENDAR_LOGIN — логин подключения к Яндекс Календарю
  • CALENDAR_PASSWORD — специальный пароль приложения
  • SYNC_LOGGING — уровень журналирования для консоли и отправки на сервер — [OFF | ERROR | WARN | INFO | DEBUG] (по умолчанию — INFO)
  • SYNC_PREFIX — префикс для записей этого сервиса в Журнал (по умолчанию — CALDAV-SYNC)
  • CREATE_NEW_VENUES — флаг создания переговорных комнат [true | false] (по умолчанию — вкл. [true])
  • PAST_DAYS — целочисленное значение, количество дней от текущей даты, после которого заканчивается событие (по умолчанию — 7 дней)
  • FUTURE_DAYS — целочисленное значение, количество дней от текущей даты, до которого начинается событие (по умолчанию — 30 дней)
  • TZ — часовой пояс переговорной комнаты, строковое значение, например: Europe/Moscow (по умолчанию пустое).