Импорт данных¶
Функционал импорта данных позволяет загружать в "Первую Форму" данные, выгруженные из внешних систем в файлы форматов CSV, XLS или непосредственно из таблиц SQL. Это могут быть, например, справочники контрагентов и контактных лиц, списки подразделений и пользователей, различные классификаторы, используемые в организации, и т.п. Также может быть настроен импорт данных из другого приложения "Первая Форма".
В "Первую Форму" могут загружаться данные о задачах, значениях ДП, а также учетные записи пользователей или орг. единицы.
Импорт данных может запускаться вручную или автоматически.
Автоматический запуск¶
Автоматический запуск импорта в "Первой Форме" настраивается смарт-автоматизацией — смарт-действием Выполнить импорт данных. Обычно такая автоматизация выполняется с заданной периодичностью — с помощью глобальных расписаний или расписаний в категориях.
Для запуска импорта из внешней системы можно использовать HTTP запрос.
Вызвать импорт можно через POST запрос вида:
\~/app/v1.0/api/DataSync/Import/NNNN?UserID=NN
где \~ — адрес приложения "Первая Форма", NNNN — алиас, указанный в настройках импорта, а NN — ID пользователя от имени которого запускается импорт (обычно это служебный пользователь Systemrobot с ID=3).
Ручной запуск¶
Для ручного импорта из интерфейса администратора нажмите кнопку Начать импорт.
Откроется окно, в котором необходимо выбрать файл с данными для импорта, при необходимости указать пользователя, от имени которого будут добавляться и изменяться данные, а также выбрать настройку импорта, а затем нажать на кнопку Ок.
По завершению импорта появится уведомление.
Для ручного запуска импорта из интерфейса пользователя обычно в категориях настраивают дополнительные кнопки, для которых также используется смарт-автоматизация со смарт-действием Выполнить импорт данных.
Для автоматизации импорта данных в "Первую Форму" можно использовать готовые настройки. С их помощью можно импортировать задачи, учетные записи пользователей, элементы орг. структуры.
Для импорта данных из нового источника сначала необходимо создать соответствующую настройку по кнопке Создать, а затем импортировать данные с использованием этой настройки по кнопке Начать импорт.
Остановка зависшего импорта¶
Зависший импорт можно остановить или перезапуском пула, или через БД следующим образом:
1. Найдите зависший процесс:
select * from [dbo].[DataImportFinishLogs]
where FinishTime is null
order by id desc
2. В журнале DataImportFinishLogs заполните колонку FinishDate текущей датой, что остановит все зависшие импорты.
Если вы хотите остановить все зависшие импорты:
update [dbo].[DataImportFinishLogs] set FinishTime = GETDATE() where FinishTime is null
Если вы хотите остановить конкретный зависший импорт:
update [dbo].[DataImportFinishLogs] set FinishTime = GETDATE() where (FinishTime is null) AND (ImportSettingsId = <ID_настроек_импорта>)
3. Проверьте, что зависших импортов не осталось. Для этого повторите запрос из п. 1 и убедитесь, что он возвращает пустой результат или что в результатах нет строки с ID настроек вашего импорта.
Добавление и редактирование настройки импорта¶
С технической точки зрения в реализации импорта данных участвуют модуль чтения (считывает данные из источника) и модуль записи (записывает данные в "Первую Форму"). Модуль чтения передает в модуль записи три массива: Created, Updated, Deleted. В каждом массиве находятся объекты со строковым идентификатором UniqueID. В зависимости от внутренней реализации модуль записи разрешает конфликты уникальности данных и выполняет необходимые действия.
Для добавления новой настройки импорта нажмите кнопку Создать. Откроется окно создания новой настройки:
Параметры настройки импорта данных:
| Название | Описание |
|---|---|
| Имя | Название настройки в системе (любой текст. включая латинские и кириллические символы, цифры и пр.) |
| Алиас | Адрес для вызова внешними системами (включает только латинские буквы без пробелов). Вызвать импорт можно через POST запрос вида \~/app/v1.0/api/DataSync/Import/NNNN?UserID=NN где \~ — адрес приложения "Первая Форма", NNNN — алиас, указанный в настройках импорта, а NN — ID пользователя от имени которого запускается импорт (обычно это служебный пользователь Systemrobot с ID=3) |
| Тип данных* | Тип данных, которые импортируются в систему. Возможные значения: -Task (задачи), -OrgStructureUnit (орг. единицы), -User (пользователи), -File (файлы). В заказных модулях импорта могут использоваться: -ExtParam (ДП), -TableColumn (колонка ДП "Таблица"), -None |
| Стратегия импорта | В настоящее время доступна только стратегия обычного импорта |
| Модуль чтения* | Выбор одного из реализованных модулей. Возможные значения: -CSV -SQL -Excel -HookService Reader (для импорта из другого приложения "Первая Форма") -Расширенная аналитика из Контур.Фокус (Устаревшее) -Экспресс-отчет по контрагенту из Контур.Фокус (Устаревшее) -Показатели бухгалтерской отчетности из Контур.Фокус (Устаревшее) -Контакты из Контур.Фокус (Устаревшее) -Выписка из ЕГРЮЛ/ЕГРИП из Контур.Фокус (Устаревшее) -Финансовый анализ бухгалтерской отчетности из Контур.Фокус (Устаревшее) -Актуализация реквизитов из Контур.Фокус (Устаревшее) |
| Модуль записи* | Выбор одной из стратегий записи. Возможные значения: -Задачи по номеру -Задачи по ключевым доп. параметрам -Задачи по GUID -DisposableTaskWriter -OrgStructureWriter -UsersWriter |
| Маппинг | Соответствия между импортируемыми данными и объектами "Первой Формы", в которые эти данные записываются |
После нажатия на кнопку Сохранить в таблице настроек появится новая запись. Вы можете отредактировать ее, нажав на соответствующую строку.
После сохранения для записи становятся доступны дополнительные настройки для стратегии импорта, модулей чтения и записи, а также настройка маппинга.
В зависимости от стратегии импорта и от выбранного модуля чтения или записи настройки имеют свои особенности.
Модули чтения
CSV
Настройки модуля чтения. Импорт из CSV:
Пользовательские настройки:
| Название | Описание |
|---|---|
| Разделитель | Символ-разделитель при перечислении значений |
Особенности импорта из CSV:
1. Файл с данными должен содержать только те колонки, которые используются при импорте, и только в том порядке, как они настроены в маппинге.
2. Ключевое поле должно быть первой колонкой в исходном файле и первой строкой в настройка маппинга.
3. Первая строка файла с данными при импорте всегда игнорируется (предполагается, что она содержит названия столбцов).
Excel
Настройки модуля чтения. Импорт из Excel:
Пользовательские настройки:
| Название | Описание |
|---|---|
| Отступ строк* | Число строк вверху страницы, которые будут игнорироваться при импорте данных (например, "шапка" с названиями колонок) |
| Номер листа* | Номер листа в многостраничной книге Excel. Обратите внимание, что иногда листы могут отображаться в обратном порядке. Предпочтительнее импортировать данные из файлов Excel, содержащих только один лист |
| Включить маппинг LookUp | Возможные значения: true/false (по умолчанию) |
Если в поле не задано значение или задано false, то предполагается, что в таблице Excel для ДП типа LookUp содержатся ID задач, на которые они ссылаются. Если в поле указано true, то значение ДП типа LookUp считается строкой. Для каждого значения будет выполнен поиск по тексту задач в категории, на которую настроен ДП, и если будет найдена задача с таким же текстом, то при импорте в задачу будет записана ссылка на нее.
ℹ️ В настройках ДП LookUp должны быть включены все статусы задач
SQL
Настройки модуля чтения. Импорт из SQL:
Пользовательские настройки:
| Название | Описание |
|---|---|
| Строка подключния | Строка подключения к БД вида: Data Source= \<адрес сервера БД>,\<порт>;Initial Catalog=\<имя каталога>;Persist Security Info=True;User ID=\<логин пользователя>;Password=\<пароль пользователя>;Max Pool Size=2500;MultipleActiveResultSets=false Параметр TrustServerCertificate. Если сервер БД использует самоподписанный SSL-сертификат или сертификат от недоверенного центра сертификации, добавьте в конец строки подключения параметр ;TrustServerCertificate=true. Без этого параметра подключение завершится ошибкой The certificate chain was issued by an authority that is not trusted. |
| Таблица | Имя таблицы, из которой импортируются данные |
| Запрос | Текст SQL-запроса для отбора данных для импорта |
| Фильтр | Дополнительное условие отбора, например: object_id=\'123456\' |
HookService Reader
Используется для импорта из другого приложения "Первая Форма". Настройки модуля чтения, импорт из "Первой Формы":
Пользовательские настройки:
| Название | Описание |
|---|---|
| ExcludeHooks | Список названий сервисов отсылки событий, которые не должны реагировать на получение события по этому импорту (разделители списка — символы "," или ";" или ":"). Список указывается для предотвращения бесконечного цикла синхронизации между приложениями |
| Формат* | Формат принимаемого сообщения (xml или json) |
| UserMapping | Список параметров для сопоставления пользователей (разделители списка — символы "," или ";" или ":") |
| GroupMapping | Список параметров для сопоставления групп (разделители списка — символы "," или ";" или ":") |
| UnitMapping | Список параметров для сопоставления орг. единиц (разделители списка — символы "," или ";" или ":") |
В полях UserMapping, GroupMapping и UnitMapping параметры перечисляются в том порядке, в котором они используются для поиска подходящей записи в БД. Например, при сопоставлении пользователей (поле UserMapping) сначала выполняется поиск по Guid; если подходящий пользователь найден, то поиск останавливается, а если не найден, то выполняется поиск по имени (Name), и так далее.
Импорт данных из Контур.Фокус (Устаревшее)
При интеграции с Контур.Фокус могут быть использованы следующие модели записи импорта: Расширенная аналитика из Контур.Фокус, Экспресс-отчет по контрагенту из Контур.Фокус, Показатели бухгалтерской отчетности из Контур.Фокус, Контакты из Контур.Фокус, Выписка из ЕГРЮЛ/ЕГРИП из Контур.Фокус, Финансовый анализ бухгалтерской отчетности из Контур.Фокус, Актуализация реквизитов из Контур.Фокус
Пользовательские настройки:
| Название | Описание |
|---|---|
| Ключ доступа | Key (string). Ключ доступа к Контур.Фокусу |
| Id ДП содержащий ИНН | InnExtParamId (int). ID параметра в "Первой Форме", в котором находится значение ИНН |
| Id ДП содержащий ОГРН | OgrnExtParamId (int). ID параметра в "Первой Форме", в котором хранится значение ОГРН |
Примеры импорта из Контур.Фокус
Модули записи
Задачи по номеру, Задачи по GUID
Настройки модуля записи, поиск задачи по номеру:
Пользовательские настройки:
| Название | Описание |
|---|---|
| Категория | ID категории для импортируемых задач |
| Текст задач по умолчанию | Текст, который проставляется для импортируемых задач (например, Договор) |
ℹ️ Поиск задачи по GUID используется в том случае, если синхронизация данных с внешней системой происходит регулярно (т.е. повторяется не один раз) и необходимо обновлять ранее загруженные задачи. Использование номера задачи в этом случает невозможно, т.к. значение TaskID генерируется только при создании задачи в "Первой Форме", а во внешней системе этого параметра нет.
Задачи по ключевым доп. параметрам
Настройки модуля записи. Поиск задачи по ключевым ДП:
Пользовательские настройки:
| Название | Описание |
|---|---|
| Категория | ID категории для импортируемых задач |
| Текст задач по умолчанию | Текст, который проставляется для импортируемых задач (например, Договор) |
| Многопоточность | Доступные значения: True\False. При включенном режиме многопоточности обработка импортируемых задач будет производиться параллельно в произвольном порядке. Поэтому многопоточность необходимо отключать, если нужно сохранить оригинальный порядок данных. Количество потоков никак не ограничивается и определяется количеством доступных ресурсов. (Для разработчиков — используется метод Parallel.ForEach.) |
OrgStructureWriter (Импорт орг.единиц)
Используются для импорта орг. единиц из внешней системы в "Первую Форму". В зависимости от источника данных, маппинг настраивается на колонки файла Excel или поля таблицы БД.
Пользовательские настройки:
| Название | Описание |
|---|---|
| Id корневой орг. единицы | ID орг. единицы, в рамках которой выполняется синхронизация. Если не указан — синхронизация выполняется для всей орг.структуры |
| Помечать не пришедшие орг. единицы, как не актуальные | True\False. По умолчанию False. Режим True позволяет помечать неакутальными те орг. единицы, которые не пришли из внешнего источника данных. |
Если для существующей орг. единицы не найдено соответствие в данных, пришедших из внешнего источника, то при включенном режиме (True) такая орг. единица помечается как неактуальная, а при выключенном режиме (False) сохраняет свое текущее состояние Особенности синхронизации:
-
Маппинг орг.единицы выполняется по полю ExternalId. Если соответствие с орг.единицей найдено, то она обновляется, если не найдено — создается
-
Маппинг родительской орг.единицы выполняется по полю ParentExternalId, внутри ветки с указанной корневой орг.единицей (родительская орг.единица также должна находиться внутри этой ветки)
-
Если родительская орг.единица указана и найдена, то она устанавливается как родительская для обновляемой\создаваемой орг. единицы
-
Если родительская орг. единица указана, но не найдена — у обновляемой орг. единицы родительская орг. единица не меняется (остается как было)
-
Если родительская орг. единица не указана, а в настройках указан Id корневой орг. единицы, то эта корневая орг. единица назначается родительской для текущей
-
Если родительская орг. единица не указана и Id корневой орг. единицы не указан в настройках, то текущая орг. единица остается без родительской орг. единицы
Возможные поля для маппинга при загрузке орг. единиц:
| Поле | Тип | Описание | Обязательность | Что может содержать |
|---|---|---|---|---|
| Name | string | Название | обязательно | строка |
| Description | string | Описание | \ | строка |
| ExternalId | string | Внешний идентификатор | обязательно | строка |
| ParentExternalId | string | Внешний идентификатор родительской орг. единицы | \ | строка |
| TypeId | int | Id типа орг. структуры в "Первой Форме" | \ | число |
| IsDirector | bool | Является руководителем | \ | "true", "yes", "да" / "false", "no", "нет" |
UsersWriter (Импорт пользователей)
Используются для импорта пользователей из внешней системы в "Первую Форму". В зависимости от источника данных, маппинг настраивается на колонки файла Excel или поля таблицы БД.
Возможные поля для маппинга при загрузке пользователей:
| Поле | Тип | Описание | Обязательность | Что может содержать |
|---|---|---|---|---|
| Nick | string | Логин | обязательно | строка |
| LastName | string | Фамилия | обязательно | строка |
| FirstName | string | Имя | \ | строка |
| MiddleName | string | Отчество | \ | строка |
| Phone | string | Телефон | \ | строка |
| Phone2 | string | Телефон | \ | строка |
| Phone3 | string | Телефон | \ | строка |
| IsFired | bool | Уволен | \ | "true", "yes", "да" / "false", "no", "нет" |
| SignsAllOwnedTasks | bool | Требует акцепта всех своих задач для перехода в статусы с акцептом заказчика | \ | "true", "yes", "да" / "false", "no", "нет" |
| string | обязательно | строка | ||
| ExternalEmail | string | Внешний email | \ | строка |
| ComputerName | string | Имя компьютера | \ | строка |
| RoomID | int | Id комнаты | \ | целое число |
| DisplayName | string | Псевдоним (рус) | обязательно | строка |
| EnglishDisplayName | string | Отображаемое имя на английском | \ | строка |
| ExternalDisplayName | string | Внешнее отображаемое имя | \ | строка |
| Password | string | Пароль | \ | строка |
| LanguageID | int | Id языка интерфейса (1 — русский, 0 — английский) | \ | целое число |
| CellPhone | string | Мобильный | \ | строка |
| HomePhone | string | Домашний | \ | строка |
| Fax | string | Факс | \ | строка |
| Skype | string | Скайп | \ | строка |
| ICQ | string | ICQ | \ | строка |
| LiveJournal | string | Живой Журнал | \ | строка |
| string | \ | строка | ||
| IsEmployee | bool | Cотрудник компании | \ | "true", "yes", "да" / "false", "no", "нет" |
| CanEditWorkInfo | bool | Mожет редактировать блок Рабочее | \ | "true", "yes", "да" / "false", "no", "нет" |
| CanEditGeoInfo | bool | Mожет редактировать блок География | \ | "true", "yes", "да" / "false", "no", "нет" |
| CanEditContactsInfo | bool | Mожет редактировать блок Контакты | \ | "true", "yes", "да" / "false", "no", "нет" |
| BirthDate | datetime | День рождения | \ | dd.MM.yyyy HH:mm |
| WorkStartDate | datetime | Дата начала работы в компании | \ | dd.MM.yyyy HH:mm |
| Country | string | Страна | \ | строка |
| City | string | Город | \ | строка |
| DisableMail | bool | Отключить почту | \ | "true", "yes", "да" / "false", "no", "нет" |
| Gender | bool | Пол (1 — мужчина, 0 — женщина) | \ | "true", "yes", "да" / "false", "no", "нет" |
| SIP | string | SIP номер | \ | строка |
| SIP_Password | string | SIP пароль | \ | строка |
| SIP_Host | string | SIP домен | \ | строка |
| SIP_Port | string | SIP порт | \ | строка |
| SIP_Host_Reserve | string | SIP резервный домен | \ | строка |
| SIP_Port_Reserve | string | SIP резервный порт | \ | строка |
| SIP_Account | string | SIP аккаунт | \ | строка |
| Notes | string | Заметки | \ | строка |
| SID | string | SIP в Active Directory | \ | строка |
| GuidFrom1C | string | Guid в 1С | \ | GUID |
| DoSyncWithExchange | bool | Синхронизировать с Exchange | \ | "true", "yes", "да" / "false", "no", "нет" |
| AutoReadCommentsInTask | bool | Автопрочтение сообщений при просмотре задачи | \ | "true", "yes", "да" / "false", "no", "нет" |
| PhoneAdditional | string | Дополнительный телефон | \ | строка |
| Phone2Additional | string | Дополнительный телефон | \ | строка |
| Phone3Additional | string | Дополнительный телефон | \ | строка |
| HomePhoneAdditional | string | Дополнительный телефон | \ | строка |
| Guid | string | Guid | \ | GUID |
| MaidenName | string | Девичья фамилия | \ | строка |
| DomainController | string | Домен Active Directory | \ | строка |
| TimeZoneId | string | Id временной зоны | \ | строка |
| PrimaryOrgStructureUnitId | int | Основная орг. Единица | \ | целое число |
| PrimaryOrgStructureUnitExternalId | string | Ключ основной орг.единицы для синхронизации | \ | строка |
| CanEditAvatar | bool | Может менять аватар | \ | "true", "yes", "да" / "false", "no", "нет" |
| CanEditPassword | bool | Может менять пароль | \ | "true", "yes", "да" / "false", "no", "нет" |
| IsInMaternityLeave | bool | В декретном отпуске | \ | "true", "yes", "да" / "false", "no", "нет" |
| RestrictCellPhoneView | bool | Ограничить видимость телефона | \ | "true", "yes", "да" / "false", "no", "нет" |
| AllowChangeDisplayNameMode | bool | Может менять режим отображения имен | \ | "true", "yes", "да" / "false", "no", "нет" |
| DisableMailWhenOnline | bool | Не присылать почтовые сообщения когда онлайн | \ | "true", "yes", "да" / "false", "no", "нет" |
| DisableMailWhenWorkTime | bool | Не присылать почтовые сообщения в рабочее время | \ | "true", "yes", "да" / "false", "no", "нет" |
| DisableMailWhenAbsence | bool | Не присылать почтовые сообщения когда отсутствует | \ | "true", "yes", "да" / "false", "no", "нет" |
| AutoReadComments | bool | Автопрочтение сообщений | \ | "true", "yes", "да" / "false", "no", "нет" |
| AutoReadCommentsInMTF | bool | Автопрочтение сообщений в МТФ | \ | "true", "yes", "да" / "false", "no", "нет" |
| DoNotUseGeolocation | bool | Не использовать геолокацию | \ | "true", "yes", "да" / "false", "no", "нет" |
| HideBirthYear | bool | Скрыть год рождения | \ | "true", "yes", "да" / "false", "no", "нет" |
| UserText | string | Персональная информация | \ | строка |
| UserNameModeId | int | Режим отображения имен | \ | целое число |
| BusinessFunctions | string | Функционал | \ | строка |
Настройки маппинга
ℹ️ Маппинг — это описание соответствий между импортируемыми данными и объектами "Первой Формы", в которые эти данные записываются. Для каждого импортируемого элемента создается отдельная строка маппинга.
Чтобы получить образец маппинга для данной настройки импорта, нажмите на кнопку Пример данных. При этом будет создан и загружен файл-образец формата в соответствии с моделью запсиси.
Маппинг настраивается в окне настроек импорта.
Нажмите на кнопку Создать для добавления нового соответствия.
Настройки маппинга (шапка таблицы настроек):
| Название | Описание |
|---|---|
| Внешний идентификатор | Имя поля во внешней системе: колонка CSV или Excel, поле в SQL. Для импорта из другого приложения "Первая Форма": TaskId — ID задачи, Text — текст задачи, ResponsibleId — ID ответственного исполнителя, OwnerId — ID заказчика, StepId — ID перехода на маршруте задачи, epXXX — ДП, где XXX — ID ДП, epXXX_ZZZ — столбец ДП "Таблица", где XXX — ID ДП "Таблица", ZZZ — ID столбца. Примечание: имя внешнего идентификатора чувствительно к регистру (например, TaskId правильно, TaskID — нет) |
| Идентификатор в "Первой Форме" | При импорте задач — основной или дополнительный параметр: TaskId (вводится вручную) или ДП из выпадающего списка (по ID ДП). При импорте пользователей и оргструктуры — поле таблицы БД в "Первой Форме". Примечание: значения не отображаются в списке доступных, если они уже были выбраны ранее в данном импорте |
| Тип поля | Сущность, к которой относятся данные: Task — для TaskId, ExtParam — для ДП, GUID — для ДП типа Lookup при импорте из CSV, OrgStructure — для орг. единицы, User — для пользователя, File — для файла, TableColumn — для колонки ДП "Таблица" (используется только в заказных модулях импорта) |
| Тип данных | Тип импортируемых данных (практически всегда можно указывать String). Возможные значения: String, Integer, Boolean, Date, DateTime, Double, Lookup, Address, File, Guid |
| Ключ | Признак, является ли поле ключом для импортируемой сущности |
Пример настройки маппинга данных:
Описание импорта данных в прежнем интерфейсе администрирования Полезные ссылки