Універсальний SOAP-конектор для взаємодії з учасниками інформаційного обміну через ШБО "Трембіта"

1. Загальний опис

На даний момент, Платформа надає обмежений набір типових SOAP-конекторів для моделювання інтеграцій з учасниками інформаційного обміну через ШБО "Трембіта":

Єдиний державний реєстр (ЄДР)
Державний реєстр актів цивільного стану (ДРАЦС)
Єдина інформаційна база даних внутрішньо переміщених осіб (ЄІБДВПО)

Кожна нова інтеграція потребує розробки, випуску нової версії Платформи та оновлення реєстру, що суттєво обмежує та ускладнює процес моделювання регламентів реєстрів.

З ціллю забезпечення інтероперабельності реєстрів, Платформа має надавати інтерфейс налаштуванню учасників інформаційного обміну "Трембіта" та SOAP-конектор для гнучкого моделювання точок інтеграції на рівні бізнес-процесів в залежності від вимог.

2. Функціональні сценарії

Створення, зміна та видалення технічним адміністратором реєстру записів з налаштуваннями учасників інформаційного обміну Трембіта задіяних в інтеграціях реєстру.
Моделювання точок інтеграції з налаштованим учасником інформаційного обміну на рівні бізнес-процесів з використанням універсального SOAP-конектора.
Скриптування запиту до веб-сервісу, який потребує додаткової авторизації, з використанням службової JUEL-функції отримання налаштувань авторизаційного токену учасника інформаційного обміну.

3. Ролі користувачів

Технічний адміністратор реєстру
Розробник регламенту

4. Загальні принципи та положення

Налаштування учасників інформаційного обміну Трембіта, дозволених для використання при моделюванні інтеграцій реєстру виконується на рівні Веб-інтерфейсу управління Платформою та реєстрами
Секрети, необхідні для взаємодії з учасників інформаційного обміну зберігаються у захищеному сховищі Сервісу управління секретами та шифруванням
Моделювання інтеграцій з використанням універсального SOAP-конектору не потребує від розробника регламенту дублювання налаштувань учасників інформаційного обміну Трембіта
У разі необхідності моделювання інтеграцій, які потребують додаткової авторизації, Платформа надає службові функції для отримання доступу до секретів при скриптуванні запиту в бізнес-процесах

5. Високорівневий дизайн рішення

Дана функціональність використовує механізми закладені в дизайні Управління налаштуваннями та секретами зовнішніх інтеграцій.

6. Управління конфігурацією реєстру

6.1. Конфігурація реєстру

control-plane-gerrit:<registry>.git

deployment-templates/values.yaml

trembita:
  registries:
    edrlike-registry:
      user-id: "DDM"
      protocol-version: "4.0"
      url: "https://trembita.mdtu-ddm.projects.epam.com"
      type: "registry" # новий тип
      protocol: "SOAP"
      client:
        x-road-instance: "THIS-REGISTRY"
        member-class: "GOV"
        member-code: "1488"
        subsystem-code: "Platform-registry"
      service:
        x-road-instance: "THAT-REGISTRY"
        member-class: "GOV"
        member-code: "42"
        subsystem-code: "Edrllike-system"
      # опційний блок авторизації
      auth:
        type: "AUTH_TOKEN"
        secret: "vault:registry-kv/registry/<registry>/trembita-registries/<trembita-registry-name>"
    new-registry:
      user-id: "DDM"
      protocol-version: "4.0"
      url: "https://trembita.mdtu-ddm.projects.epam.com"
      type: "registry" # новий тип
      protocol: "SOAP"
      client:
        x-road-instance: "THIS-REGISTRY"
        member-class: "GOV"
        member-code: "1488"
        subsystem-code: "Platform-registry"
      service:
        x-road-instance: "THAT-REGISTRY"
        member-class: "GOV"
        member-code: "13"
        subsystem-code: "New-system"

6.2. Інтерфейси адміністратора

Перелік налаштувань взаємодії з реєстрами через Трембіту розширюється:

Новим типом для атрибуту Рівень - Реєстровий
Можливістю додавання нових взаємодій на рівні реєстру
Можливістю видалення створених для поточного реєстру взаємодій

Екран конфігурації реєстру

Зображення 1. Загальний вигляд блоку налаштувань

Додавання нової конфігурації

Зображення 2. Додавання нової конфігурації з авторизаційним токеном

Зображення 3. Додавання нової конфігурації без додаткової авторизації

З міркувань безпеки, Службова назва реєстру не може бути змінена після збереження конфігурації, та має бути унікальна в рамках реєстру

7. Моделювання регламенту реєстру

7.1. Референтний бізнес-процес моделювання інтеграції через ШБО "Трембіта"

7.2. Службова JUEL-функція отримання доступу до секрету з налаштувань учасника інформаційного обміну

Отримання авторизаційного токена через JUEL-функцію в БП

Приклад використання

get_trembita_auth_token('edrlike-registry')

Результатом виконання JUEL-функції є значення поля секрету trembita-registries-secrets за маскою trembita.registries.<registry-name>.auth.secret.token

7.3. Конфігурація інтеграційного SOAP-конектора

В основі конектора для відправки SOAP повідомлень використовується SoapHttpConnector. З розширенням можливості. Розширення даних запиту до ШБО "Трембіта" службовими тегами в конекторі.

Значення для параметрів беруться з ConfigMap trembita-registries-configuration

Конфігураційний параметр	Вхідний/Вихідний	Тип	Опис
Службова назва реєстру учаснику ШБО "Трембіта"	in	string	Назва яка була вказана в якості службової при створенні конфігурації в адміністративній консолі
Назва операції	in	string	Назва операції (метода SOAP) який буде викликатись
Дані запиту	in	string	Дані для запиту без службових полів
Вихідний результат запиту	out	SpinXmlElement	Строкове представлення відповіді від ШБО "Трембіта"

Конфігураційний параметр

Вхідний/Вихідний

Тип

Опис

Службова назва реєстру учаснику ШБО "Трембіта"

string

Назва яка була вказана в якості службової при створенні конфігурації в адміністративній консолі

Назва операції

string

Назва операції (метода SOAP) який буде викликатись

Дані запиту

string

Дані для запиту без службових полів

Вихідний результат запиту

out

SpinXmlElement

Строкове представлення відповіді від ШБО "Трембіта"

trembita:
  registries:
    <edrlike-registry>
      user-id: "..."
      protocol-version: "..."
      ...
    <new-registry>
      user-id: "..."
      protocol-version: "..."
      ...

Перелік і структура службових тегів обовʼязкових для запиту до ШБО "Трембіта"

<xro:client iden:objectType="?" xmlns:xro="http://x-road.eu/xsd/xroad.xsd" xmlns:iden="http://x-road.eu/xsd/identifiers">
    <iden:xRoadInstance>?</iden:xRoadInstance>
    <iden:memberClass>?</iden:memberClass>
    <iden:memberCode>?</iden:memberCode>
    <iden:subsystemCode>?</iden:subsystemCode>
</xro:client>
<xro:service iden:objectType="SERVICE" xmlns:xro="http://x-road.eu/xsd/xroad.xsd" xmlns:iden="http://x-road.eu/xsd/identifiers">
    <iden:xRoadInstance>?</iden:xRoadInstance>
    <iden:memberClass>?</iden:memberClass>
    <iden:memberCode>?</iden:memberCode>
    <iden:subsystemCode>?</iden:subsystemCode>
    <iden:serviceCode>?</iden:serviceCode>
    <iden:serviceVersion>?</iden:serviceVersion>
</xro:service>
<xro:userId xmlns:xro="http://x-road.eu/xsd/xroad.xsd">?</xro:userId>
<xro:id xmlns:xro="http://x-road.eu/xsd/xroad.xsd">?</xro:id>
<xro:protocolVersion xmlns:xro="http://x-road.eu/xsd/xroad.xsd">?</xro:protocolVersion>

Приклад структури вхідного параметру універсального конектора з відсутністю корінного тега

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Header>
      <edr:AuthorizationToken xmlns:edr="http://nais.gov.ua/api/sevdeir/EDR">?</edr:AuthorizationToken>
   </Header>
   <Body>
      <edr:SubjectStateDict2Ext xmlns:edr="http://nais.gov.ua/api/sevdeir/EDR">?</edr:SubjectStateDict2Ext>
   </Body>
</Envelope>

Формат відповідного запиту до ШБО "Трембіта"

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Header>
        <!-- Обовʼязковий блок який формується в конекторі-->
        <!-- ... -->
        <edr:AuthorizationToken xmlns:edr="http://nais.gov.ua/api/sevdeir/EDR">?</edr:AuthorizationToken>
   </Header>
   <Body>
        <edr:SubjectStateDict2Ext xmlns:edr="http://nais.gov.ua/api/sevdeir/EDR">?</edr:SubjectStateDict2Ext>
   </Body>
</Envelope>

8. Міграція існуючих бізнес-процесів з використанням стандартного SoapHttpConnector

Основною відмінністю цільової імплементації універсального SOAP-конектору до ШБО "Трембіта" в порівнянні з стандартним - є спрощення управління службовими полями необхідними для інтеграції.

В загальному вигляді міграція з попердньої версії буде включати в себе наступні кроки:

Створення конфігурації в розділі Налаштування взаємодії з реєстрами через ШБО "Трембіта" для реєстрів з якими існує інтеграція і перенесення даних підключення з рівня регламенту (scriplet-задачі окремого БП)
Видалення ручного створення службових тегів в scriplet-задачі формування запиту до ШБО "Трембіта"
[ОПЦІЙНО] У разі використання авторизаційного токена - використати JUEL функцію для його отримання з конфігурації взаємодії.
Застосування нового Універсальний SOAP-конектор для взаємодії з ШБО Трембіта.

9. Високорівневий план розробки

9.1. Технічні експертизи

BE (Java, Go)

9.2. План розробки

Розширення бібліотеки ddm-starter-juel-function новою JUEL-функціює для читання значення секретів.
Додати нову функцію в адміністративний портал для автодоповнення.
Створення нового розширення для camunda.
Розширення функціональності адмін консолі (control-plane) можливістю додавати нові реєстри для інтеграції через ШБО "Трембіта".
Створення референтного прикладу бізнес-процесу з використання конектору та JUEL-функції
Створення інструкцій для технічного адміністратора та розробника регламенту
Включення інструкції в реліз по міграції для реєстрів, які використовують стандартний SOAP-конектор