В BI Конструкторе можно работать с внешними базами MySQL и PostgreSQL. Это удобно, если часть данных хранится отдельно: в интернет-магазине, внутреннем сервисе или другой корпоративной базе.

Например, если компания хранит заказы в PostgreSQL. После подключения базы к BI Конструктору можно выбрать таблицу с продажами, создать датасет и построить график по сумме заказов. Так руководитель увидит динамику продаж в одном отчете вместе с данными из Битрикс24.

Что нужно подготовить для подключения базы данных

Перейдите в раздел BI Конструктор > Рабочее место аналитика > Подключения > Создать и выберите MySQL или PostgreSQL.

Дальнейшие действия зависят от версии Битрикс24.

Облачный Битрикс24. Внешняя база данных подключается через серверное приложение. Сначала нужно настроить приложение по инструкции, а затем вернуться к созданию подключения.

Приложение будет связывать Битрикс24 и базу данных: получать запрос, подключаться к MySQL или PostgreSQL, читать список таблиц и структуру полей, затем передавать данные в BI Конструктор.
Серверное локальное приложение без пользовательского интерфейса

Чтобы настроить приложение, подготовьте:

• Сервер — компьютер или виртуальная машина для размещения приложения. На нем будут храниться файлы и выполняться работа приложения. Например, можно использовать виртуальный сервер компании или отдельный сервер в вашей инфраструктуре.
• Docker и Docker Compose — установите на сервере, чтобы запустить приложение в контейнере. Docker создает изолированную среду для приложения, а Docker Compose помогает запустить его с нужными настройками. Ознакомьтесь с документацией Docker и установите версию для своей операционной системы:
  Docker Desktop on Windows
  Docker Desktop on Linux
  Docker Desktop on Mac
• Файлы для сборки серверного приложения. Скачайте файлы из репозитория и загрузите их на сервер.
  Bitrix24 BI Connector Extension
• Доступ к внешней базе MySQL или PostgreSQL — нужен, чтобы приложение могло подключиться к базе и прочитать данные. Подготовьте адрес базы, порт, название базы, логин и пароль пользователя с правами на чтение таблиц.
• Публичный HTTPS-адрес для серверного приложения — нужен, чтобы Битрикс24 мог обратиться к приложению. Адрес вида localhost не подойдет, потому что он доступен только внутри сервера. Используйте адрес вида https://bi-connector.company.ru.

Коробочная версия Битрикс24. Серверное приложение настраивать не нужно. После выбора MySQL или PostgreSQL можно сразу указать параметры подключения и работать с базой данных. Перед настройкой подготовьте адрес базы, порт, название базы, логин и пароль пользователя. Убедитесь, что сервер Битрикс24 видит базу по сети.

Проверьте названия таблиц и полей во внешней базе. Они должны соответствовать двум правилам:

• Названия таблиц должны начинаться с латинской буквы и содержать только строчные латинские буквы, цифры и нижнее подчеркивание. Например: users, order_items, customer_data_2024.
• Названия полей должны начинаться с латинской буквы и содержать только заглавные латинские буквы, цифры и нижнее подчеркивание. Например: ID, USER_ID, ORDER_DATE.

Как установить приложение на сервер

Серверное приложение связывает Битрикс24 и внешнюю базу. Оно выполняет четыре действия:

• проверяет подключение к базе,
• получает список таблиц,
• получает структуру таблицы и типы полей,
• передает данные в BI Конструктор.

Пользователю не нужно запускать эти действия вручную. Они выполняются автоматически, когда пользователь проверяет подключение, выбирает таблицу или строит отчет. Чтобы установить приложение, выполните шесть шагов:

1. Перейдите в папку приложения на сервере. Все команды нужно выполнять на сервере, где будет работать приложение. Откройте терминал и перейдите в папку с файлами приложения. Проверьте, что в папке есть файл docker-compose.yml. Если он есть в списке, значит, вы находитесь в нужной папке. Команды Docker Compose нужно выполнять именно из нее.

2. Создайте файл настроек. В папке приложения есть файл .env.example. Это пример настроек. На его основе нужно создать рабочий файл .env. Файл хранит настройки приложения: публичный адрес, параметры логирования, настройки кеша и данные локального приложения Битрикс24. Выполните команду:

 
cp .env.example .env
 

3. Укажите публичный адрес приложения. Откройте файл .env и укажите адрес, по которому Битрикс24 будет обращаться к серверному приложению. Пример настроек:

APP_DOMAIN=https://bi-connector.company.ru
APP_ENV=production
LOG_LEVEL=INFO

APP_DOMAIN — публичный HTTPS-адрес приложения. Он должен открываться из интернета, чтобы облачный Битрикс24 мог отправлять запросы к приложению. Адрес вида localhost не подойдет. Такой адрес доступен только внутри сервера или контейнера. Например, если приложение работает на сервере в Docker, а снаружи открывается через домен, схема может быть такой:

https://bi-connector.company.ru → сервер с приложением → Docker-контейнер

Используйте действующий SSL-сертификат. Битрикс24 должен открывать адрес приложения по HTTPS без предупреждений о безопасности.

4. Проверьте Docker-сеть. Приложение использует внешнюю сеть shared_db_network. Она нужна, чтобы приложение могло обращаться к базам данных, которые работают в Docker или доступны через общую сеть. Если запускаете приложение командой make start, сеть создастся автоматически. Если запускаете контейнеры через Docker Compose напрямую, создайте сеть вручную:

 
docker network create shared_db_network

Если Docker ответит, что сеть уже существует, это не ошибка. Значит, ее создали раньше.

5. Запустите приложение. Соберите и запустите приложение на сервере. Выполните команду:

 
make build
make start
 

Команда make build собирает Docker-образ приложения. Команда make start запускает контейнер.

6. Проверьте, что приложение запустилось. Выполните команду, чтобы посмотреть статус контейнеров:

docker compose ps

Если приложение запущено, в статусе контейнера будет значение Up. После этого проверьте, что приложение отвечает по публичному адресу:

curl -i https://bi-connector.company.ru/

Если приложение отвечает, можно переходить к созданию локального приложения в Битрикс24. Ответ может выглядеть как сообщение об ошибке без действия, например: {"error":"Unknown action: "}. Такой ответ появляется, когда запрос отправлен без параметра действия. Рабочие запросы будет отправлять Битрикс24: при проверке подключения, выборе таблицы и создании датасета.

Как создать локальное приложение в Битрикс24

Перейдите в раздел Приложения > Разработчикам > Другое > Локальное приложение. Заполните параметры:

• Локальное приложение — укажите тип Серверное. Такой тип подходит для приложения, которое работает на сервере и обменивается данными с Битрикс24 через REST API.
• Путь вашего обработчика — публичный HTTPS-адрес серверного приложения. По этому адресу Битрикс24 будет отправлять запросы к приложению. Например: https://bi-connector.company.ru/.
• Путь для первоначальной установки — адрес установочного файла приложения. Он вызывается при установке локального приложения в Битрикс24. Например: https://bi-connector.company.ru/install.php.
• Использует только API — включите опцию. Она нужна для приложения без отдельного интерфейса в Битрикс24. Пользователь не будет открывать приложение как страницу: BI Конструктор будет обращаться к нему автоматически через REST API.
• Настройка прав — добавьте право Коннектор BI-аналитики (biconnector). Это право нужно, чтобы приложение могло работать с источниками данных BI Конструктора.

Когда заполните параметры, нажмите Сохранить.

После сохранения Битрикс24 покажет служебные поля:

• Код приложения (client_id) — идентификатор локального приложения. Он нужен серверному приложению, чтобы обращаться к Битрикс24.
• Ключ приложения (client_secret) — секретный ключ локального приложения. Он подтверждает, что запросы идут от вашего приложения.

Скопируйте client_id и client_secret. Вернитесь на сервер и заполните параметры в файле .env:

 
BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID=ваш_client_id
BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET=ваш_client_secret
BITRIX24_PHP_SDK_APPLICATION_SCOPE=biconnector

Сохраните файл .env в кодировке UTF-8 без дополнительных символов в начале файла. Иначе приложение может не прочитать настройки. Затем перезапустите приложение на сервере:

 
docker compose restart app

Вернитесь в карточку локального приложения в Битрикс24 и нажмите Переустановить приложение. После этого в BI Конструкторе можно будет установить соединение с базой данных.

Как подключить внешнюю базу данных

Перейдите в раздел BI Конструктор > Рабочее место аналитика > Подключения > Создать. Выберите источник данных: MySQL Database Connector или PostgreSQL Database Connector.

Заполните параметры подключения:

• Название — укажите понятное название подключения. Оно будет отображаться в списке подключений BI Конструктора.
• Host — адрес сервера, на котором находится база данных. Не указывайте localhost, если база находится на другом сервере: приложение будет искать базу внутри своего окружения. Например, укажите db.company.local, 10.10.20.15 или имя контейнера, если база работает в Docker и подключена к той же сети.
• Port — порт подключения к базе данных. Для PostgreSQL используют порт 5432, для MySQL — 3306. Если в вашей инфраструктуре настроен другой порт, укажите его.
• Database — название базы данных, из которой нужно получать данные для отчетов.
• Username — логин пользователя базы данных.
• Password — пароль пользователя базы данных.

Когда заполните параметры, нажмите Проверить подключение. Если проверка прошла успешно, нажмите Создать. После создания подключения Битрикс24 предложит создать таблицу из внешней базы данных. Нажмите Создать таблицу.

Как создать таблицу и датасет

В форме создания таблицы выберите нужную Таблицу из внешней базы данных. Справа появится Предпросмотр данных. В нем можно проверить, какие поля и строки BI Конструктор получил из внешней базы. В режиме предпросмотра отображается только часть данных.

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

В блоке Настройка колонок таблицы проверьте, правильно ли Битрикс24 определил поля и их типы данных. Если поля и типы данных определены правильно, нажмите Создать.
Как настроить колонки
Как настроить форматы и типы данных

После этого Битрикс24 покажет сообщение, что таблица создана. Нажмите Создать датасет. Датасет нужен, чтобы использовать данные в отчетах и графиках BI Конструктора.

После создания датасета можно построить график и добавить его в дашборд. Например, на основе таблицы можно сделать датасет по заказам, построить график по сумме продаж и добавить его в отчет руководителя.
Как создавать отчеты в BI Конструкторе

• Битрикс24 BI-аналитика
• BI Конструктор для создания аналитических отчетов
• Настройки BI-аналитики