Описание формата XLSX-файла¶
Файл Excel используется для экспорта записей в Excel и импорта записей из Excel в систему. Причем, для импорта можно либо скачать пустой шаблон, либо использовать результаты экспорта (доступного в пакетных операциях с записями).
Файл Excel может состоять из нескольких листов, каждый из которых содержит описание отдельного объекта. Тип объекта можно определить по первой букве в названии листа:
E – реестр/справочник (от entity). Является основным листом;
N – комплексный атрибут (от nested);
R – связь (от relation);
Также в названии листа указывается логическое имя объекта (но не более 31 символа).
При повторном импорте записей (редактировании существующих данных) при помощи ETALON_ID, вне зависимости от того, какая система-источник указана, записи будут загружаться от имени внутреннего (системного) источника. Для загрузки данных от имени других источников используйте EXTERNAL_ID.
Tip
Рекомендуется изучать файл Excel на готовом примере. Например, выполнить пакетную операцию экспорта для любого реестра/справочника, либо, если данных нет, скачать шаблон для импорта
Основной лист реестра/справочника¶
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
ID |
Виртуальный ключ для задания соответствия объектов из разных листов. Значение ID не сохраняется в системе |
Значения ID считываются со всех листов файла. При совпадении ID запись реестра /справочника с указанным ID включает в себя объекты, имеющие совпавший ID. |
Не выгружается при экспорте |
ETALON_ID |
Системный идентификатор эталонной записи |
Необязательное. Может быть пустым. Если ETALON_ID указан, то при импорте запись с совпадающим идентификатором будет перезаписана (изменятся пустые или отредактированные атрибуты). При импорте ETALON_ID указывается в паре с системой-источником, которая была указана на 1 шаге импорта записей. Это необходимо для идентификации записи при отсутствии значения в столбце EXTERNAL_ID. При первичной загрузке данных ETALON_ID должен быть не заполнен. В противном случае записи будут отклонены. При редактировании существующих записей через ETALON_ID данные всегда будут загружаться от имени системного источника данных |
Выгружается при экспорте |
EXTERNAL_ID |
Внешний ключ записи (идентификатор записи в системе-источнике) |
Может быть пустым для существующих записей. При импорте EXTERNAL_ID указывается в паре с системой-источником, которая была указана на 1 шаге импорта записей. Это необходимо для идентификации новой записи. Указывается обязательно для импорта записей с несколькими периодами |
Не выгружается при экспорте |
Если ETALON_ID и EXTERNAL_ID импортируемой записи не соответствуют ETALON_ID и EXTERNAL_ID существующей записи, то загрузка записи завершится ошибкой. При этом, если указан только EXTERNAL_ID, то запись будет загружена как новая |
|||
IS_ACTIVE |
Индикатор активности, который определяет, является ли период актуальности записи помеченным на удаление |
Необязательное. Должно быть указано одно из состояний: ИСТИНА или ЛОЖЬ Где ЛОЖЬ – период помечен на удаление. Если IS_ACTIVE пустой, то поведение аналогично параметру в состоянии ИСТИНА |
Выгружается при экспорте |
Для иерархических справочников - индикатор определяет, является ли запись помеченной на удаление |
Необязательное. Должно быть указано одно из состояний: ИСТИНА или ЛОЖЬ Где ЛОЖЬ – запись помечена на удаление. Если IS_ACTIVE пустой, то поведение аналогично параметру в состоянии ИСТИНА |
Выгружается при экспорте |
|
EXTERNAL_KEYS |
Список пар внешних ключей записи и систем-источников. Каждая пара ключ/источник записана через разделитель |
При импорте не используется |
Выгружается при экспорте |
Только для реестра и простого справочника |
|||
FROM |
Дата/время начала периода актуальности записи |
Необязательное. Может быть пустым. Дата указывается в формате дд.мм.гггг, дата/время в формате дд.мм.гггг чч:мм:сс |
Выгружается при экспорте, если имеет значение, отличное от «-∞» |
TO |
Дата/время окончания периода актуальности записи |
Необязательное. Может быть пустым. Дата указывается в формате дд.мм.гггг, дата/время в формате дд.мм.гггг чч:мм:сс |
Выгружается при экспорте, если имеет значение, отличное от «+∞» |
Отсутствие значения в поле FROM трактуется как «-∞», TO – как «+∞» Например, если указать текущую дату в качестве значения TO, а поле FROM оставить пустым, то запись будет актуальна до сегодняшнего дня включительно |
|||
Только для иерархического справочника |
|||
PARENT_ID |
Идентификатор родительского узла |
Необязательное. Может быть пустым - в таком случае импортированная запись становится корневым узлом |
Выгружается при экспорте |
В последующих столбцах располагаются основные атрибуты реестра/cправочника. Идентификатор каждого атрибута имеет вид “Имя_реестра/справочника”.”Имя_атрибута”. Например, COUNTRY.NAME для справочника COUNTRY и атрибута NAME. Также указывается подсказка. Например, Список стран >> Наименование.
Лист комплексных атрибутов¶
Обрабатываются только комплексные атрибуты первого уровня
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
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 |
Дата/время начала периода актуальности (записи, к которой добавляется комплексный атрибут) |
Необязательное. Может быть пустым (трактуется как «-∞»). Дата указывается в формате дд.мм.гггг, дата/время в формате дд.мм.гггг чч:мм:сс. Комплексные атрибуты импортируются при совпадении ID, FROM и TO с аналогичными полями в записи реестра/справочника на основном листе |
Выгружается при экспорте, если имеет значение, отличное от «-∞» |
TO |
Дата/время окончания периода актуальности (записи, к которой добавляется комплексный атрибут) |
Необязательное. Может быть пустым (трактуется как «+∞»). Дата указывается в формате дд.мм.гггг, дата/время в формате дд.мм.гггг чч:мм:сс. Комплексные атрибуты импортируются при совпадении ID, FROM и TO с аналогичными полями в записи реестра/справочника на основном листе |
Выгружается при экспорте, если запись имеет значение, отличное от «+∞» |
IS_ACTIVE |
Для комплексных атрибутов отсутствует |
||
EXTERNAL_KEYS |
Список пар внешних ключей записи и систем-источников. Каждая пара ключ/источник записана через разделитель |
Заполняется так же, как для основного листа |
Заполняется так же, как для основного листа |
Лист связей¶
Столбец |
Описание |
При импорте |
При экспорте |
|---|---|---|---|
ID |
Виртуальный ключ для задания соответствия объектов из разных листов. Значение ID не сохраняется в системе |
Заполняется так же, как для комплексного атрибута |
Заполняется так же, как для комплексного атрибута |
ETALON_ID |
Системный идентификатор эталонной записи |
Заполняется так же, как для комплексного атрибута |
Заполняется так же, как для комплексного атрибута |
EXTERNAL_ID |
Внешний ключ записи (идентификатор записи в системе-источнике) |
Заполняется так же, как для комплексного атрибута |
Заполняется так же, как для комплексного атрибута |
Если ETALON_ID и EXTERNAL_ID импортируемой записи не соответствуют ETALON_ID и EXTERNAL_ID существующей записи, то загрузка записи завершится ошибкой. При этом, если указан только EXTERNAL_ID, то запись будет загружена как новая |
|||
FROM |
Дата/время начала периода актуальности связи (для основного листа) |
Необязательное. Может быть пустым. Дата указывается в формате дд.мм.гггг, дата/время в формате дд.мм.гггг чч:мм:сс |
Выгружается при экспорте, если имеет значение, отличное от «-∞» |
TO |
Дата/время окончания периода актуальности связи (для основного листа) |
Необязательное. Может быть пустым. Дата указывается в формате дд.мм.гггг, дата/время в формате дд.мм.гггг чч:мм:сс |
Выгружается при экспорте, если запись имеет значение, отличное от «+∞» |
Отсутствие значения в поле FROM трактуется как «-∞», TO – как «+∞» Например, если указать текущую дату в качестве значения TO, а поле FROM оставить пустым, то запись будет актуальна до сегодняшнего дня включительно |
|||
TO_ETALON_ID |
Эталонный ключ правого конца связи (ID записи, на которую указывает связь) |
При импорте используется для связывания записей |
Выгружается при экспорте |
IS_ACTIVE |
Для связей отсутствует |
||
TO_EXTERNAL_ID |
Внешний ключ записи правого конца связи |
При импорте используется для связывания записей |
Не выгружается при экспорте |
TO_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 у всех строк одной записи должен быть одинаковым.
Период, который полностью перекрывается другим (входит в него), будет объединен с более крупным периодом.