Налаштування регламенту для надання доступу до даних через SOAP та REST API

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

Якщо ваш реєстр є власником даних, і ви хочете виставляти інтеграційні API-точки, отримувати запити та віддавати дані іншим реєстрам або системам, виконайте наступні налаштування регламенту:

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

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

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

Для REST-взаємодії необхідно також надати доступ до реєстру в адміністративній панелі Control Plane. Детальніше про це — див. на сторінці Налаштування доступу до реєстрів.

1. Налаштування авторизації для доступу до бізнес-процесів реєстру

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

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

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

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

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

    Для цього перейдіть до файлу 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. Налаштуйте файл bp-trembita/external-system.yml у регламенті:

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

      Без визначення 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 — умовне ім’я учня.

      Приклад, як прийняти змінні у цільовому процесі, див. у розділі нижче: Моделювання бізнес-процесу для виклику у цільовому реєстрі.

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

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

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

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

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

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

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

accept map params bp
Зображення 1. Приймання стартових змінних процесу у цільовому реєстрі
Де можна знайти приклад референтного бізнес-процесу?

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

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

Приклад BPMN-схеми процесу буде доступний у регламенті демо-реєстру за пошуком по ключовим словам — create-school-auto-sign. Назви форм ви можете знайти всередині відповідних користувацьких задач (User Task) бізнес-процесу у полі Form key.