Импорт данных
Механизм импорта позволяет собирать данные из различных источников данных, а затем сопоставлять эти данные с соответствующими таблицами.
Механизм импорта SimpleOne поддерживает:
- различные типы источников данных
- различные форматы файлов (если в качестве типа источника выбран Файл)
Вы можете выбрать источник данных, поместить данные из него во временную таблицу (набор для импорта), а затем сопоставить данные из источника с целевой таблицей при помощи соотношения таблиц и соотношения полей.
Требуемая роль: admin, import_admin.
На схеме ниже представлены основные этапы процесса импорта.
Ключевые понятия
| Понятие | Описание |
|---|---|
| Источник импорта | Запись, указывающая, какие данные набора для импорта должны быть импортированы. |
| Набор для импорта | Запись, содержащая ссылки на необработанные данные, загруженные в промежуточную таблицу. Запись также возвращает информацию о состоянии попытки этого импорта. |
| Таблица импорта | Автоматически сгенерированная таблица, используемая в качестве временного хранилища для импортированных записей перед преобразованием. Структура таблицы формируется автоматически в зависимости от импортируемых данных. |
| Преобразование | Процесс преобразования данных в соответствии с соотношением таблиц и скриптами преобразований, определяющими исходную таблицу (набор для импорта) и целевую таблицу. |
| Схема трансформации | Запись, определяющая соответствие полей исходной и целевой таблиц в виде набора соотношений полей. |
| Скрипт преобразований | Скрипт, который позволяет настраивать операции импорта с использованием нативного JavaScript, расширенного серверным API SimpleOne. |
| Соотношение полей | Запись, определяющая связь между полем в исходной таблице и полем в целевой таблице. |
| Объединение данных | Эта опция позволяет обновлять существующее записи таблицы в процессе преобразования. Подробнее читайте далее в разделе: Объединение данных (coalesce). |
Источники импорта
Создание источника импорта необходимо для загрузки необработанных данных в систему для дальнейшей обработки и преобразования. Вы можете настроить источник импорта с различными типами источников данных и форматами файлов.
- Перейдите в Импорт → Источники импорта.
- Нажмите Создать и заполните поля.
- Если вы выбрали тип Файл, нажмите на иконку скрепки и прикрепите нужный файл. Вы можете прикрепить файлы в форматах JSON, XML или Excel.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Источники для импорта
| Поле | Обязательно | Описание |
|---|---|---|
| Наименование | Да | Укажите название источника импорта. |
| Наименование таблицы импорта | Да | Укажите название временной таблицы импорта. |
| Тип | Нет | Выберите тип источника импорта. Доступные опции для выбора:
|
| Способ получения файла | Нет | Выберите метод добавления файла в источник импорта. Доступные варианты:
Поле появляется, когда выбран тип Файл. |
| Формат | Да | Выберите формат файла и прикрепите его к форме. Доступные варианты:
Поле появляется, если выбран тип Файл или Текст. |
| Текст импорта | Нет | Введите текст в выбранном Формате, который вам нужно импортировать. Поле появляется, когда выбран тип Текст. |
| Настройка LDAP | Нет | Нажмите на иконку лупы , чтобы выбрать протокол, который вам необходим. Поле появляется, когда выбран тип LDAP. Читайте статью Источник данных LDAP, чтобы узнать больше. |
После сохранения, следующие действия пользовательского интерфейса появляются на форме источника импорта. Они отвечают за дальнейшую обработку импорта.
| Действие | Описание |
|---|---|
| Пробная загрузка (20 записей) | Используйте это действие для создания пробного набора для импорта из 20 записей, предназначенных для анализа структуры данных импорта. Не используйте тестовый набор для дальнейшего преобразования. |
| Загрузить все | Используйте это действие для создания новой записи набора для импорта, содержащего все данные из источника импорта. Используйте этот набор для дальнейшего преобразования. |
После загрузки данных в источник импорта, сохранения записи и вызова одного из действий загрузки данных, в связанном списке Наборы для импорта появляется новая запись.
Использование формата JSON
В качестве источника импорта можно использовать файлы, содержащие данные в формате JSON. В этом случае убедитесь, что файлы соответствуют следующим критериям:
- Файлы JSON должны быть актуальными. Используйте документ RFC 8259 в качестве руководства.
- Тип данных для использования в структуре JSON один из следующих: объект JSON, массив объектов, оБбъект с массивом объектов. Использование dot-walking не поддерживается.
Объект JSON
{
"top500": 1,
"name": "More",
"sector": "Oil and gas"
}
Результат: один элемент. В таблице есть поля top500, name, sector и одна запись.
Массив объектов
[
{
"top500": 1,
"name": "More",
"sector": "Oil and gas"
},
{
"top500": 2,
"name": "Nevermore",
"sector": "Oil and gas"
}
]
Результат: создан набор для импорта со связанной таблицей. Таблица имеет поля top500, name, sector и содержит две записи.
Объект с массивом объектов
// Path for Each Row == exportField
{
"exportField":[
{
"top500":1,
"name":"More",
"sector":"Oil and gas"
},
{
"top500":2,
"name":"Nevermore",
"sector":"Oil and gas"
},
{
"top500": 4,
"name": "Givememore",
"sector": "Oil and gas",
"more_info": "https://instance.example.com/company/34"
}
]
}
Результат: создан набор для импорта со связанной таблицей. Таблица имеет поля top500, name, sector и содержит три записи.
Преобразование имени таблицы импорта и колонок
Во время конвертации данных для импорта системные названия колонок и системные названия таблиц, которые отображаются в поле Наименование таблицы импорта в таблице Источники для импорта, транслитерируются и преобразуются по следующим правилам:
- Каждый символ из списка символов кириллицы заменяется на символ, соответствующий порядковому номеру в списке символов латиницы:
Таблица соотнесения
| Кириллица | Латиница | ||
|---|---|---|---|
| а | А | a | A |
| б | Б | b | B |
| в | В | v | V |
| г | Г | g | G |
| д | Д | d | D |
| е | Е | e | E |
| ё | Ё | io | Io |
| ж | Ж | zh | Zh |
| з | З | z | Z |
| и | И | i | I |
| й | Й | j | J |
| к | К | k | K |
| л | Л | l | L |
| м | М | m | M |
| н | Н | n | N |
| о | О | o | O |
| п | П | p | P |
| р | Р | r | R |
| с | С | s | S |
| т | Т | t | T |
| у | У | u | U |
| ф | Ф | f | F |
| х | Х | h | h |
| ц | Ц | ts | Ts |
| ч | Ч | ch | Ch |
| ш | Ш | sh | Sh |
| щ | Щ | shch | Shch |
| ъ | Ъ | \ | \ |
| ы | Ы | y | Y |
| ь | Ь | \ | \ |
| э | Э | e | e |
| ю | Ю | yu | Yu |
| я | Я | ya | Ya |
- Затем все символы, не удовлетворяющие регулярному выражению
/[^A-Za-z0-9_]+/u, заменяются на нижнее подчеркивание _ . То есть все символы, кроме больших и маленьких букв, цифр и нижнего подчеркивания, заменяются на _. - Текущее имя колонки разбивается на части по символу _, а затем они склеиваются символом _, например, для
_DOC_____1в итоге получимdoc_1. При этом повторяющиеся символы нижнего подчеркивания сливаются в один. - Текущее имя колонки приводится к нижнему регистру.
Если полученное во время конвертации имя колонки пустое, то устанавливается имя imp_invalid_column + номер колонки. Номер колонки определяется ее порядком в таблице, нумерация начинается с 0, например imp_invalid_column0.
- К имени добавляется префикс imp, например,
imp_spisok_klientov.
Набор для импорта
Набор для импорта создается автоматически на основе необработанных данных, загруженных в источник импорта. Набор для импорта – временное хранилище записей, импортируемых из источника данных.
Поля формы Набор для импорта
| Поле | Обязательно | Описание |
|---|---|---|
| Номер | Нет | Уникальный номер набора для импорта. Поле заполняется автоматически. |
| Источник импорта | Да | Поле содержит соответствующее наименование источника импорта и заполняется автоматически. |
| Таблица набора импорта | Да | Поле содержит наименование временной таблицы импорта и заполняется автоматически. Системные имена полей таблицы начинаются с префикса imp. |
| Статус | Нет | Состояние загрузки набора для импорта. Поле заполняется автоматически и доступно только для чтения. Возможные значения:
|
| Краткое описание | Нет | Поле описывает структуру созданной таблицы и заполняется данными автоматически. Пример значения поля:
|
Записи Набора для импорта находятся в отношениях родитель-потомок с записями таблицы Элементы наборов.
Схема трансформации
Схема трансформации представляет собой набор соотношений полей. Укажите этом наборе соотношения полей временной таблицы импорта и полями целевой таблицы.
Для каждой операции импорта требуется по крайней мере одна запись схемы трансформации, которая показывает связь временной таблицы импорта и целевой таблицы.
После создания первого набора для импорта, создайте запись схемы трансформации. Для этого выполните следующие шаги:
- Нажмите на Открыть схему трансформации на форме записи источника импорта, который вы настраиваете.
- В появившемся всплывающем сообщении пройдите по ссылке Создать схему трансформации.
- Заполните поля в появившейся форме.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Схему трансформации также можно создать с нуля. Для этого выполните следующие шаги:
- Перейдите в Импорт → Схемы трансформаций, чтобы открыть список соотношений таблиц.
- Нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Схемы трансформаций
| Поле | Обязательно | Описание |
|---|---|---|
| Наименование | Да | Укажите отображаемое название схемы трансформации. |
| Активна | Нет | Установите флажок, чтобы сделать схему трансформации доступной для использования. |
| Исходная таблица | Да | Выберите таблицу, содержащую данные набора для импорта. |
| Целевая таблица | Да | Выберите таблицу, в которую необходимо поместить импортированные данные. |
| Форсированный импорт | Нет | Установите флажок, чтобы игнорировать бизнес-правила, правила уведомлений и другие механизмы на стороне сервера, которые могут запускаться действиями создания или обновления записей. В частности, рабочие процессы, связанные с этой записью, не запустятся, история изменений поля не будет записана и не будет отображаться в Ленте активности. Вы можете найти порядок выполнения механизмов и бизнес-правил в статье Порядок выполнения. |
| Игнорировать обязательные поля | Нет | Установите флажок, чтобы игнорировать обязательные поля в целевой таблице. |
| Использовать скрипт | Нет | Установите флажок, чтобы отобразить поле Скрипт, в котором можно указать скрипт преобразования. Если вы снимете флажок после создания скрипта, скрипт не будет применяться в преобразовании. |
| Скрипт | Нет | Введите скрипт соотношения таблиц, который необходимо использовать для преобразования значений полей из исходной таблицы в целевую. Узнайте больше о настройках импорта в разделе API для разработчиков. |
Рекомендации к скрипту
Используйте функцию runTransformRow() со следующими параметрами:
- source – запись Элемента набора, которая будет трансформирована. Вызовите определенное поле из записи, как обычный объект SimpleRecord. Например, source.imp_name.
- map – запись Схемы трансформации, которая используется для процесса преобразования.
- log – объект, который содержит методы info, warn, и error. Методы предназначены для регистрации процесса трансформации.
- target – запись в целевой таблице, которая будет создана или обновлена при трансформации исходной записи. Вызовите определенное поле из записи, как обычный объект SimpleRecord. Например, target.name = source.imp_name. При указании объекта параметра target учитывайте тип поля в целевой таблице.
- isUpdate – Boolean параметр, который проверяет, обновилась ли целевая запись.
Этот скрипт можно использовать для определения связей полей перед трансформацией. Вы также можете настроить соотношения, создав связанные записи на вкладке Соотношения полей схемы трансформации.
Если вы настраиваете соотношения полей с помощью скрипта, создайте еще одну запись соотношения полей, чтобы определить настройку объединения данных (флажок Объединить данные на форме соотношения полей) для этого сеанса трансформации.
Читайте статью API для разработчиков, чтобы узнать больше о расширенном импорте.
Скрипт преобразования
Скрипт преобразования позволяет настроить импорт данных с помощью JS-скриптов и классов серверного API после создания схемы трансформации. Для этого выполните следующие шаги:
- Перейдите на нужную форму записи Схемы трансформации.
- В области Связанные списки выберите вкладку Скрипты преобразований.
- Нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
Поля формы Скрипт преобразования
| Поле | Обязательно | Описание |
|---|---|---|
| Схема трансформации | Да | Укажите схему трансформации, для которой будет выполняться скрипт. |
| Активен | Нет | Установите флажок, чтобы активировать скрипт. |
| Когда | Да | Выберите, когда выполнять скрипт. Доступные опции:
|
| Порядок | Нет | Укажите порядок, в котором будет выполняться скрипт преобразования. Заполните это поле целым числом. |
| Скрипт | Нет | Введите скрипт, используя серверный API SimpleOne. |
Поле Порядок временно работает некорректно. Наша команда работает над улучшением его логики, чтобы сделать его работу полноценной. Об изменениях мы сообщим вам в одном из следующих релизов.
Рекомендации к скрипту
Используйте функцию runTransformScript() со следующими параметрами:
- source – запись Элемента набора, которая будет трансформирована. Вызовите определенное поле из записи, как обычный объект SimpleRecord. Например, source.imp_name.
- map – запись Схемы трансформации, которая используется для процесса преобразования.
- log – объект, который содержит методы info, warn и error. Методы предназначены для регистрации процесса трансформации.
- target – запись в целевой таблице, которая будет создана или обновлена при трансформации исходной записи. Вызовите определенное поле из записи, как обычный объект SimpleRecord. Например, target.name = source.imp_name.
При указании объекта параметра target учитывайте тип поля в целевой таблице. Пример заполнения полей скриптом В начале трансформации:
Скрипт заполнения полей в начале трансформации
(function runTransformScript(source, map, log, target /*undefined onStart*/) {
target.email = source.imp_mail; // string
target.username = source.imp_samaccountname; // string
const parsedPhoneDigits = source.imp_mobile.match(/\d/g);
target.phone = parsedPhoneDigits ? parsedPhoneDigits.join('') : null; // phone
const company = new SimpleRecord('org_company');
company.addQuery('name', 'like', source.imp_company);
company.selectAttributes('sys_id');
company.setLimit(1);
company.query();
target.company = company.next() ? company.sys_id : null; // reference
})(source, map, log, target);
- ignore – Boolean параметр, который позволяет пропустить запись Элемента набора для импорта.
- status_message – сообщение, которое описывает процесс трансформации записи.
Скрипт пропуска импорта в начале трансформации
(function runTransformScript(source, map, log, target /*undefined onStart*/) {
const duplicate = new SimpleRecord('task');
duplicate.addEncodedQuery(`number=${source.imp_number}^sys_id!=${target.sys_id}`);
duplicate.selectAttributes('sys_id');
duplicate.setLimit(1);
duplicate.query();
if (duplicate.next()) {
ignore = true; // пропуск строки набора для импорта
status_message = 'The "Number" [number] field should be an unique.'; // записать сообщение в строку набора для импорта -> Описание
}
})(source, map, log, target);
Соотношение полей
Соотношения полей используются для определения соответствия между полями временной таблицы импорта и полями целевой таблицы. Для этого необходимо определить значения из исходной таблицы, которые будут добавлены в целевую таблицу.
В процессе импорта может потребоваться обновить существующие записи в целевой таблице. Чтобы настроить ключевые отношения между исходной и целевой таблицами, создайте хотя бы одну запись соотношения полей с активным атрибутом Объединить данные. Этот атрибут должен быть активен для соотношения полей, которое содержит отношения между колонками с уникальными значениями. Это может быть адрес электронной почты для пользователя или серийный номер для КЕ.
Чтобы получить более строгое соотношение полей, активируйте опцию Объединить данные для нескольких записей Соотношение полей.
Чтобы создать соотношение полей, выполните следующие действия:
- Перейдите в Импорт → Схемы трансформаций.
- Откройте запись схемы трансформации, которую вам нужно настроить.
- Нажмите Создать соотношения полей. Появится виджет Соотношения полей. Смотрите скриншот в таблице ниже.
- Настройте соотношения полей в текущем процессе преобразования.
- Нажмите Создать, чтобы сохранить изменения, или Отменить, чтобы отменить изменения.
Еще один способ создания соотношения полей:
- Перейдите в Импорт → Схемы трансформаций.
- Откройте запись схемы трансформации, которую вам нужно настроить.
- В связаном списке Соотношения полей нажмите Создать и заполните поля.
- Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.
- Повторите шаги 1–4 для каждой пары полей, которые необходимо соотнести.
Поля формы Соотношения полей
| Поле | Обязательно | Описание |
|---|---|---|
| Схема трансформации | Да | Укажите схему трансформации, которая использует эту запись соотношения полей. Поле заполняется автоматически, если запись создается через виджет или из связанного списка. |
| Исходное поле | Да | Выберите поле исходной таблицы, которое необходимо преобразовать. |
| Целевое поле | Да | Выберите поле целевой таблицы, в котором должны храниться значения из исходной таблицы. |
| Объединить данные | Нет | Если этоn поле активно в процессе преобразования, механизм проверяет, равны ли значения в Целевой таблице значениям в Исходной таблице импорта. Если значения равны, запись в Целевой таблице будет обновлена; в противном случае, будет создана новая запись. Эту опцию можно настроить в виджете. После нажатия на Создать соотношения полей на форме записи соотношения таблицы появится виджет, содержащий кнопки Add coalesce и Drop coalesce.
|
| Использовать исходный скрипт | Нет | Установите флажок, чтобы определить скрипт преобразования в поле Скрипт. |
| Скрипт | Да | Создайте скрипт, чтобы определить функцию, которая принимает объект записи таблицы Набор для импорта в качестве аргумента и возвращает значение для помещения в Целевое поле. Поле появляется, когда установлен флажок Использовать исходный скрипт. Не снимайте флажок Использовать исходный скрипт после создания скрипта; иначе он не применится. Читайте статью API для разработчиков, чтобы узнать больше о расширенном импорте. |
Рекомендации к скрипту
Используйте функцию transformEntry() со следующими параметрами:
- source – запись Элемента набора, которая будет трансформирована. Вызовите определенное поле из записи, как обычный объект SimpleRecord. Например, source.imp_name.
- target – запись в целевой таблице, которая будет создана или обновлена при трансформации исходной записи. Вызовите определенное поле из записи, как обычный объект SimpleRecord. Например, target.name = source.imp_name. При указании объекта параметра target учитывайте тип поля в целевой таблице.
Запуск преобразования
- Перейдите в Импорт → Наборы для импорта.
- Откройте набор для импорта, который вам нужно преобразовать. Убедитесь, что статус набора Загружен.
- Нажмите Трансформировать.
В результате появится всплывающее сообщение Импорт завершен. Импортированные данные будут перенесены в целевую таблицу.
Последовательность трансформации
На схеме ниже показана последовательность событий, вызванных преобразованием:
- Последовательность начинается со скрипта преобразования При старте импорта. Он выполняется в начале преобразования до того, как будет прочитана какая-либо запись Элемента набора.
- (опционально) Скрипт, указанный в записи Соотношения полей, принимает объект записи таблицы Элемент набора в качестве аргумента и возвращает значение для помещения в целевое поле.
- (опционально) Скрипт, указанный в записи Схемы трансформации, преобразует значения полей из исходной строки в целевую строку.
- Скрипт преобразования В начале трансформации выполняется до преобразования исходной строки в целевую.
- Между выполнением скриптов В начале трансформации и По окончании трансформации создается или обновляется целевая запись.
- Скрипт преобразования По окончании трансформации запускается, когда исходная строка преобразуется в целевую.
- Скрипт преобразования При завершении импорта выполняется, когда преобразуются все исходные строки.
Скрипты, указанные в записях Соотношения полей и Схемы трансформации, а также скрипты преобразований типа В начале трансформации и По окончании трансформации повторяются для каждой записи до тех пор, пока не будет преобразованы все записи из набора.