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

Введение

Адаптер для экспорта данных используется для отправки данных из шаблонов записи Comindware Platform во внешние системы через топики Apache Kafka.

В отличие от получения сообщений через Apache Kafka, где Comindware Platform считывает сообщения из топика, адаптер экспорта публикует сообщения в топик. В отличие от адаптера для импорта данных, который создаёт или обновляет записи по входящим сообщениям, этот адаптер формирует исходящие сообщения по данным шаблона записи.

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

1. В Comindware Platform настраивают подключение к Apache Kafka.
2. В пути передачи данных выбирают приложение, шаблон записи, атрибуты для экспорта и топик Apache Kafka.
3. Сценарий с действием отправки сообщения запускается по нажатию кнопки в записи или в процессе.
4. Адаптер формирует сообщение на основе данных записи и публикует его в топик.
5. Внешняя система считывает сообщение из топика Apache Kafka.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   Столбец	Назначение
   Системное имя	Отображает системное имя атрибута
   Название	Отображает название атрибута
   Тип данных	Отображает тип данных атрибута из шаблона
   Альтернативное название	Позволяет переопределить имя поля в теле сообщения

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

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

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

Настройка сценария отправки сообщения

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

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

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

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

4. В конструкторе сценария нажмите заголовок стартового события «Нажатие кнопки».

5. Выберите кнопку шаблона записи или процесса, по нажатию которой требуется экспортировать данные.
6. Добавьте действие отправки сообщения.

7. Настройте свойства действия:

   • Подключение — выберите подключение адаптера экспорта данных, например platform_send_messages_connection.
   • Путь передачи данных — выберите путь передачи данных адаптера экспорта данных, например platform_send_messages_route.

8. При необходимости настройте дополнительные действия постобработки.

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

Проверка работы экспорта

1. Откройте запись шаблона, выбранного в пути передачи данных.
2. Нажмите кнопку, настроенную как стартовое событие сценария.
3. Проверьте, что сценарий выполнился без ошибок.
4. Проверьте, что сообщение появилось в топике Apache Kafka.

Пример проверки топика с помощью консольного потребителя Apache Kafka:

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

Ограничения

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

Если для парного сценария обмена требуется принимать ответные сообщения внешней системы через механизм DataImport, в пользовательском адаптере добавьте в файл Adapter.cs следующий метод:

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

Диагностика