Описание формата 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 |
Значение атрибута узла классификатора |
Необходимо заполнять как минимум атрибуты, имеющие свойство "Обязательный" |
Выгружается при экспорте если существует |
Лист единиц измерения¶
Столбец MU.name - содержит системное имя единицы измерения.
Столбец MU.display.name - содержит отображаемое имя единицы измерения.
Примечания¶
Общая информация
Каждый лист имеет системные атрибуты (столбцы синим цветом) и основные атрибуты объекта.
Каждому атрибуту соответствует отдельный столбец.
Каждая новая строка соответствует отдельной записи с периодом актуальности (если запись содержит несколько периодов актуальности, то каждый период будет отдельной строкой).
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 связи.