Импорт документов

← Назад к разделу «Модули»

Модуль document_import загружает CSV, XLSX, XLS и XML в документы выбранной рубрики. Он заменяет старый универсальный импорт: данные сохраняются через штатный DocumentMutationService, поэтому выполняются проверка alias, поля, хуки сохранения, аудит и сброс связанного кеша.

Быстрый запуск

Откройте Модули → Импорт документов и создайте профиль.
Выберите рубрику и формат файла. Для XML укажите повторяемый элемент, для Excel при необходимости задайте лист.
Нажмите запуск профиля и загрузите новый исходный файл.
Проверьте найденные колонки и первые строки.
Сопоставьте колонки источника с реквизитами документа и полями рубрики.
Для обновления существующих документов отметьте один или несколько ключей поиска.
Запустите импорт и дождитесь завершения всех порций.

Файл не хранится в профиле. Профиль запоминает формат, сопоставление, ключи и режим выполнения, а при каждом запуске принимает новый источник.

Форматы источника

Формат	Настройка	Примечание
CSV	разделитель или автоопределение	Первая строка должна содержать названия колонок.
XLSX	название или номер листа	Пустое значение выбирает первый лист.
XLS	название или номер листа	Читается встроенной библиотекой PHPExcel.
XML	имя повторяемого элемента	Дочерние элементы и атрибуты становятся колонками.

Максимальный размер источника составляет 50 МБ. Загруженный файл проходит общую UploadPolicy и хранится вне публичного каталога до завершения или удаления запуска.

Сопоставление

Каждое правило связывает одну колонку источника с одной целью. Одну цель нельзя выбрать дважды. Доступны системные реквизиты документа и все актуальные поля выбранной рубрики.

Для правила можно задать:

преобразование: без изменений, обрезка пробелов, целое, десятичное число, дата, логическое значение, нижний или верхний регистр, JSON;
значение по умолчанию для пустой колонки;
обязательность значения;
шаблон, в котором {Название колонки} подставляет данные текущей строки;
участие в поиске существующего документа;
точное совпадение или поиск по вхождению.

Для создания документа обязательно сопоставьте название. В качестве ключей допустимы название, alias и поля рубрики. Несколько ключей объединяются условием И: документ должен совпасть по каждому из них. Для стабильного повторного импорта лучше использовать внешний ID, артикул или иной уникальный реквизит, а не название.

Режим запуска

Опция	Поведение
Создавать новые	Создаёт документ, когда совпадение по ключам не найдено.
Обновлять найденные	Изменяет только сопоставленные реквизиты найденного документа.
Отключить отсутствующие	После успешного прохода выключает активные документы рубрики, которых не было в источнике.
Стоп при ошибке	Прерывает запуск на первой ошибочной строке.

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

Импорт выполняется порциями. Позиция хранится в БД, поэтому прерванный браузером запуск можно продолжить из вкладки Запуски. В истории видны созданные, обновлённые, пропущенные и ошибочные строки.

Хуки

Хук	Назначение
`document_import.source.prepared`	Источник разобран, известны профиль и запуск.
`document_import.row.normalized`	Позволяет изменить значения одной строки до сопоставления.
`document_import.document.payload`	Изменяет payload перед штатным сохранением документа.
`document_import.document.saved`	Документ успешно создан или обновлён.
`document_import.run.started`	Запуск настроен и начал обработку.
`document_import.run.completed`	Все строки и финализация обработаны.
`document_import.run.cancelled`	Пользователь остановил запуск.

Общие хуки документов content.document.saving и content.document.saved также выполняются, потому что модуль не обходит нативный цикл сохранения.

Удаление

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

7.2 KiB Raw Blame History