Адаптер импорта данных в платформу. Настройка подключения, пути передачи данных и сценария

Введение

Comindware Platform может получать данные от внешних систем с помощью адаптера импорта данных.

В интерфейсе администрирования адаптер настраивается как подключение к шине сообщений. Адаптер преобразует входящее XML- или JSON-сообщение во внутреннюю структуру DataImport и передаёт данные в сценарий для создания или обновления записей.

Если интеграция с внешней системой требует дополнительной обработки входящих данных, используйте вариант адаптера или пример его реализации, предоставленный Comindware. Такой адаптер может разобрать входящее сообщение или HTTP-запрос, сопоставить поля со структурой сообщения и передать данные в механизм DataImport.

Связь с получением сообщений через Kafka

Адаптер для импорта данных решает ту же прикладную задачу, что и получение сообщений через Apache Kafka: принимает данные из внешней системы, преобразует их в сообщение Comindware Platform и запускает сценарий для создания или обновления записей.

Различается способ доставки данных:

• при получении сообщений через Apache Kafka Comindware Platform получает сообщение и передаёт его в сценарий для дальнейшей обработки;
• при использовании адаптера для импорта данных Comindware Platform дополнительно сопоставляет поля сообщения с моделью шаблона записи и передаёт данные в механизм DataImport.

Используйте адаптер для импорта данных, если требуется импортировать записи в шаблон с учётом ключевых атрибутов, действий создания или обновления и правил сопоставления полей.

Логика работы адаптера

1. Внешняя система передаёт сообщение в настроенный источник данных.
2. Адаптер получает сообщение и преобразует его во внутреннюю структуру DataImport.
3. Comindware Platform сопоставляет поля сообщения с атрибутами выбранного шаблона записи.
4. По ключевым атрибутам выполняется поиск существующих записей.
5. В зависимости от выбранного действия Comindware Platform создаёт, обновляет либо создаёт или обновляет записи.
6. Comindware Platform запускает сценарий с событием «Получение сообщения» для дальнейшей обработки полученного сообщения.

Предварительные требования

• Адаптер для импорта данных установлен, опубликован и доступен в списке подключений к шинам сообщений.
• Если адаптер отсутствует в списке подключений или требуется доработать сопоставление полей под внешний XML-контракт, запросите адаптер или пример его реализации у Comindware.
• Сервер Apache Kafka доступен для сервера Comindware Platform, если обмен выполняется через Apache Kafka.
• Подготовлен шаблон записи для импортируемых данных.
• Известна структура входящего XML- или JSON-сообщения внешней системы.
• У пользователя есть права на настройку подключений, путей передачи данных и сценариев.

Формат входящего XML-запроса

Адаптер обрабатывает XML-запросы, структура которых согласована с внешней системой и соответствует данным, передаваемым в Comindware Platform.

Согласуйте структуру XML-запроса с внешней системой и используйте понятные имена элементов, отражающие состав передаваемых данных.

Пример входящего XML-запроса:

<Requests> 
    <Request> 
        <ContactName>Иванов Иван</ContactName> 
        <RequestSummary>Краткое описание заявки</RequestSummary> 
        <ResolutionActions>Необходимые действия</ResolutionActions> 
        <RequestCategory> 
            <Code>SUPPORT</Code> 
        </RequestCategory> 
    </Request> 
</Requests> 

Пример сопоставления XML-элементов с полями сообщения:

Настройка подключения

1. Откройте страницу «Администрирование» — «Подключения».
2. Создайте или настройте подключение к шине сообщений типа «Адаптер импорта данных в платформу».

3. Настройте свойства подключения:

   • Системное имя — введите уникальное системное имя подключения, например platform_receive_messages_connection. Не должно начинаться с цифры. Разрешены английские и русские буквы, цифры и символ «_». Рекомендуется использовать английские буквы.
   • Отключить — установите этот флажок, если требуется временно отключить подключение.
   • Описание — введите наглядное описание подключения, например «Импорт данных из внешней системы».
   • Запись в файловые журналы — выберите способ записи сведений о работе подключения:
     • Полные сведения об обработке сообщения;
     • Только ошибки;
     • Отключить.
   • Список пар хост/порт (разделённых запятой), используемых для подключения к кластеру Kafka — введите адреса одного или нескольких узлов кластера Apache Kafka, например 12.34.56.78:9092.
   • Максимальный объём данных (в байтах), который брокеры должны возвращать по запросу сообщений — введите лимит для ответа каждого брокера.
   • Количество байтов, которые необходимо попытаться получить для каждого топика-партиции в каждом запросе сообщений — введите объём данных для получения от Apache Kafka, не меньше максимального размера сообщения, допустимого сервером Apache Kafka.
   • Тайм-аут (в миллисекундах) для запросов на стороне сервера Kafka — введите лимит времени обработки запроса сервером Apache Kafka.
   • Тайм-аут на стороне клиента (в миллисекундах) — введите лимит времени ожидания ответа от сервера Apache Kafka.
   • Временной интервал (в миллисекундах) для пакетной обработки сообщений, используемых при запросах сообщений — введите интервал опроса Apache Kafka.
   • Имя пользователя и пароль — введите логин и пароль для подключения к серверу Apache Kafka.

4. Сохраните подключение.

Настройка пути передачи данных

1. Откройте страницу «Администрирование» — «Пути передачи данных».
2. Создайте или настройте путь передачи данных для подключения к шине сообщений типа «Адаптер импорта данных в платформу».

3. На вкладке «Основные свойства» настройте параметры:

   • Подключение — выберите подключение адаптера импорта данных.
   • Системное имя — введите уникальное системное имя пути передачи данных, например platform_receive_messages_route. Не должно начинаться с цифры. Разрешены английские и русские буквы, цифры и символ «_». Рекомендуется использовать английские буквы.
   • Отключить — установите этот флажок, если требуется временно отключить путь передачи данных.
   • Описание — введите наглядное описание пути передачи данных, например «Импорт данных из внешней системы».
   • Номер шины данных — выберите номер от 0 до 3, если требуется распределить потоки данных нескольких путей для повышения производительности.

4. На вкладке «Атрибуты сообщений» настройте параметры импортируемых данных:

   • Тип сообщения — выберите тип «Адаптер импорта данных в платформу».
   • Приложение — выберите приложение, в которое требуется импортировать данные.
   • Шаблон — выберите шаблон записи, данные в который требуется импортировать. После выбора шаблона в таблице отобразятся его атрибуты, включая атрибуты связей с другими шаблонами.

   Сопоставление атрибутов

   Структура модели запроса должна соответствовать модели шаблона записи. Имена полей запроса могут отличаться от системных имён атрибутов шаблона: для сопоставления используйте столбец «Альтернативное название». Если имена полей запроса совпадают с системными именами атрибутов, Comindware Platform сопоставит их автоматически.

5. В таблице атрибутов проверьте и настройте столбцы:

   Столбец	Назначение
   Системное имя	Отображает системное имя атрибута
   Название	Отображает название атрибута
   Ключевой атрибут	Установите этот флажок, если по значению атрибута требуется искать запись в шаблоне
   Тип данных	Отображает тип данных атрибута из шаблона
   Действие	Позволяет выбрать, что делать с записью: создать, обновить либо создать или обновить
   Тип обновления данных	Позволяет выбрать способ обновления связанных данных: добавить новые значения или заменить существующие
   Альтернативное название	Позволяет сопоставить поле сообщения с атрибутом шаблона записи

   Пример типа обновления данных

   Если выбран тип обновления «Добавить», новые связанные записи добавляются к существующим. Например, если в заказе уже есть позиции 1 и 2, а во входящем сообщении пришла позиция 3, после импорта заказ будет содержать позиции 1, 2 и 3.

   Если выбран тип обновления «Заменить», связанные данные из сообщения заменяют существующие. Например, если в заказе уже есть позиции 1 и 2, а во входящем сообщении пришла позиция 3, после импорта заказ будет содержать только позицию 3.

6. На вкладке «Интеграция» настройте параметры получения сообщения:

   • Очередь — введите название топика Apache Kafka, который требуется прослушивать, например CLIENT_ORDERS.
   • Тип содержимого — выберите формат передачи данных:
     • XML;
     • JSON.
   • Уникальная текстовая строка — укажите название группы потребителей. Например, введите имя экземпляра ПО Comindware Platform. Название группы потребителей служит для отслеживания новых сообщений в топике. Не назначайте это название группы другим потребителям, иначе будет утрачен прогресс считывания сообщений из топика.

7. Сохраните путь передачи данных.

Настройка сценария

Для получения сообщений и передачи данных в шаблон записи настройте сценарий, срабатывающий при поступлении сообщения из адаптера.

1. Откройте страницу администрирования приложения.
2. Выберите пункт «Сценарии».
3. Создайте сценарий, например «Импорт данных».

4. Настройте свойства сценария:

   • Контекст выполнения — выберите подходящий контекст выполнения, например «От инициатора».
   • Статус — на время настройки выберите «Приостановлен», после проверки сценария выберите «Активен».

5. В конструкторе сценария настройте стартовое событие:

   • Тип — «Получение сообщения».
   • Контекстный шаблон — выберите шаблон записи, указанный в пути передачи данных.
   • Подключение — выберите подключение адаптера импорта данных.
   • Путь передачи данных — выберите путь передачи данных адаптера импорта данных.
   • Имя переменной — укажите переменную для полученного сообщения, например platform_message.

6. Добавьте действия для создания или обновления записей на основе полученного сообщения.

7. Сохраните и активируйте сценарий.

Проверка работы адаптера

Отправьте тестовое сообщение во входной топик и проверьте, что сценарий с событием «Получение сообщения» выполнился без ошибок.

sudo -i 
cd /usr/share/kafka/bin 
bash kafka-console-producer.sh --bootstrap-server 12.34.56.78:9092 --topic CLIENT_ORDERS 

Вставьте тестовое сообщение в формате XML или JSON и нажмите клавишу Ввод.

Ограничения

• Адаптер начинает принимать и обрабатывать сообщения только после создания и включения подключения и пути передачи данных.
• Сообщения, отправленные до создания или включения пути передачи данных, не обрабатываются после включения.
• Передача документов не поддерживается.
• Для интеграции с внешней системой и сопоставления нестандартной структуры XML со структурой шаблонов можно разработать пользовательский адаптер. На уровне адаптера можно разобрать входящий запрос, сопоставить поля и использовать механизм DataImport.

Для использования механизма DataImport в пользовательском адаптере добавьте в файл Adapter.cs следующий метод:

public override PerformerType GetPerformerType() 
{ 
    return PerformerType.DataImport; 
} 

Диагностика

Для подробной диагностики просмотрите журналы адаптера и события получения сообщений. См. «Журналы событий. Типы, просмотр, цепочки событий».