1. Назначение и модель работы

Модуль BUSSOL DataBridge: импорт, экспорт и автоматизация каталога организует повторяемый обмен данными между 1С-Битрикс и файлами XLSX/XLSM/XLS/CSV, Google Sheets и внешними источниками. Версия 1.6.0 работает не только с элементами инфоблоков, но и с разделами/SEO, Highload-блоками, скидками/правилами корзины и наборами/комплектами.

Рекомендуемая модель эксплуатации: создать профиль, выполнить контрольный экспорт или dry-run импорта, проверить журнал, сделать резервную копию, запустить реальный обмен, а автоматизацию и расписание включать после успешной приёмки сценария на копии сайта.

2. Возможности версии 1.6.0

• Неограниченное число профилей; направления «Экспорт», «Импорт» и «Импорт и экспорт».
• Типы профилей: элементы/товары, разделы и SEO, Highload-блоки, скидки/правила корзины, наборы и комплекты.
• Форматы XLSX, XLSM, XLS и CSV; многолистовой импорт и экспорт.
• Импорт из ручного файла, HTTP/HTTPS/FTP/FTPS, email-вложений по IMAP и Google Sheets.
• Экспорт с автоматической доставкой на FTP/FTPS, HTTP(S), Google Drive, Google Sheets и по email.
• Элементы и свойства инфоблоков, разделы, SEO, файлы, изображения, цены, валюты, товарные параметры и остатки отдельных складов.
• Создание и обновление SKU прямо из строк товарного профиля, включая свойства, цены и складские остатки.
• Составные ключи, стратегии найден/не найден, дубликаты, деактивация или удаление отсутствующих объектов там, где это поддерживает тип профиля.
• Highload-профили с UF-полями, составными ключами, dry-run и удалением отсутствующих записей.
• Создание свойств инфоблока, свойств SKU и UF-полей по явно размеченным заголовкам файла.
• Безопасные цепочки преобразований колонок без eval и произвольного PHP-кода.
• Внешние JPEG/PNG/GIF/WebP с SSRF-защитой, проверкой MIME, размера и геометрии.
• XLSX/XLSM-шаблоны с сохранением стилей, формул и VBA-пакета XLSM.
• Расписание: интервал, ежедневно или по дням недели.
• Dry-run и журналируемый откат выполненного импорта.
• Очередь, прогресс, статистика, журнал, групповые права D/R/W и защищённая выдача файлов.

3. Системные требования

4. Установка обновление и удаление

Чистая установка

1. Распакуйте каталог bussol.iblockexcel в /local/modules/ сайта либо установите решение штатным механизмом Marketplace.
2. Откройте «Marketplace → Установленные решения», найдите BUSSOL DataBridge и нажмите «Установить».
3. Установщик создаст таблицы модуля, административные прокси и тему, зарегистрирует меню и агент \Bussol\IblockExcel\Service\Agent::run(); с интервалом 60 секунд.
4. Откройте настройки модуля и назначьте групповые права, а также глобально разрешите/запретите HTTP/FTP- и email-источники.
5. Перейдите в «BUSSOL → BUSSOL DataBridge → Профили обмена» и создайте тестовый профиль.

Обновление с 1.2.4–1.5.x до 1.6.0

• Сделайте резервную копию каталога модуля и базы данных.
• При штатном обновлении Marketplace используйте механизм обновлений решения.
• При ручном обновлении замените каталог /local/modules/bussol.iblockexcel новой версией, не удаляя решение и его таблицы.
• Схема таблиц в 1.6.0 не меняется: новые параметры хранятся в SETTINGS_JSON, rollback-журналы — в файловой системе.
• Убедитесь, что административные прокси и тема обновлены. При контролируемой переустановке обязательно выберите сохранение данных.
• Очистите управляемый кеш Битрикс и кеш браузера, затем проверьте меню, права, один экспорт и dry-run одного импорта.

Удаление

Деинсталлятор удаляет агент, обработчик меню, административные прокси и тему модуля. В диалоге удаления можно сохранить таблицы профилей, заданий и журнала. Если данные не сохраняются, таблицы b_bussol_ibx_profile, b_bussol_ibx_job и b_bussol_ibx_log удаляются.

5. Права настройки и навигация

Права групп

Настройки модуля

Путь к интерфейсу: BUSSOL → BUSSOL DataBridge. Внутри доступны «Профили обмена» и «Задания и журнал». Администратор сайта получает полный доступ независимо от группового права.

6. Создание и параметры профиля

Профиль описывает устойчивый сценарий обмена. Интерфейс разделён на три шага: «Профиль» (сущность, источник и формат), «Столбцы» (состав данных) и «Логика» (фильтр, импорт, формат, доставка и расписание).

Рекомендуемый порядок настройки

1. Создайте профиль, выберите тип сущности и целевой объект.
2. Выберите направление и формат.
3. Для автоматического импорта настройте источник и его учётные данные.
4. Настройте выбранные столбцы, заголовки, порядок и преобразования.
5. Настройте ключи и стратегии импорта; для товарного профиля при необходимости — отдельные правила SKU.
6. Настройте листы, внешние изображения, создание схемы и rollback.
7. Для экспорта при необходимости настройте шаблон и каналы доставки.
8. Выполните ручную приёмку, после чего включите расписание.

7. Конструктор столбцов

Для каждой колонки задаются пользовательский заголовок, порядок, разрешение экспорта/импорта, базовое преобразование и дополнительная цепочка правил. Заголовки выбранных колонок должны быть уникальны без учёта регистра. Порядок меняется drag-and-drop или кнопками вверх/вниз.

Базовые преобразования

Цепочки правил

Дополнительные правила выполняются сверху вниз, по одному правилу на строку. Строки, начинающиеся с #, считаются комментариями. Поддерживаются следующие команды:

8. Экспорт и фильтрация

Запуск экспорта

1. Откройте активный профиль с направлением EXPORT или BOTH.
2. Настройте экспортируемые колонки, фильтр и формат.
3. При необходимости настройте многолистовой режим, XLSX/XLSM-шаблон и каналы доставки.
4. Нажмите «Сохранить и запустить экспорт» либо дождитесь расписания.
5. После статуса «Готово» скачайте файл в карточке задания и проверьте записи доставки в журнале.

Многолистовой экспорт

Шаблон XLSX / XLSM

Для XLSX/XLSM можно загрузить существующий шаблон, выбрать лист по номеру или имени, строку заголовков и первую строку данных. Модуль копирует книгу, заполняет выбранный лист, переносит стили и формулы строки-шаблона. Относительные ссылки формул сдвигаются, абсолютные ссылки с $ сохраняются. Формулы ниже расширяемого блока также сдвигаются. Для XLSM нужен именно .xlsm-шаблон, чтобы сохранить VBA-пакет.

Автоматическая доставка

Для основного элементного экспорта перед записью строки вызывается событие OnBeforeExportRow; обработчик может изменить строку или вернуть false, чтобы её исключить.

9. Импорт и стратегии обработки

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

Ключ поиска

Ключ может состоять из одной или нескольких импортируемых keyable-колонок. Для элементов это ID/XML_ID/CODE/NAME и одиночные нефайловые свойства; для других типов доступность ключей определяется каталогом колонок. Все части составного ключа должны быть заполнены.

Торговые предложения SKU

Если выбран инфоблок товаров с настроенным инфоблоком предложений, одна строка может одновременно создать/обновить товар и одно SKU. Для SKU выбирается собственный составной ключ и отдельные стратегии «найден / не найден». Поддерживаются поля, свойства, каталог, цены, валюты и остатки складов. Для нескольких предложений одного товара используйте отдельную строку на каждое предложение. Скрытая перепривязка существующего SKU к другому товару блокируется.

Разделы и списки

• SECTION_PATHS может разрешать путь и при включённой опции создавать отсутствующую иерархию разделов.
• В самостоятельном профиле разделов PARENT_PATH может создать отсутствующий родительский путь.
• Для элементного профиля можно автоматически создавать новые значения существующих свойств типа «Список».

Создание свойств и UF из заголовков

Включите «Создавать свойства / UF из заголовков». Обычный неизвестный заголовок не меняет схему — новое поле создаётся только по явному префиксу.

PROPERTY:BRAND
PROPERTY:COLOR{type=L;name=Цвет;multiple=N;sort=500;values=Красный|Синий|Белый}
SKU:PROPERTY:SIZE{type=L;name=Размер;values=S|M|L|XL}
UF_VENDOR{type=string;name=Поставщик;multiple=N;required=N}
UF_STATUS{type=enumeration;name=Статус;values=Новый|Активный|Архив}

Для свойств инфоблока поддерживаются типы S, N, L, F, E, G. Для UF: string, integer, double, boolean, date, datetime, enumeration, file. Созданные свойства, UF и значения списков записываются в rollback-журнал, если он включён.

Безопасный запуск

1. Создайте резервную копию базы данных.
2. Включите «Тестовый импорт — без записи изменений».
3. Запустите файл или источник и проверьте счётчики/журнал.
4. Исправьте данные, преобразования, ключи и стратегии.
5. Отключите dry-run; оставьте включённым rollback-журнал.
6. Запустите реальный импорт и проверьте результат до включения расписания.

10. Форматы значения файлов и изображений

Листы и строки

Для XLSX/XLSM/XLS-импорта можно указать * (все листы), список 1,3,5 или диапазоны 1-3,5-7. Заголовок определяется заново на каждом выбранном листе. Также задаются явная строка заголовков и первая строка данных; значение 0 включает автоматический режим.

Источники импорта

Множественные значения

Множественные значения объединяются и разбираются по разделителю профиля, по умолчанию |. Выберите символ, который не встречается внутри отдельных значений. Для наборов/комплектов тот же разделитель используется для ITEM_IDS, QUANTITIES и SORTS.

Файлы и изображения

• При импорте файловых значений принимается существующий ID файла Битрикс или локальный путь внутри /upload/.
• HTTP(S)-URL изображения разрешён только при включённой опции «Разрешить внешние изображения».
• Допустимы JPEG, PNG, GIF и WebP; SVG из внешнего источника не принимается.
• По умолчанию максимальный размер внешнего изображения — 10 МБ, лимит пикселей — 40 000 000; значения настраиваются в профиле.
• Можно задать allowlist хостов. Пустой список разрешает любой публичный HTTP(S)-хост, прошедший SSRF-проверки.
• Пустая ячейка для файлового поля удаляет текущее файловое значение там, где сущность поддерживает такую операцию.

11. Задания прогресс и журнал

Карточка задания показывает обработанные, созданные, обновлённые, пропущенные записи и ошибки. Журнал выводит до 500 последних событий в обратном порядке с уровнем, номером строки, ID сущности и сообщением.

• Задание в очереди можно выполнить немедленно или отменить.
• Экспортный файл и исходный импортный файл скачиваются через административную страницу после проверки прав.
• После экспорта в журнал попадают успешные каналы автоматической доставки.
• Для импорта с включённым rollback создаётся серверный журнал обратных действий.

Откат импорта

Если в профиле включено «Записывать журнал отката импорта» и импорт выполнялся не в dry-run, для завершённого задания со статусом «Готово» или «Ошибка» может быть доступна команда «Откатить импорт». Откат ставится в очередь как отдельное задание типа ROLLBACK.

• Откат покрывает поддерживаемые изменения элементов, свойств, привязок разделов, каталога, цен и складов.
• Поддерживается откат созданных элементов/SKU, разделов/SEO, Highload-записей, созданных свойств/UF/значений списков, скидок и наборов/комплектов.
• Два одновременных rollback-задания для одного импорта блокируются.
• После полностью успешного rollback его журнал удаляется; повторно применить тот же откат нельзя.

12. Очередь агент и хранение

При установке регистрируется агент \Bussol\IblockExcel\Service\Agent::run(); с интервалом 60 секунд. За один проход агент восстанавливает зависшие задания, проверяет расписание, выполняет самое раннее задание очереди и очищает часть старых записей.

• Задания RUNNING старше двух часов помечаются ошибкой «Выполнение прервано или превысило 2 часа».
• Планировщик использует lock-файл и не ставит один и тот же профиль/операцию повторно, если уже есть QUEUED/RUNNING задание.
• За один проход ScheduleService ставит не более 5 плановых заданий.
• Агент выполняет одно самое раннее задание очереди за проход.
• За один проход очищается до 20 старых DONE/ERROR/CANCELLED заданий вместе с файлом, журналом и rollback-журналом.

Режимы расписания

Плановый импорт использует REMOTE, EMAIL или GOOGLE_SHEETS, выбранный в профиле. Плановый экспорт может после создания файла выполнить все включённые каналы доставки.

Файловое хранение

13. Безопасность

• Выдавайте W только доверенным администраторам и контент-менеджерам.
• При необходимости глобально отключайте REMOTE и EMAIL источники в настройках модуля.
• Для поставщиков с изображениями используйте allowlist доменов.
• Не помещайте пароли в HTTP/FTP URI; используйте отдельные поля профиля.
• Перед включением DELETE/DEACTIVATE, автосоздания схемы и расписания выполните dry-run и backup.

14. Расширение разработчиком

Модуль использует стандартный механизм событий Битрикс для module ID bussol.iblockexcel. В версии 1.6.0 публичные события сохранили сигнатуры предыдущих версий.

Перед экспортом строки элемента/товара

OnBeforeExportRow(array &$row, array $elementFields, array $profile): bool|null

Событие вызывается основным ExportService для профиля элементов/товаров. Обработчик может изменить row по ссылке. Возврат false исключает строку из файла.

Перед импортом строки

OnBeforeImportRow(array &$valuesByKey, int $rowNumber, array $profile): bool|null

Событие вызывается при импорте элементов/товаров, разделов и Highload-блоков. Обработчик может нормализовать значения по ссылке; false пропускает строку. Профили скидок и наборов/комплектов используют отдельные сервисы и это событие не вызывают.

15. Хранение данных и структура модуля

В 1.6.0 схема таблиц не меняется по сравнению с предыдущими версиями: новые функции сохраняют параметры внутри существующего SETTINGS_JSON.

16. Ограничения и совместимость

• DataBridge не создаёт сами инфоблоки и Highload-блоки; создание схемы ограничено свойствами инфоблока, свойствами SKU и UF-полями существующих сущностей.
• Автосоздание свойств инфоблока поддерживает типы S/N/L/F/E/G; UF — string/integer/double/boolean/date/datetime/enumeration/file.
• Профиль скидок поддерживает безопасно ограниченный набор правил; произвольные сложные деревья условий/действий Битрикс из строкового кода не генерируются.
• Для набора/комплекта, если у владельца есть несколько наборов одного типа, для однозначного обновления нужен SET_ID.
• Экспорт XLSM требует существующего .xlsm-шаблона; без него профиль с экспортом XLSM не сохраняется.
• Шаблонизированный XLSX/XLSM заполняет один целевой лист; многолистовое разбиение применяется обычному экспорту.
• Импорт бинарного BIFF .xls требует локального LibreOffice/soffice; SpreadsheetML 2003 .xls читается напрямую.
• Google Sheets/Drive требуют OAuth Client ID, Client Secret, Refresh Token и исходящий доступ к Google API.
• Email-источник требует PHP imap, FTP/FTPS — PHP ftp.
• Внешние URL принимаются только для растровых изображений JPEG/PNG/GIF/WebP и только при включённой опции; SVG запрещён.
• Формулы при обычном импорте не пересчитываются модулем как Excel-приложением; шаблонный экспорт переносит формулы и включает полный пересчёт книги при открытии.
• Rollback восстанавливает только изменения, которые записал DataBridge; это не транзакция всей базы и не замена backup.
• Стратегия «Последняя строка» и массовая обработка отсутствующих объектов требуют памяти пропорционально числу уникальных ключей.
• Очень большие обмены необходимо тестировать с реальными лимитами PHP, базы, диска, почты и внешних API.

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

17. Диагностика

18. Чек-лист приёмки

• Есть актуальная резервная копия файлов и базы данных.
• Проверены PHP 8.1+, mbstring/zip/XMLReader/SimpleXML и дополнительные imap/ftp/LibreOffice по используемым сценариям.
• Проверены iblock и необходимые catalog/sale/highloadblock.
• Веб-процесс может записывать /upload/bussol.iblockexcel и системный temp.
• Модуль отображается в меню BUSSOL; права D/R/W проверены на тестовых группах.
• Глобальные REMOTE/EMAIL-переключатели соответствуют политике проекта.
• Создан тестовый профиль нужного типа; заголовки уникальны, выбранные колонки и порядок корректны.
• Экспорт выбранных XLSX/XLSM/XLS/CSV открывается ожидаемым приложением; многолистовой режим проверен при использовании.
• Если используется XLSX/XLSM-шаблон — проверены стили, формулы, целевой лист и сохранение макросов XLSM.
• Dry-run формирует ожидаемые счётчики и журнал без изменения данных.
• Реальный импорт проверен на создании, обновлении, пропуске и ошибке.
• Составные ключи и стратегия дублей проверены отдельными тестовыми строками.
• SKU проверены на создании/обновлении, ценах и остатках складов.
• Разделы/SEO и HL-профили проверены, если используются.
• Создание PROPERTY:/SKU:PROPERTY:/UF_ проверено на тестовой схеме.
• Удаление/деактивация отсутствующих объектов проверены только в ограниченной тестовой области.
• Внешние изображения проверены на допустимом и запрещённом host/MIME/размере.
• REMOTE/IMAP/Google Sheets источники проверены вручную до включения расписания.
• FTP/HTTP/Google/email доставка экспорта проверена для каждого включённого назначения.
• Планировщик проверен в выбранном режиме; нет дублирующих QUEUED/RUNNING заданий.
• Rollback проверен на тестовом реальном импорте; команда создаёт отдельное задание и восстанавливает ожидаемые изменения.
• Агент обрабатывает очередь, помечает зависшие задания и очищает старые данные в соответствии с retention.
• Сценарии аварийного восстановления, backup и ответственность за внешние интеграции задокументированы для проекта.