Инструкция по работе с утилитой миграции SPToMPMigrateApp

Утилита миграции Vitro.Server.SPToMPMigrate (Vitro.Server.SPToMPMigrate.exe) переносит папки и файлы, созданные в системе Vitro SP, в систему Vitro MP с сохранением даты создания, авторства, версионности и прочих настраиваемых атрибутов.

Предварительные действия

Для работы утилиты нужны решения Migration, которые надо разместить в Solutions на сервере Vitro MP:

Windows — C:\Program Files\Vitro Software\Vitro\Server\Solutions\Migration
Linux — /etc/Vitro/Server/Solutions/Migration

Утилита запускается на машине с Vitro SP с доступом к SQL Server (база Vitro и контентная база SharePoint WSS_Content). Строка подключения к SQL читается из Conf\vitro.config сервера Vitro MP (объект SqlConnectionString), а не из config.json.

Рядом с исполняемым файлом должны находиться config.json и каталог Scripts\ с SQL-процедурами. Логи пишутся в каталог logs\ (файлы SPToMPMigrate-YYYYMMDD-HHmm.log).

Режимы работы утилиты

Режимы задаются массивом ModeList в config.json и выполняются в указанном порядке.

Перед обработкой каждого режима утилита автоматически:

Разворачивает SQL-процедуры procMigration_Table и procMigration_{Mode} (из Scripts\ или Scripts\{Customer}\).
Выполняет procMigration_Table — создаёт или обновляет служебную таблицу Migration.
Выполняет procMigration_{Mode} — заполняет таблицу Migration данными из Vitro SP.
Обрабатывает подготовленные записи через API Vitro MP.

Обязательные режимы (базовая миграция структуры и связей):

Folder — перенос папочной структуры. Подготовка: procMigration_Folder для каждой пары из LibraryMap. Обработка: создание папок в MP.
File — перенос файлов. Подготовка: procMigration_File (дополнительно актуализирует папки) по LibraryMap. Обработка: загрузка файлов и версий.
Reference — перенос связей между файлами и папками. Подготовка: procMigration_Reference. Переносятся связи с типом:
- 1 — внешняя ссылка (вставка) на / является внешней ссылкой (вставка) для;
- 2 — внешняя ссылка (наложение) на / является внешней ссылкой (наложение) для;
- 3 — связано с.

Дополнительные режимы (подключаются в ModeList при необходимости):

Member — перенос прав Vitro «Участники». Подготовка: procMigration_Member. В MP создаётся элемент в списке «Разрывы прав» с участником из полей SP VitroProjectEditRole и VitroProjectFullControlRole с правом доступа Изменить.
Sign — перенос электронных подписей файлов. Подготовка: procMigration_Sign. Переносятся подпись, сертификат, версия, автор и дата для уже смигрированных файлов.
Issue — перенос замечаний к файлам и папкам. Подготовка: procMigration_Issue. Маркапы переносятся.
List — работа со справочниками: перенос данных справочников в Vitro MP или заполнение служебного поля sp_id на существующих записях. Обычно выполняется до миграции файловой структуры (добавить "List" в начало ModeList).

Пример обязательной цепочки:

"ModeList": [ "Folder", "File", "Reference" ]

Пример с дополнительными режимами:

"ModeList": [ "Folder", "File", "Reference", "Member", "Sign", "Issue" ]

При повторном запуске режима повторно обрабатываются записи с ошибками, а также элементы, у которых в SP изменилась дата (FinishDate пустая или меньше ModifiedDate).

Параметры утилиты

Параметры задаются в файле config.json в каталоге с исполняемым файлом.

Параметр	Пример значения	Описание
Customer	`"Default"`	Имя заказчика для кастомных SQL-скриптов в `Scripts\{Customer}\`. Если скрипт не найден, используется `Scripts\procMigration_{Mode}.sql`.
WebUrl	`http://sp.vitrocad.ru`	Адрес Vitro SP
Url	`https://mp.vitrocad.ru`	Адрес Vitro MP
Login	`admin_user`	Логин технической учётной записи Vitro MP
Password	`admin_password`	Пароль технической учётной записи Vitro MP
ModeList	`[ "Folder", "File", "Reference" ]`	Список и порядок режимов работы утилиты
SkipFieldMapError	`true`	Флаг пропуска ошибок маппинга лукапов. Если в Vitro SP есть значения справочников, которые не сопоставились в MP, они выводятся в лог. При `false` утилита завершит работу при наличии таких записей
SkipUserMapError	`true`	Флаг пропуска ошибок маппинга пользователей. Если в Vitro SP есть пользователи, которых нет в MP, они выводятся в лог. При `false` утилита завершает работу. Сопоставление — по email
DefaultUserId	`00000000-0000-0000-0000-000000000001`	GUID пользователя MP, подставляемый при отсутствии сопоставления по email
SwitchOffIriParsing	`false`	Отключение обработки ссылок от скрытых символов. Полезно, если в SP есть файлы или папки с «невидимыми» символами в имени и из-за этого не удаётся получить файл
ThreadNumber	`2`	Количество потоков. Параллельно работают все режимы, кроме Folder (всегда 1 поток)
MigrateAllFileVersion	`true`	При `true` переносятся все версии файла, при `false` — только последняя
QrCodeReplace	`false`	При `true` и установленном поле QR в SP тело файла формируется заново (PDF с QR-кодом), иначе файл читается из SP или внешнего хранилища
LibraryMap	`{ "http://sp2013/TempLibrary/Project1": "966e62c5-a803-49a0-a1be-e680d130c481" }`	Переносимые корни: URL библиотеки или папки SP → GUID родительской папки или списка в MP
ContentTypeMap	`[ [ "Проект", "540ff572-..." ], [ "Папка", "09ad2c16-..." ] ]`	Маппинг типов контента SP (название) → тип элемента MP (GUID). Не указанные: папка → «Папка», файл → «Файл проекта», элемент справочника → «Элемент»
FieldMap	`[ [ "VitroBaseStatus", "document_status", "sp_id_list" ] ]`	Маппинг столбцов SP → атрибутов MP (internal name). Третий параметр — только для лукапов (поле `sp_id` в справочнике MP, по умолчанию `sp_id`)
ListMap	`{ "http://sp2013/Lists/seStatusList": "9618f977-0447-4010-88f7-76d8edca255c" }`	Справочники для режима List: URL списка SP → GUID списка MP
ListMapCriterion	`[ "Title", "name", "sp_id" ]`	Критерий сопоставления в режиме List. При совпадении проставляется поле SP ID; иначе — ошибка или создание записи (см. `CreateListMapItem`)
CreateListMapItem	`false`	В режиме List: при `false` только проставление `sp_id` на существующих записях; при `true` — создание новых по `ContentTypeMap` и `FieldMap`

Принцип работы

Определяется список типов контента и полей (столбцов), которые необходимо перенести из SP в MP.
Создаются соответствующие типы элементов и атрибуты в Vitro MP.
Задаётся конфигурация утилиты: маппинги ТК, полей и LibraryMap.
Создаются справочники для лукапов в MP с полем sp_id (числовой ID элемента в SP). Заполняются утилитой (режим List), вручную или комбинированно. Несопоставленные значения выводятся в лог.
Утилита создаёт и заполняет таблицу Migration — по ней отслеживаются прогресс, объём и ошибки.
Запускается режим Folder. Контролируются таблица Migration и лог. Ошибки на верхнеуровневых папках критичны: неперенесённый проект повлечёт ошибки у всех дочерних элементов. Ошибки устраняют или вручную корректируют запись в Migration; при повторном запуске режим обработает их снова.
Запускается режим File. Утилита может работать в несколько потоков (ThreadNumber). Учитывать нагрузку на Vitro SP — оптимальное число потоков подбирается на площадке.
Запускается режим Reference (обязательный этап после файлов).
При необходимости запускаются Member, Sign, Issue (добавить в ModeList после Reference).
При ошибках — анализ лога и Migration, исправление и повторный запуск нужного режима.

Текущие ограничения

Нет штатной процедуры очистки смигрированных данных. Нельзя гарантированно перенести данные, удалить их в MP и повторить перенос «с нуля» — возможны ошибки дублирования.
Нельзя размножать значения из одного поля SP в FieldMap: левая часть маппинга (поле SP) должна быть уникальной.
При переносе в MP работают все вычисления, валидаторы и автоматизации целевых типов элементов. Для переноса «1 в 1» их нужно временно удалить из списка и восстановить из корзины, либо убедиться, что они не искажают импортируемые данные.
GUID целевых списков MP в SQL-процедурах (procMigration_Reference, Member, Sign, Issue) заданы в скриптах — при другой конфигурации стенда их нужно скорректировать в Scripts\.
Путь к конфигурации Vitro Server (C:\Program Files\Vitro Software\Vitro\Server) задан в коде утилиты; при нестандартной установке требуется изменение и пересборка.

Возможные ошибки

ItemExistException — при переносе MP сообщает, что файл или папка с таким именем уже существуют. Возможные причины: активные вычисления имён, неверный маппинг, повторный перенос без очистки.
ItemNotFoundException — не найден родительский или связанный элемент.
Server Response 500 — смотреть аудит запросов в Vitro MP: не создан родитель, неверный маппинг, тип элемента не привязан к библиотеке.
Ошибки в поле Migration.error — повторный запуск режима; при необходимости ручная правка строки в таблице Migration.
Сообщения о несопоставленных лукапах или пользователях в логе — заполнить справочники и учётные записи MP или использовать SkipFieldMapError / SkipUserMapError.
ListMapException — дубликаты sp_id в справочнике MP или не найден родитель при создании записи в режиме List.

Дополнительная информация

GUID элементов в Vitro SP и Vitro MP совпадают. Перенесённые элементы доступны по /item/{uniqueId}.
Корень переноса задаётся в LibraryMap (URL в SP и GUID родителя в MP), отдельный скрипт исключения корневой папки не используется.
Повторный запуск режимов Folder и File подхватывает новые папки, файлы и новые версии (по дате изменения в SP).
Кастомные конфигурации заказчиков: Conf\{Customer}\config.json и при необходимости Scripts\{Customer}\procMigration_*.sql.
Для файлов во внешнем хранилище (поле FileStorageUniqueId) путь к файлам читается из Options\App\Cfg.xml (Site.FileStorage.Path).

Page tree