Інтеграційна REST-взаємодія реєстрів з іншими реєстрами на Платформі та зовнішніми системами

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

Платформа підтримує інтеграційну взаємодію реєстрів за допомогою REST API-інтерфейсів. Така взаємодія можлива завдяки Підсистемі міжреєстрових інтеграцій.

Функціональність забезпечує інтероперабельність Платформи з можливістю надавати доступи до бізнес-процесів та API читання даних, а також дозволяє читати дані та викликати бізнес-процеси в інших реєстрах.

За замовчуванням на Платформі використовується інтеграційна взаємодія між реєстрами через шлюз безпечного обміну (ШБО) «Трембіта». Така взаємодія здійснюється за протоколом SOAP та вимагає розв’язання підготовчих питань у юридичній площині (див. детальніше — Реєстрація підсистеми нового реєстру на ШБО "Трембіта" Платформи).

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

Основні функції підсистеми міжреєстрових інтеграцій:

  • Надання API для виклику бізнес-процесів реєстру сторонніми для реєстру системами.

  • Надання доступу іншим реєстрам або системам до окремих запитів читання Підсистеми управління даними реєстру.

  • Маршрутизація запитів до зовнішніх реєстрів, до яких було надано доступ.

2. Схеми міжреєстрової REST-взаємодії

Виділяють 2 схеми інтеграційної взаємодії реєстрів, що розгорнуті на Платформі:

2.1. REST-взаємодія реєстрів на Платформі із зовнішньою інформаційною системою

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

int reg ext system
Зображення 1. Взаємодія реєстрів на Платформі зі сторонньою інформаційною системою

  1. Вихідна взаємодія можлива завдяки інтеграційному REST-конектору Connect to external system. Конектор має REST-інтерфейс для виклику зовнішніх ендпоінтів. Його можна використовувати при моделюванні бізнес-процесів у регламенті певного реєстру. Для автентифікації необхідно використовувати OpenShift (Kubernetes) секрети.

  2. Вхідна взаємодія можлива завдяки імплементованим реєстровим сервісам external-system-api-kong-proxy та registry-rest-api-ext.

    Зовнішня система має спочатку отримати пароль доступу від адміністратора реєстру. З цим паролем — отримати токен доступу у сервісі Keycloak. З цим токеном надалі можливо авторизуватися у сервісах та отримувати доступ до ресурсів.

    • Сервіс external-system-api-kong-proxy розгортається автоматично, разом з реєстром та має REST-інтерфейс, що дозволяє ініціювати бізнес-процеси у реєстрах на Платформі та отримувати з них дані. Сервіс використовує точку входу (ендпоінт) /startBp для старту бізнес-процесу.

    • Сервіс registry-rest-api-ext розгортається автоматично, після створення моделі даних у регламенті реєстру. Він дозволяє звертатися до API-представлень операційної бази даних реєстру.

2.2. REST-взаємодія реєстрів в межах одного екземпляра Платформи

При інтеграційній взаємодії реєстрів в межах Платформи завжди є реєстр-клієнт (споживач/запитувач даних) та цільовий реєстр (власник даних).

internal registries platform
Зображення 2. REST-взаємодія реєстрів в межах одного екземпляра Платформи
Реєстр-клієнт може запитати дані у цільового реєстру 2-ма шляхами:
Реєстр-клієнт має спочатку отримати токен доступу іншого реєстру у сервісі Keycloak. З цим токеном надалі можливо авторизуватися у сервісах.

  1. Через сервіс bp-webservice-gateway — розгортається автоматично, разом з реєстром та має REST-інтерфейс, що дозволяє ініціювати бізнес-процеси у реєстрах на Платформі та отримувати з них дані. Сервіс використовує точку входу (ендпоінт) /startBp для старту бізнес-процесу.

    • Ініціювати бізнес-процеси в іншому (цільовому) реєстрі можливо за допомогою спеціального розширення-делегата — Start business process in another registry. Він призначений лише для інтеграції реєстрів у межах Платформи.

    • Отримати дані з операційної БД реєстру іншого (цільового) реєстру в рамках виконання бізнес-процесів можливо за допомогою спеціального розширення-делегата — Search for entities from another registry data factory. Він призначений лише для інтеграції реєстрів у межах Платформи.

  2. Через сервіс registry-rest-api-ext — розгортається автоматично, після створення моделі даних у регламенті реєстру. Він дозволяє звертатися до API-представлень операційної бази даних реєстру з форм Кабінету користувача (за критеріями пошуку).

3. Налаштування взаємодії між реєстрами

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

3.1. Налаштування цільового реєстру (власника даних)

Налаштуйте взаємодію з іншими реєстрами для цільового реєстру (власника даних):

  1. Виконайте налаштування на рівні регламенту реєстру (доступ для виклику бізнес-процесу).

  2. Змоделюйте бізнес-процес, що викликатиметься іншим реєстром.

  3. Створіть модель даних (надайте доступ на читання даних реєстру через API-представлення)

  4. Надайте доступ до реєстру для іншого реєстру на Платформі, або зовнішньої системи через адміністративну панель Control Plane.

3.1.1. Налаштування регламенту цільового реєстру (власника даних)

Адміністратор реєстру має виконати налаштування на рівні регламенту.

Виконайте налаштування у 2-х конфігураційних файлах:

  • bp-auth/external-system.yml — відповідає за доступ до бізнес-процесів;

  • trembita/external-system.yml — відповідає за обмін даними для ініціювання/старту бізнес-процесу.

  1. Налаштуйте доступ до бізнес-процесів у цільовому реєстрі, які братимуть участь в обміні даними.

    Для цього перейдіть до файлу bp-auth/external-system.yml у регламенті та визначте конфігурацію:

    Приклад 1. Конфігураційний файл для надання доступу до бізнес-процесів у цільовому реєстрі
    authorization:
  realm: 'external-system'
  process_definitions:
    - process_definition_id: 'my-process-id'
      process_name: 'Назва вашого бізнес-процесу'
      process_description: 'Опис вашого бізнес-процесу'
      roles:
        - 'trembita-invoker'

    У цьому прикладі ми вказуємо, що доступ необхідно надати до бізнес-процесу my-process-id для ролі trembita-invoker з Keycloak-реалму -external-system. Параметри process_name та process_description є опціональними, і не впливають на процес авторизації

    Клієнт trembita-invoker з однойменною роллю створюється автоматично оператором Keycloak в реалмі -external-system при розгортанні реєстру. Облікові дані цього клієнта необхідно використовувати для всіх зовнішніх систем, яким потрібен доступ до реєстру на Платформі.

  2. Сконфігуруйте файл trembita/external-system.yml у регламенті:

    • Налаштуйте змінні старту бізнес-процесу. Для цього вкажіть, які параметри очікуватиме бізнес-процес у блоці start_vars.

      Без цього бізнес-процес не запрацює.

    • Налаштуйте змінні повернення. Для цього вкажіть, які параметри повертатиме бізнес-процес у блоці return_vars.

      Приклад 2. Налаштування API-контракту для бізнес-процесу
      trembita:
  process_definitions:
    - process_definition_id: 'my-process-id'
      start_vars:
        - eduname
      return_vars:
        - id
        - name

      У цьому прикладі ми вказуємо, що для старту бізнес-процесу my-process-id у цільовому реєстрі, необхідно передати стартові змінні. Без них бізнес-процес не буде ініційований. Тут ми передаємо параметр eduname — умовне ім’я учня.

      Стартові параметри (змінні) передаються як Map вхідних параметрів (Input Parameters), тобто як ключ-значення при налаштуванні делегата для старту бізнес-процесу.

      pass map params bp
      Зображення 3. Формування стартових змінних процесу у реєстрі-клієнті для передачі до цільового реєстру
      accept map params bp
      Зображення 4. Приймання стартових змінних процесу у цільовому реєстрі

      Також налаштуйте змінні повернення. Тут ми налаштовуємо, що бізнес-процес повертатиме параметри id та name. Вони будуть записані до змінної результату в Output Parameters цієї ж сервісної задачі з делегатом.

3.1.2. Моделювання бізнес-процесу для виклику у цільовому реєстрі

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

Скористайтеся прикладом такого бізнес-процесу у вкладенні:

3.1.3. Налаштування моделі даних

Створіть модель даних реєстру. Додайте нові критерії пошуку, що надаватимуть доступ на читання даних БД через API-представлення реєстру.

Детальніше про налаштування моделі даних ви можете переглянути на сторінці Налаштування атрибутів доступу до REST API-представлень реєстру.

3.1.4. Надання доступу до реєстру в Control Plane

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

Деталі дивіться на сторінці Налаштування доступу до реєстрів.

3.2. Налаштування реєстру-клієнта (споживача даних)

Налаштуйте взаємодію з іншими реєстрами для реєстру-споживача даних. Для цього:

  1. Змоделюйте бізнес-процес з можливістю виклику зовнішнього реєстру.

    Скористайтеся прикладом такого бізнес-процесу у вкладенні: BPMN-create-school-auto.bpmn

  2. В рамках бізнес-процесу використовуйте типові інтеграційні розширення для взаємодії з іншими реєстрами на Платформі:

    • старту бізнес-процесів в іншому реєстрі на Платформі — для цього використовуйте типове інтеграційне розширення-конектор Start business process in another registry;

    • отримання даних з операційної БД іншого реєстру на Платформі — для цього використовуйте типове інтеграційне розширення-конектор Search for entities from another registry data factory.

      Опис та налаштування делегатів ви можете знайти на сторінці Типові розширення для інтеграції із бізнес-процесами інших реєстрів на Платформі.

  3. Змоделюйте UI-форму для читання даних з операційної БД реєстру за критеріями пошуку (search condition). Це дозволить звертатися до БД іншого реєстру з користувацької форми. Для цього:

    • Перейдіть до Кабінету адміністратора регламентів > Відкрийте розділ UI-форми > Створіть форму введення даних > Відкрийте Конструктор форм.

    • У компоненті Select перейдіть на вкладку Data > У полі Data Source URL введіть шлях до ресурсу у фабриці даних іншого реєстру:

      Приклад 3. Поле Data Source URL на UI-формі
      /api/integration/data-factory/test-registry/resource-name
      Параметр/Шлях Опис

      /api/integration/data-factory

      Кореневий шлях (не змінюється).

      test-registry

      Службова назва цільового реєстру, вказана у Control Plane.

      resource-name

      Назва ресурсу/ендпоінту, до якого звертатися для отримання даних. Наприклад, /edu-type.
      create sc data source url
      Зображення 5. Запит до БД іншого реєстру за критерієм пошуку з UI-форми користувача

3.3. Отримання токена авторизації зовнішніми системами

Щоб отримати дозвіл на звернення до ресурсів реєстру, зовнішня система має отримати спеціальний токен доступу — JWT-токен. Він призначений для подальшої авторизації зовнішніх систем при взаємодії з реєстрами, що розгорнуті в межах Платформи.

Детальніше дивіться на сторінці Виклик реєстру зовнішньою системою: Отримання JWT-токена у Keycloak.

3.4. Вихідна інтеграція із зовнішніми системами

Якщо необхідно інтегруватися із зовнішнім сервісом, або системою, що знаходиться поза кластером Платформи, використовуйте спеціальний REST-конектор — Connect to external system.

Детальніше дивіться на сторінці Інтеграція із зовнішніми сервісами за допомогою REST-конектора.

3.5. Пов’язані сторінки

Опис функціональності охоплює пов’язані сторінки з документацією. Вони подані списком у цьому розділі для зручності.