Налаштування взаємодії з реєстрами через ШБО "Трембіта" у Control Plane

На цій сторінці:

1. Вступ до інтеграції з реєстрами через ШБО "Трембіта"
2. Конфігурація сервісів та параметрів інтеграції
3. Налаштування інтеграційних можливостей у Control Plane
4. Перегляд налаштувань інтеграції та розгортання змін

1. Вступ до інтеграції з реєстрами через ШБО "Трембіта"

Платформа надає можливості для інтеграції з зовнішніми сервісами та іншими реєстрами через ШБО "Трембіта". Це дозволяє легко отримувати необхідні дані з різних джерел у стандартизованому форматі.

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

Щоб використовувати ці інтеграційні можливості, потрібно спершу виконати налаштування на рівні екземпляра реєстру. Усі конфігурації здійснюються через адміністративну панель Control Plane. Після збереження змін, потрібні мережеві політики застосовуються автоматично — додаткові ручні налаштування не потрібні.

Детальніше про каталог доступних SOAP-конекторів та їх можливості читайте тут — Інтеграційні SOAP-конектори до інших реєстрів.

2. Конфігурація сервісів та параметрів інтеграції

За замовчуванням доступна інтеграція з 5 сервісами, що належать до 3-х реєстрів під управлінням 2-х міністерств. Це дозволяє швидко підключатися до основних державних реєстрів без додаткової розробки.

Окрім готових інтеграцій, Платформа підтримує підключення нових сервісів-учасників СЕВ ДЕІР "Трембіта", що дає змогу розширювати функціональність та інтегрувати будь-які зовнішні джерела даних за потреби.

2.1. Пошук підсистем та сервісів у СЕВ ДЕІР "Трембіта"

Щоб використовувати сервіс ШБО "Трембіта", він спершу має бути зареєстрований у системі СЕВ ДЕІР "Трембіта". Лише зареєстровані підсистеми та сервіси можуть бути інтегровані через платформу.

Для пошуку потрібного сервісу або підсистеми у СЕВ ДЕІР "Трембіта" використовуйте офіційний каталог. Нижче наведено покроковий алгоритм для пошуку.

Щоб знайти потрібну підсистему або сервіс для інтеграції через "Трембіту", дотримуйтеся наступного алгоритму:

Відкрийте офіційний каталог підсистем "Трембіти".
Оберіть середовище:
- SEVDEIR-TEST — тестове середовище для розробки та перевірок.
- SEVDEIR-PROD — промислове середовище для продуктивних інтеграцій.

Знайдіть потрібну підсистему за кодом:

Використовуйте поле Код підсистеми для пошуку.
Наприклад, для Єдиного державного реєстру (ЄДР) міністерства юстиції використовуйте код 2_MJU_EDR_prod.

Зверніть увагу, що _prod означає, що це підсистема-власник/виробник даних (producer), а не вказівка на продуктивне середовище.

Перегляньте доступні сервіси у підсистемі:
- У розділі Сервіси знайдіть потрібний сервіс.
- Наприклад, сервіс SearchSubjects використовується для пошуку суб’єкта в ЄДР.
Повний ідентифікатор сервісу формується за таким шаблоном:
```
SEVDEIR-ENV/GOV/КОД_ОРГАНУ/КОД_ПІДСИСТЕМИ/СЕРВІС
```

2.2. Каталог інтегрованих підсистем та сервісів "Трембіта"

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

Каталог інтеграцій через Трембіту

Міністерство	Реєстр	Сервіс	Опис	Повний ID сервісу
Міністерство юстиції України	Єдиний державний реєстр (ЄДР)	SearchSubjects	Сервіс пошуку суб'єкта в ЄДР	SEVDEIR-TEST/GOV/00015622/2_MJU_EDR_prod/SearchSubjects
	Єдиний державний реєстр (ЄДР)	SubjectDetail	Сервіс отримання детальної інформації про суб'єкта	SEVDEIR-TEST/GOV/00015622/2_MJU_EDR_prod/SubjectDetail
	Державний реєстр актів цивільного стану (ДРАЦС)	GetCertByNumRoleNames	Вивантаження даних свідоцтва за серією, номером та ПІБ	SEVDEIR-TEST/GOV/00015622/3_MJU_DRACS_prod/GetCertByNumRoleNames
	Державний реєстр актів цивільного стану (ДРАЦС)	GetCertByNumRoleBirthDate	Вивантаження даних свідоцтва за серією, номером та датою народження	SEVDEIR-TEST/GOV/00015622/3_MJU_DRACS_prod/GetCertByNumRoleBirthDate
Міністерство соціальної політики України	Єдина інформаційна база даних ВПО (ЄІБДВПО)	IDPexchangeService	Сервіс пошуку довідки ВПО	SEVDEIR-TEST/GOV/37567866/51_IDP_prod/IDPexchangeservice

Пояснення до таблиці:

У таблиці наведено тестові середовища (SEVDEIR-TEST).
Для інтеграції з продуктивним середовищем замініть SEVDEIR-TEST на SEVDEIR-PROD.
Завжди перевіряйте підтримку версій сервісів у каталозі — можуть бути доступні різні варіанти інтеграції (наприклад, стандартна або розширена версія сервісу тощо).

Перегляньте сторінку Інтеграція з "Трембіта": SOAP API контракт (XML) та ознайомтеся із параметрами SOAP API-контракту для інтеграції кожного сервісу.

2.3. Приклади конфігурацій для інтеграції з реєстрами

Налаштування інтеграції з іншими реєстрами через ШБО "Трембіта" визначаються в адміністративній панелі Control Plane і зберігаються до файлу конфігурації deploy-templates/values.yaml реєстру.

Нижче подано приклади параметрів, які можна використати у Control Plane для налаштування взаємодії із сервісами СЕВ ДЕІР "Трембіта" і які потім зберігаються до файлу конфігурації.

2.3.1. Приклад YAML-конфігурації для інтеграції з сервісами ЄДР

Цей приклад демонструє, як виглядатиме конфігурація для інтеграції з Єдиним державним реєстром (ЄДР) через ШБО "Трембіта" після налаштування у Control Plane.

Ці YAML-налаштування не налаштовуються вручну. Вони є результатом конфігурації, виконаної через Control Plane. Після збереження змін у Control Plane файл deploy-templates/values.yaml оновиться автоматично та міститиме подібну конфігурацію.

Приклад інтеграції з ЄДР: deploy-templates/values.yaml

trembita:
  registries:
    edr-registry:
      user-id: 'DDM'
      protocol-version: '4.0'
      protocol: "SOAP"
      trembita-url: 'https://trembita-edr-registry-mock.example.com'
      secret-name: 'trembita-registries-secrets'
      client:
        x-road-instance: 'SEVDEIR-TEST'
        member-class: 'GOV'
        member-code: '43395033'
        subsystem-code: 'IDGOV_TEST_01'
      service:
        x-road-instance: 'SEVDEIR-TEST'
        member-class: 'GOV'
        member-code: '00015622'
        subsystem-code: '2_MJU_EDR_prod'
      # Опційний блок авторизації, залежить від сервісу
      auth:
        type: "AUTH_TOKEN"
        secret: "vault:registry-kv/registry/<registry>/trembita-registries/<trembita-registry-name>"

де:
- trembita-edr-registry-mock — назва mock-сервісу;
- example.com — назва кластера.

2.3.2. Приклад YAML-конфігурації для інтеграції з сервісами ДРАЦС

Цей приклад демонструє, як виглядатиме конфігурація для інтеграції з Державним реєстром актів цивільного стану (ДРАЦС) через ШБО "Трембіта" після налаштування у Control Plane.

Приклад інтеграції з ДРАЦС: deploy-templates/values.yaml

trembita:
  registries:
    dracs-registry:
      trembita-url: 'https://trembita-dracs-registry-mock.example.com'
      user-id: 'DDM'
      protocol-version: '4.0'
      protocol: "SOAP"
      client:
        x-road-instance: 'SEVDEIR-TEST'
        member-class: 'GOV'
        member-code: '43395033'
        subsystem-code: 'IDGOV_TEST_01'
      service:
        x-road-instance: 'SEVDEIR-TEST'
        member-class: 'GOV'
        member-code: '22956058'
        subsystem-code: 'TEST_DRAC'

де:
- trembita-dracs-registry-mock — назва mock-сервісу;
- example.com — назва кластера.

2.3.3. Приклад YAML-конфігурації для інтеграції з сервісами ЄІБДВПО

Цей приклад демонструє, як виглядатиме конфігурація для інтеграції з Єдиною інформаційною базою даних внутрішньо переміщених осіб (ЄІБДВПО) після налаштування у Control Plane.

Приклад інтеграції з ЄІБДВПО: deploy-templates/values.yaml

trembita:
  registries:
    idp-exchange-service-registry:
      trembita-url: 'https://trembita-idp-mock-server.example.com'
      user-id: DDM
      protocol-version: '4.0'
      type: "registry"
      protocol: "SOAP"
      client:
        x-road-instance: SEVDEIR-TEST
        member-class: GOV
        member-code: '43395033'
        subsystem-code: IDGOV_TEST_01
      service:
        x-road-instance: SEVDEIR-TEST
        member-class: GOV
        member-code: '37567866'
        subsystem-code: 51_IDP_prod

де:
- trembita-idp-mock-server — назва mock-сервісу;
- example.com — назва кластера.

2.3.4. Приклад YAML-конфігурації для інтеграції з довільними SOAP-сервісами "Трембіта"

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

Приклад інтеграції двох довільних SOAP-сервісів: deploy-templates/values.yaml

trembita:
  registries: (1)
    edrlike-registry:
      trembita-url: "https://trembita.example.com" (2)
      user-id: "DDM" (3)
      protocol-version: "4.0" (4)
      type: "registry" # Вказує на рівень взаємодії - реєстровий (5)
      protocol: "SOAP" (6)
      client:
        x-road-instance: "THIS-REGISTRY" (7)
        member-class: "GOV" (8)
        member-code: "0000" (9)
        subsystem-code: "Platform-registry" (10)
      service:
        x-road-instance: "THAT-REGISTRY" (11)
        member-class: "GOV" (12)
        member-code: "42" (13)
        subsystem-code: "Edrllike-system" (14)
        service-code: "Service code" (15)
        service-version: "Service version" (16)
      # опційний блок авторизації
      auth:
        type: "AUTH_TOKEN" (17)
        secret: "vault:registry-kv/registry/<registry>/trembita-registries/<trembita-registry-name>" (18)
    new-registry:
      user-id: "DDM"
      protocol-version: "4.0"
      trembita-url: "https://trembita.example.com"
      type: "registry" # Вказує на рівень взаємодії - реєстровий
      protocol: "SOAP"
      client:
        x-road-instance: "THIS-REGISTRY"
        member-class: "GOV"
        member-code: "1111"
        subsystem-code: "Platform-registry"
      service:
        x-road-instance: "THAT-REGISTRY"
        member-class: "GOV"
        member-code: "13"
        subsystem-code: "New-system"
        # Опціональний параметр
        service-code: "Service code"
        # Опціональний параметр
        service-version: "Service version"

2.3.5. Опис параметрів YAML-конфігурації

У таблиці нижче наведено опис структурних параметрів та їх відповідність елементам YAML-файлу.

Таблиця 1. Опис структурних параметрів конфігурації
Параметр	Опис
① `registries`	Назва реєстру, до якого буде сформовано запит
Заголовки, що ідентифікують користувача, який робить запит
② `trembita-url`	Адреса до ШБО
③ `user-id`	Ідентифікатор користувача, який ініціює запит
④ `protocol-version`	Версія протоколу, за яким обмінюються повідомлення ШБО. *На цей час версія протоколу 4.0*
⑤ `type`	Вказує на рівень взаємодії. При створенні нових SOAP-інтеграцій через "Трембіту", рівень взаємодії завжди реєстровий — `type: "registry"`
⑥ `protocol`	Протокол інтеграційної взаємодії. Встановлюється за замовчуванням — завжди `"SOAP"`
Заголовок (`client`), який ідентифікує учасника сервісу
⑦ `x-road-instance`	Код середовища, який ідентифікує екземпляр учасника
⑧ `member-class`	Ідентифікатор класу учасника
⑨ `member-code`	Ідентифікатор учасника
⑩ `subsystem-code`	Код підсистеми учасника, якщо сервіс надається підсистемою
Заголовок (`service`), який ідентифікує сервіс
⑪ `x-road-instance`	Код середовища сервісу
⑫ `member-class`	Ідентифікатор класу сервісу
⑬ `member-code`	Ідентифікатор сервісу
⑭ `subsystem-code`	Код підсистеми сервісу
⑮ `service-code`	(Опціональний) Код конкретного сервісу для виклику
⑯ `service-version`	(Опціональний) Номер версії сервісу
(Опціональний блок) Заголовок (`auth`), який визначає параметри авторизації
⑰ `type`	Тип автентифікації. Доступні значення: `AUTH_TOKEN`, `NO_AUTH`.
⑱ `secret`	Шлях до секрету рівня реєстру у Vault

3. Налаштування інтеграційних можливостей у Control Plane

3.1. Налаштування інтеграції з ЄДР

Увійдіть до консолі Control Plane як адміністратор реєстру.
Перейдіть до розділу Реєстри та відкрийте необхідний.
Знайдіть секцію Налаштування взаємодії з реєстрами через Трембіту та сконфігуруйте необхідну інтеграцію із реєстром ЄДР.
Налаштуйте ШБО "Трембіта" для реєстру ЄДР.

Адреса ШБО "Трембіта" має бути абсолютною та починатися з http:// або https://.
Налаштуйте клієнт "Трембіти", тобто Вашу зареєстровану у "Трембіті" систему, яка звертатиметься до сервісів ЄДР.

Налаштуйте сервіс для інтеграції.

Під "сервісом" тут мається на увазі рівень реєстру ЄДР. Безпосередньо ендпоінти (ресурси), до яких надходитиме запит для отримання даних, налаштовані на рівні інтеграційних конекторів до ЄДР, які ви можете використовувати у бізнес-процесах.

Службова назва реєстру, протокол інтеграції й тип автентифікації встановлюються за замовчуванням та не можуть бути змінені з міркувань безпеки.
Наразі підтримується лише SOAP-протокол інтеграції.
Тип автентифікації — AUTH_TOKEN^[1].
Отримайте токен авторизації від представників ЄДР та вкажіть його тут. Він може виглядати, наприклад, ось так:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6Ik
```

Натисніть Підтвердити, щоб зберегти налаштування.

В результаті формується запит на внесення змін до конфігурації реєстру.

Відкрийте розділ Запити на оновлення та перегляньте сформований запит, натиснувши іконку перегляду — 👁.

Запропоновані зміни автоматично підтверджуються системою та зберігаються до конфігурації реєстру у файлі deploy-templates/values.yaml.

cp ext sys 4

У новому вікні ви можете переглянути, які саме параметри додано до конфігурації.

3.2. Налаштування інтеграції з ДРАЦС

Увійдіть до консолі Control Plane як адміністратор реєстру.
Перейдіть до розділу Реєстри та відкрийте необхідний.
Знайдіть секцію Налаштування взаємодії з реєстрами через Трембіту та сконфігуруйте необхідну інтеграцію із реєстром ДРАЦС.
Налаштуйте ШБО "Трембіта" для реєстру ДРАЦС.

Адреса ШБО "Трембіта" має бути абсолютною та починатися з http:// або https://.
Налаштуйте клієнт "Трембіти", тобто Вашу зареєстровану у "Трембіті" систему, яка звертатиметься до сервісів ДРАЦС.

Налаштуйте сервіс для інтеграції.

Під "сервісом" тут мається на увазі рівень реєстру ДРАЦС. Безпосередньо ендпоінти (ресурси), до яких надходитиме запит для отримання даних, налаштовані на рівні інтеграційних конекторів до ДРАЦС, які ви можете використовувати у бізнес-процесах.

Службова назва реєстру, протокол інтеграції й тип автентифікації встановлюються за замовчуванням та не можуть бути змінені з міркувань безпеки.
Наразі підтримується лише SOAP-протокол інтеграції.
Тип автентифікації — NO_AUTH^[2].

Натисніть Підтвердити, щоб зберегти налаштування.

В результаті формується запит на внесення змін до конфігурації реєстру.

Відкрийте розділ Запити на оновлення та перегляньте сформований запит, натиснувши іконку перегляду — 👁.

Запропоновані зміни автоматично підтверджуються системою та зберігаються до конфігурації реєстру у файлі deploy-templates/values.yaml.

cp ext sys 4

У новому вікні ви можете переглянути, які саме параметри додано до конфігурації.

3.3. Налаштування інтеграції з ЄІБДВПО

Увійдіть до консолі Control Plane як адміністратор реєстру.
Перейдіть до розділу Реєстри та відкрийте необхідний.
Знайдіть секцію Налаштування взаємодії з реєстрами через Трембіту та сконфігуруйте необхідну інтеграцію із системою ЄІБДВПО.
Налаштуйте ШБО "Трембіта" для ЄІБДВПО.

Адреса ШБО "Трембіта" має бути абсолютною та починатися з http:// або https://.
Налаштуйте клієнт "Трембіти", тобто Вашу систему, яка звертатиметься до сервісів ЄІБДВПО.

Налаштуйте сервіс для інтеграції.

Під "сервісом" тут мається на увазі рівень ЄІБДВПО. Безпосередньо ендпоінти (ресурси), до яких надходитиме запит для отримання даних, налаштовані на рівні інтеграційних конекторів до ЄДР, які ви можете використовувати у бізнес-процесах.

Службова назва реєстру, протокол інтеграції й тип автентифікації встановлюються за замовчуванням та не можуть бути змінені з міркувань безпеки.
Наразі підтримується лише SOAP-протокол інтеграції.
Тип автентифікації — NO_AUTH^[2].

Натисніть Підтвердити, щоб зберегти налаштування.

В результаті формується запит на внесення змін до конфігурації реєстру.

Відкрийте розділ Запити на оновлення та перегляньте сформований запит, натиснувши іконку перегляду — 👁.

Система автоматично підтверджує запропоновані зміни та зберігає їх до файлу конфігурації реєстру deploy-templates/values.yaml.

cp ext sys 4

У новому вікні ви можете переглянути, які саме параметри додано до конфігурації.

3.4. Інтеграція з довільними SOAP-сервісами "Трембіта"

Механізм налаштування інтеграційної взаємодії із сервісами-учасниками СЕВ ДЕІР "Трембіта" є однаковим для усіх систем (детальніше див. у попередніх розділах цього документа). Єдиними відмінностями є такі:

Ви можете додавати нові інтеграційні взаємодії на рівні реєстру.
Ви можете видаляти створені інтеграційні взаємодії для поточного реєстру.
При додаванні нової взаємодії, у налаштуваннях реєстру deploy-templates/values.yaml додається атрибут type: "registry", який вказує на реєстровий рівень взаємодії.
Взаємодії, які розгортаються автоматично разом із реєстром (ЄДР, ДРАЦС та ЄІБДВПО), можливо лише редагувати й неможливо видалити. Для таких інтеграцій рівень взаємодії завжди системний.

Зображення 1. Загальний вигляд блоку інтеграційних налаштувань у вебінтерфейсі Control Plane

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

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

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

4. Перегляд налаштувань інтеграції та розгортання змін

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

Ви можете відредагувати налаштування, натиснувши відповідну іконку 🖉.
У результаті внесених змін запускається Jenkins-пайплайн MASTER-Build-<registry-name>, де <registry-name> — назва реєстру. Він застосовує параметри заданої конфігурації.
Зачекайте, доки виконається збірка коду. Це може зайняти до 15 хвилин.

Ви можете перевірити поточний статус та результат виконання за посиланням CI на інтерфейсі.

Зображення 4. Перехід до Jenkins

Зображення 5. Пайплайн збірки реєстру MASTER-Build

Зображення 6. Процесу проходження пайплайну збірки реєстру
При успішному виконанні збірки, задана конфігурація буде застосована до реєстру.

1. AUTH_TOKEN (скорочення від «токен автентифікації») — це фрагмент даних, який використовується для автентифікації користувача або системи для доступу до певного сервісу чи ресурсу. Токени автентифікації зазвичай використовують у вебдодатках, API та інших мережевих системах для забезпечення безпечного та ефективного доступу до ресурсів. Токени можуть приймати різні форми, наприклад випадкові рядки символів, зашифровані дані або навіть вебтокени JSON (JWT), які містять інформацію про користувача та термін дії.

2. NO_AUTH означає метод/тип аутентифікації, який не потребує жодних облікових даних або токенів аутентифікації для доступу до певного ресурсу або сервісу. Це означає, що будь-хто може отримати доступ до ресурсу або сервісу без будь-яких обмежень або перевірки його ідентичності.