Описание формата XLSX-файла¶
Общая информация¶
Файл Excel используется для экспорта записей в Excel и импорта записей из Excel в систему. Причем, для импорта можно либо скачать пустой шаблон, либо использовать результаты экспорта (доступного в пакетных операциях с записями).
Файл Excel может состоять из нескольких листов, каждый из которых содержит описание отдельного объекта. Тип объекта можно определить по первой букве в названии листа:
E – реестр/справочник (от entity). Является основным листом;
N – комплексный атрибут (от nested);
Количество листов комплексных атрибутов зависит от количества используемых в реестре вложенных объектов. Например, если у реестра есть два комплексных атрибута "с1" и "с2", которые используют один и тот же вложенный объект "nested1", то в xlsx-файле будут присутствовать два листа "N<nested1>1" и "N<nested1>2".
R – связь (от relation);
C – классификация (от classifier);
В названии листа указывается системное и отображаемое имя объекта (не более 31 символа). В названии листа комплексного атрибута указывается имя самого атрибута и имя вложенного объекта.
Примечание
В файле Excel все отметки о времени указываются в часовом поясе UTC+0, и могут отличаться от времени в интерфейсе пользователя. Например, в интерфейсе используется московский часовой пояс UTC+3, но при выгрузке записей в Excel время отображается в поясе UTC+0.
Совет
Рекомендуется изучать файл Excel на готовом примере. Например, выполнить пакетную операцию экспорта для любого реестра/справочника, либо, если данных нет, скачать шаблон для импорта
Особенности импорта¶
При импорте основной лист должен присутствовать в файле, даже если в нем нет записей.
При повторном импорте записей (редактировании существующих данных) при помощи ETALON_ID, вне зависимости от того, какая система-источник указана, записи будут загружаться от имени внутреннего (системного) источника. Для загрузки данных от имени других источников используйте EXTERNAL_ID.
Если импортируются только связи, то необходимо соблюдать условия для концов связей.
Левый конец связи:
ETALON_ID - запись уже должна быть в MDM. Указывается ETALON_ID существующей связи;
EXTERNAL_ID - запись, на которую указывает EXTERNAL_ID, должна импортироваться в этом же файле. Или уже быть в MDM и в этом случае иметь ту же систему-источник;
ID - запись, на которую указывает EXTERNAL_ID, должна импортироваться в этом же файле;
Правый конец связи:
ETALON_ID - запись уже должна быть в MDM. Или в случае связи Включение быть пустой;
EXTERNAL_ID - нужно выполнять одно из условий. Запись уже должна быть в MDM, имея ту же систему-источник. Или импортироваться в этом же файле в случае связей типа Ссылка и Многие-ко-многим, которые ссылаются на этот же реестр. Или в случае связи Включение EXTERNAL_ID может быть пустым и тогда будет сгенерирован автоматически.
Основной лист реестра/справочника¶
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
ID |
Виртуальный ключ для задания соответствия объектов из разных листов. Значение ID не сохраняется в системе |
Значения ID считываются со всех листов файла. При совпадении ID запись реестра /справочника с указанным ID включает в себя объекты, имеющие совпавший ID. |
Не выгружается при экспорте |
ETALON_ID |
Системный идентификатор эталонной записи |
Необязательное. Может быть пустым. Если ETALON_ID указан, то при импорте запись с совпадающим идентификатором будет перезаписана (изменятся пустые или отредактированные атрибуты). При первичной загрузке данных ETALON_ID должен быть не заполнен. В противном случае записи будут отклонены. При редактировании существующих записей через ETALON_ID данные всегда будут загружаться от имени системного источника данных |
Выгружается при экспорте |
EXTERNAL_ID |
Внешний ключ записи (идентификатор записи в системе-источнике) |
При импорте EXTERNAL_ID указывается в паре с системой-источником, которая была указана на 1 шаге импорта записей. Это необходимо для идентификации новой записи. |
Не выгружается при экспорте |
Если указан ETALON_ID, то только он будет использован: - Если запись с таким ETALON_ID уже существует, то используется системный источник данных для вставки записи; - Если записи с таким ETALON_ID не существует, то появится ошибка. Если указан EXTERNAL_ID (при отсутствии ETALON_ID), то запись с таким EXTERNAL_ID создастся или обновится (в выбранной системе-источнике). Если не указаны ни ETALON_ID, ни EXTERNAL_ID, то запись будет вставлена и сгенерируется EXTERNAL_ID. |
|||
IS_ACTIVE |
Индикатор активности, который определяет, является ли период актуальности записи помеченным на удаление |
Необязательное. Должно быть указано одно из состояний: ИСТИНА или ЛОЖЬ, где ЛОЖЬ – период помечен на удаление. Если IS_ACTIVE пустой, то поведение аналогично параметру в состоянии ИСТИНА |
Выгружается при экспорте |
Для иерархических справочников - индикатор определяет, является ли запись помеченной на удаление |
Необязательное. Должно быть указано одно из состояний: ИСТИНА или ЛОЖЬ, где ЛОЖЬ – запись помечена на удаление. Если IS_ACTIVE пустой, то поведение аналогично параметру в состоянии ИСТИНА |
Выгружается при экспорте |
|
EXTERNAL_KEYS |
Список пар внешних ключей записи и систем-источников. Каждая пара ключ/источник записана через разделитель |
При импорте не используется |
Выгружается при экспорте |
Только для реестра и простого справочника |
|||
FROM |
Дата/время начала периода актуальности записи |
Необязательное. Может быть пустым. Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss |
Выгружается при экспорте, если имеет значение, отличное от "-∞" |
TO |
Дата/время окончания периода актуальности записи |
Необязательное. Может быть пустым. Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss |
Выгружается при экспорте, если имеет значение, отличное от "+∞" |
Отсутствие значения в поле FROM трактуется как "-∞", TO – как "+∞" Например, если указать текущую дату в качестве значения TO, а поле FROM оставить пустым, то запись будет актуальна до сегодняшнего дня включительно |
|||
Только для иерархического справочника |
|||
PARENT_ID |
Идентификатор родительского узла |
Необязательное. Может быть пустым - в таком случае импортированная запись присоединяется к корневому узлу |
Выгружается при экспорте |
PARENT_CODE |
Значение главного кодового атрибута родительской записи |
Необязательное. Может быть пустым - в таком случае импортированная запись присоединяется к корневому узлу |
Выгружается при экспорте |
В последующих столбцах располагаются основные атрибуты реестра/cправочника. Идентификатор каждого атрибута имеет вид "Имя_реестра/справочника"."Имя_атрибута". Например, COUNTRY.NAME для справочника COUNTRY и атрибута NAME. Также указывается подсказка. Например, Список стран >> Наименование.
Лист комплексных атрибутов¶
Заголовок листа комплексного атрибута отображается как
complex_attr_name>nested_name >> Комплексный атрибут: Имя комплексного атрибута > Имя вложенного объекта, где ">" - разделитель, "complex_attr_name" и "nested_name" - системные имена комплексного атрибута и вложенного объекта соответственно.Системные имена в заголовке используются для правильной идентификации вложенного объекта и комплексного атрибута, которому он принадлежит. В импортируемом файле заголовки должны быть составлены также, в противном случае вложенный объект при импорте будет пропущен и не обновится (в записи будет старое значение комплексного атрибута) или не вставится (в записи будет пустым).
Файлы Excel, созданные в версии Юниверс MDM 6.8 и ниже, не поддерживаются. Чтобы их загрузить, необходимо исправить заголовок листа комплексных атрибутов в соответствии с новым форматом.
Обрабатываются вложенные объекты только первого уровня. Лист комплексных атрибутов может содержать описания нескольких вложенных объектов. Также один вложенный объект может использоваться несколькими комплексными атрибутами.
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
ID |
Виртуальный ключ для задания соответствия объектов из разных листов. Значение ID не сохраняется в системе |
Используется только для привязки к периодам актуальности записи (строки таблицы) с основного листа и последующего поиска. Если на основном листе присутствует запись с соответствующими колонками ID, FROM, TO, то комплексный атрибут будет добавлен к найденной строке и будет использован для обновления соответствующего периода актуальности записи. Если запись на основном листе не найдена, то комплексный атрибут игнорируется |
Не выгружается при экспорте |
ETALON_ID |
Системный идентификатор эталонной записи |
Используется при импорте совместно с FROM, TO для привязки к периодам актуальности записи (строке таблицы). Если ключ задан, то будет осуществлен поиск среди строк основного листа (который содержит вставки данных). Если на основном листе присутствует запись с соответствующими колонками ETALON_ID, FROM, TO и незаполненной колонкой ID, то комплексный атрибут будет добавлен к найденной строке. Если запись на основном листе не найдена, то комплексный атрибут игнорируется |
Выгружается при экспорте |
EXTERNAL_ID |
Внешний ключ записи (идентификатор записи в системе-источнике) |
Используется при импорте совместно с FROM, TO для привязки к периодам актуальности записи (строке таблицы). Если ключ задан, то будет осуществлен поиск среди строк основного листа (который содержит вставки данных). Если на основном листе присутствует запись с соответствующими колонками EXTERNAL_ID, FROM, TO и незаполненными колонками ID и ETALON_ID, то комплексный атрибут будет добавлен к найденной строке. Если запись на основном листе не найдена, то комплексный атрибут игнорируется |
Не выгружается при экспорте |
Если ETALON_ID и EXTERNAL_ID импортируемого атрибута не соответствуют ETALON_ID и EXTERNAL_ID существующего атрибута, то загрузка атрибута завершится ошибкой |
|||
FROM |
Дата/время начала периода актуальности (записи, к которой добавляется комплексный атрибут) |
Необязательное. Может быть пустым (трактуется как "-∞"). Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss. Комплексные атрибуты импортируются при совпадении ID, FROM и TO с аналогичными полями в записи реестра/справочника на основном листе |
Выгружается при экспорте, если имеет значение, отличное от "-∞" |
TO |
Дата/время окончания периода актуальности (записи, к которой добавляется комплексный атрибут) |
Необязательное. Может быть пустым (трактуется как "+∞"). Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss. Комплексные атрибуты импортируются при совпадении ID, FROM и TO с аналогичными полями в записи реестра/справочника на основном листе |
Выгружается при экспорте, если запись имеет значение, отличное от "+∞" |
IS_ACTIVE |
Для комплексных атрибутов отсутствует |
||
EXTERNAL_KEYS |
Список пар внешних ключей записи и систем-источников. Каждая пара ключ/источник записана через разделитель |
Заполняется так же, как для основного листа |
Заполняется так же, как для основного листа |
Лист связей¶
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
ID |
Виртуальный ключ для задания соответствия объектов из разных листов. Значение ID не сохраняется в системе |
Заполняется так же, как для комплексного атрибута |
Заполняется так же, как для комплексного атрибута |
ETALON_ID |
Системный идентификатор эталонной записи |
Заполняется так же, как для комплексного атрибута |
Заполняется так же, как для комплексного атрибута |
EXTERNAL_ID |
Внешний ключ записи (идентификатор записи в системе-источнике) |
Заполняется так же, как для комплексного атрибута |
Заполняется так же, как для комплексного атрибута |
Если ETALON_ID и EXTERNAL_ID импортируемой записи не соответствуют ETALON_ID и EXTERNAL_ID существующей записи, то загрузка записи завершится ошибкой. При этом, если указан только EXTERNAL_ID, то запись будет загружена как новая |
|||
FROM |
Дата/время начала периода актуальности связи (для основного листа) |
Необязательное. Может быть пустым. Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss |
Выгружается при экспорте, если имеет значение, отличное от "-∞" |
TO |
Дата/время окончания периода актуальности связи (для основного листа) |
Необязательное. Может быть пустым. Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss |
Выгружается при экспорте, если запись имеет значение, отличное от "+∞" |
Отсутствие значения в поле FROM трактуется как "-∞", TO – как "+∞" Например, если указать текущую дату в качестве значения TO, а поле FROM оставить пустым, то запись будет актуальна до сегодняшнего дня включительно |
|||
TO_ETALON_ID |
Эталонный ключ правого конца связи (ID записи, на которую указывает связь) |
При импорте используется для связывания записей |
Выгружается при экспорте |
IS_ACTIVE |
Для связей отсутствует |
||
TO_EXTERNAL_ID |
Внешний ключ записи правого конца связи |
При импорте используется для связывания записей |
Не выгружается при экспорте |
TO_DISPLAY_NAME |
Отображаемое имя записи, на которую указывает связь |
При импорте не используется |
Выгружается при экспорте |
Лист классификации¶
Классификация описывается построчно для каждого атрибута узла. Например, для описания узла с 3 атрибутами понадобится три строки. При этом столбцы EXTERNAL_ID, FROM, TO, CLASSIFIER_VERSION_ID, CLASSIFIER_IS_ACTIVE, CLASSIFIER_NODE_NAME будут одинаковы; отличаться будут только ATTRIBUTE_NAME и ATTRIBUTE_VALUE.
Если флаг Активная версия включен, то классификация выгружается только из активной версии классификатора.
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
ID |
Виртуальный ключ для задания соответствия объектов из разных листов. Значение ID не сохраняется в системе |
Заполняется так же, как для комплексного атрибута |
Не выгружается при экспорте |
ETALON_ID |
Системный идентификатор эталонной записи, к которой привязан узел классификатора |
Заполняется так же, как для комплексного атрибута |
Выгружается при экспорте |
EXTERNAL_ID |
Внешний ключ записи (идентификатор записи в системе-источнике), к которой привязан узел классификатора |
Заполняется так же, как для комплексного атрибута |
Выгружается при экспорте |
FROM |
Дата/время начала периода актуальности (записи, к которой добавляется узел классификатора) |
Необязательное. Может быть пустым (трактуется как "-∞"). Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss. Комплексные атрибуты импортируются при совпадении ID, FROM и TO с аналогичными полями в записи реестра/справочника на основном листе |
Не выгружается при экспорте |
TO |
Дата/время окончания периода актуальности (записи, к которой добавляется узел классификатора) |
Необязательное. Может быть пустым (трактуется как "+∞"). Дата указывается в формате DD.MM.YYYY, дата/время в формате DD.MM.YYYY hh:mm:ss. Комплексные атрибуты импортируются при совпадении ID, FROM и TO с аналогичными полями в записи реестра/справочника на основном листе |
Не выгружается при экспорте |
CLASSIFIER_VERSION_ID |
Логическое имя классификатора |
Обязательно заполняется |
Выгружается при экспорте |
CLASSIFIER_NODE_NAME |
Имя узла классификатора (логическое имя узла версии классификатора) |
Обязательно заполняется |
Выгружается при экспорте |
CLASSIFIER_IS_ACTIVE |
Определяет, активен ли узел классификатора (не путать с флагом Активная версия в мастере экспорта записей) |
Обязательно заполняется. При импорте со значением false узел, до этого существовавший в записи, будет помечен на удаление. (Для редактирования записей путем импорта). Если у узла несколько атрибутов, то есть несколько строк, для удаления узла при импорте файла достаточно проставить false только в одной из них. |
Выгружается при экспорте. При экспорте существующей записи с классификацией используйте значение true. При экспорте логически удаленной записи с классификацией используйте значение false. Узлы классификатора, удаленные из существующей записи при редактировании, не экспортируются. |
ATTRIBUTE_NAME |
Логическое имя атрибута узла классификатора |
Обязательно заполняется, если атрибут существует |
Выгружается при экспорте если существует |
ATTRIBUTE_VALUE |
Значение атрибута узла классификатора |
Необходимо заполнять как минимум атрибуты, имеющие свойство "Обязательный" |
Выгружается при экспорте если существует |
Примечания¶
Общая информация
Каждый лист имеет системные атрибуты (столбцы синим цветом) и основные атрибуты объекта.
Каждому атрибуту соответствует отдельный столбец.
Каждая новая строка соответствует отдельной записи с периодом актуальности (если запись содержит несколько периодов актуальности, то каждый период будет отдельной строкой).
ID, ETALON_ID и EXTERNAL_ID в листах атрибутов и связей служат для идентификации записи (периода актуальности), к которой они привязываются.
Идентификация происходит по содержимому основного листа. Если запись не найдена, то вставляемый объект (комплексный атрибут или связь) будет проигнорирован.
Поиск записей по системным атрибутам
При заполнении шаблона необходимо учитывать возможные случаи содержания трех главных системных атрибутов записи: ID, ETALON_ID и EXTERNAL_ID. Кроме того, все объекты (связи, комплексные атрибуты) для привязки учитывают периоды актуальности (значения полей FROM и TO).
Приоритет колонок при идентификации: ID, ETALON_ID, затем EXTERNAL_ID.
Если в основном листе не задан ни один из ключей, она будет вставлена как новая. Привязать объекты к такой записи невозможно.
Если в основном листе ID Задан, ETALON_ID Пустой, EXTERNAL_ID Пустой: запись будет вставлена как новая. Только этот ключ будет использоваться для поиска между листами.
Если в основном листе ID Пустой, ETALON_ID Задан, EXTERNAL_ID Пустой: для поиска будет использован ETALON_ID. Только этот ключ будет использоваться для поиска между листами.
Если в основном листе ID Пустой, ETALON_ID Пустой, EXTERNAL_ID Задан: для поиска будет использован EXTERNAL_ID. Только этот ключ будет использоваться для поиска между листами.
Если в основном листе ID Задан, ETALON_ID Задан, EXTERNAL_ID Задан: для поиска будет использован ID. Только этот ключ будет использоваться для поиска между листами.
Если в основном листе ID Задан, ETALON_ID Задан, EXTERNAL_ID Пустой: для поиска будет использован ID. Только этот ключ будет использоваться для поиска между листами.
Если в основном листе ID Задан, ETALON_ID Пустой, EXTERNAL_ID Задан: для поиска будет использован ID. Только этот ключ будет использоваться для поиска между листами.
Рекомендуется заполнять один тип ключа для всех объектов соответствующей записи (для самого реестра/справочника, для комплексных атрибутов, связей).
Импорт записи с несколькими периодами актуальности
Несколько периодов одной записи загружаются только с помощью EXTERNAL_ID.
В файле .xlsx такая запись с несколькими периодами актуальности занимает несколько строк, где каждая из строк должна содержать собственные периоды актуальности (столбцы FROM и TO).
В случае обновления существующей записи ETALON_ID у всех строк одной записи должен быть одинаковым.
Период, который полностью перекрывается другим (входит в него), будет объединен с более крупным периодом.
Особенности импорта справочников (с помощью PARENT_ID и PARENT_CODE)
Вставка записей и обновление иерархии записей выполняются в рамках одной транзакции. Если выдается ошибка, например, из-за неразрешенного родительского кода, вся пакетная операция откатывается, изменения индекса очищаются. Такое поведение отличается от традиционной пакетной обработки сбоев, поскольку отдельный запрос не изолирован от других: успех обновления дочерних записей зависит от результата обновления родительского запроса.
В одном импорте xlsx поддерживается разрешение иерархии как на основе кода, так и на основе идентификатора. Если заполнено только одно из этих полей, оно используется. Если оба заполнены и указывают на разные записи, выдается ошибка. Если нет, то запись прикрепляется к корневому каталогу.
Значение первичного кода не идентифицирует запись, т.е. если etalon_id пуст, оно обрабатывается как новая запись и вызовет ошибку, если запись с тем же кодом существует.
Особенности экспорта связи "Включение"
При экспорте связи "Включение" с комплексным атрибутом появляется дополнительный лист.
На листе комплексного атрибута связи "Включение":
Можно указать ID или EXTERNAL_ID, которые привязываются к TO_EXTERNAL_ID связи;
Можно указать ETALON_ID, который привязывается к TO_ETALON_ID связи.