Розгортання демо-реєстру із референтними прикладами

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

Ви маєте змогу розгорнути демо-реєстр на Платформі з референтними прикладами моделювання регламенту. Структура такого регламенту аналогічна структурі типового регламенту, який використовується для будь-якого реєстру, розгорнутого на Платформі.

Регламент демо-реєстру включає референтні приклади, які позначені префіксом reference-, та приклади для тестування, позначені префіксом feature-. Це можуть бути зразки .bpmn-схем бізнес-процесів, .json-форм для внесення даних до процесів, а також .xml-схем для розгортання моделі даних реєстру тощо.

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

1. Розгортання демо-реєстру та регламенту

Щоб розгорнути демо реєстр та скопіювати регламент із готовими зразками, виконайте наступні кроки:

  1. Створіть новий реєстр demo відповідно до інструкції на сторінці Розгортання екземпляра реєстру.

  2. Увійдіть до консолі OpenShift > Home > Projects та знайдіть проєкт control-plane.

    Відкрийте розділ Networking > Routes та перейдіть за посиланням до компонента control-plane-console.

    cp deploy consent data 1

  3. Відкрийте консоль Control Plane > Дашборд та перейдіть за посиланням до центрального компонента Gerrit.

    control plane overview

  4. Перейдіть до налаштувань облікового запису Gerrit та знайдіть розділ HTTP Credentials.

    cp deploy consent data 2

  5. Згенеруйте новий HTTP-пароль та скопіюйте його до блокнота.

    cp deploy consent data 2 1

    Цей HTTP-пароль надалі потрібен для автентифікації при клонуванні Gerrit-репозиторію consent-data.

  6. Відкрийте вкладку Browse > Repositories та у полі Filter знайдіть репозиторій consent-data.

    cp deploy consent data 3

  7. Клонуйте репозиторій consent-data на локальну машину. Зробити це можна наступним чином:

    • Оберіть вкладку Anonymous HTTP (за замовчуванням) та скопіюйте команду Clone with commit-msg hook.

      cp deploy consent data 4

      Обов’язково клонуйте репозиторій із опцією commit-msg hook.

      Один з ключових елементів Gerrit — це використання "hooks" (або "гуків"). Hooks — це скрипти, які виконуються перед або після певних подій у Git, наприклад, перед git commit або git push.

      Команда Clone with commit-msg hook у Gerrit дозволяє клонувати репозиторій і автоматично додає спеціальний commit-msg hook до локального репозиторію. Цей hook автоматично генерує унікальний Change-Id для кожного нового коміту. Change-Id використовується Gerrit для слідкування за різними версіями зміни.

    • Відкрийте Git Bash та перейдіть до бажаної директорії, куди потрібно скопіювати consent-data:

      Перехід до цільової директорії
      cd <шлях/до/вашої/локальної/директорії>

    • Вставте скопійовану команду Clone with commit-msg hook та натисніть Enter.

      cp deploy consent data 5

      Зачекайте, доки репозиторій буде остаточно клоновано.

      cp deploy consent data 6

  8. Увійдіть до консолі OpenShift > Home > Projects та знайдіть проєкт зі створеним демо-реєстром demo.

    Відкрийте розділ Networking > Routes та перейдіть за посиланням до компонента Gerrit реєстру.

    cp deploy consent data 7

  9. Перейдіть до налаштувань облікового запису Gerrit та знайдіть розділ HTTP Credentials.

    cp deploy consent data 2

  10. Згенеруйте новий HTTP-пароль та скопіюйте його до блокнота.

    cp deploy consent data 2 1

    Цей HTTP-пароль надалі потрібен для автентифікації при клонуванні та подальшій взаємодії із Gerrit-репозиторієм, що містить регламент registry-regulations.

  11. Відкрийте вкладку Browse > Repositories та у полі Filter знайдіть репозиторій registry-regulations.

    Після розгортання реєстру, Gerrit міститиме порожній регламент registry-regulations. Його необхідно наповнити.

  12. Клонуйте репозиторій registry-regulations на локальну машину. Зробити це можна наступним чином:

    • Оберіть вкладку Anonymous HTTP (за замовчуванням) та скопіюйте команду Clone with commit-msg hook.

      Обов’язково клонуйте репозиторій із опцією commit-msg hook.

      Один з ключових елементів Gerrit — це використання "hooks" (або "гуків"). Hooks — це скрипти, які виконуються перед або після певних подій у Git, наприклад, перед git commit або git push.

      Команда Clone with commit-msg hook у Gerrit дозволяє клонувати репозиторій і автоматично додає спеціальний commit-msg hook до локального репозиторію. Цей hook автоматично генерує унікальний Change-Id для кожного нового коміту. Change-Id використовується Gerrit для слідкування за різними версіями зміни.

    • Відкрийте Git Bash та перейдіть до бажаної директорії, куди потрібно скопіювати consent-data:

      Перехід до цільової директорії
      cd <шлях/до/вашої/локальної/директорії>

    • Вставте скопійовану команду Clone with commit-msg hook та натисніть Enter.

      Зачекайте, доки репозиторій буде остаточно клоновано.

  13. На локальній машині скопіюйте вміст репозиторію consent-data та вставте його із заміною до registry-regulations.

    Обов’язково перенесіть вміст репозиторію consent-data без системної теки .git.
    Якщо демо-реєстр не передбачає налаштувань підключення до "Дії", то для успішного розгортання регламенту необхідно видалити теку diia із репозиторію registry-regulations, яка знаходиться за шляхом: ./notifications/diia.

  14. Опублікуйте зміни у регламенті демо-реєстру. Після публікації, сутності регламенту, як-от модель даних, бізнес-процеси, форми тощо стануть доступними для використання у Кабінетах користувачів, зокрема у Кабінеті адміністратора регламентів (admin-portal), посадової особи (officer-portal) та отримувача послуг (citizen-portal).

    На цьому кроці вам необхідно наповнити регламент registry-regulations онлайн-репозиторію Gerrit реєстру.

    • Підготуйте commit зі змінами до registry-regulations та відправте його до репозиторію. Для цього виконайте по черзі наступні команди у Git Bash-терміналі:

      git add --all

      Ця команда додає всі нові, змінені або видалені файли в поточному каталозі та його підкаталогах до індексу (stage) для наступного коміту. Тобто, вона готує всі зміни у проєкті до виконання команди git commit.

      git commit -m "added demo registry data"

      Команда git commit створює новий коміт зі змінами, які були попередньо додані до індексу за допомогою команди git add. Опція -m дозволяє додати коротке повідомлення до коміту, яке описує виконані зміни. У нашому випадку повідомлення буде таке: "added demo registry data".

      cp deploy consent data 8

      git push origin HEAD:refs/for/master

      Команда git push відправляє зміни на віддалений git-сервер. У нашому випадку origin — це віддалений репозиторій, до якого ви надсилаєте зміни. HEAD:refs/for/master означає, що ви надсилаєте зміни з поточної гілки до віддаленої для перевірки коду перед злиттям із гілкою master. Це специфічний для Gerrit спосіб відправки змін для перевірки.

      cp deploy consent data 9

  15. Після відправки змін, перейдіть за посиланням до Gerrit, яке з’явиться у терміналі.

    Шлях до реєстрового Gerrit буде таким:

    https://admin-tools-<openshift-project-name>.<dns-wildcard>/gerrit

    • <openshift-project-name> — назва вашого реєстру (тут — demo).

    • <dns-wildcard> — назва середовища в OpenShift, в якому розгорнуто реєстр.

  16. Зачекайте, доки виконається системний пайплайн перевірки коду — MASTER-Code-review-registry-regulations. Перевірити прогрес можна за посиланням внизу сторінки у Gerrit.
    У результаті успішної перевірки, ваш запит на внесення змін отримає статус VERIFIED +1.

  17. Підтвердьте внесення змін натисканням кнопки CODE-REVIEW+2 як модератор.

    cp deploy consent data 10

  18. Застосуйте зміни до master-гілки репозиторію з регламентом натисканням кнопки SUBMIT, тобто виконайте git merge змін.

    У результаті запускається автоматична публікація регламенту пайплайном MASTER-Build-registry-regulations. Перевірити прогрес розгортання можна за посиланням внизу сторінки у Gerrit.

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

  19. Перейдіть до Кабінету адміністратора регламентів та перевірте наявність бізнес-процесів, UI-форм тощо. Службова назва референтних прикладів міститиме префікс reference-.

    Адміністративний портал доступний за посиланням: https://admin-tools-<registry-name>.<dns-wildcard>.

    cp deploy consent data 11

    Ці ж референтні бізнес-процеси стануть доступними у вигляді послуг у Кабінетах посадової особи та отримувача послуг.

2. Опис вмісту регламенту демо-реєстру

Вміст регламенту демо-реєстру подібний до типового регламенту будь-якого реєстру, що розгорнуто на Платформі (див. детальніше — Структура регламенту реєстру).

Регламент демо-реєстру містить референтні приклади, відмічені префіксом reference- та приклади для тестування, відмічені префіксом feature-. Це можуть бути .bpmn-схеми бізнес-процесів, .json-форми внесення даних до процесу, .xml-схеми розгортання моделі даних реєстру тощо.

cp deploy consent data 6
Зображення 1. Вміст регламенту демо-реєстру

Для того, щоб посадова особа в особистому Кабінеті змогла отримати доступ до відповідного референтного процесу, необхідно створити користувача у реалмі <назва-реєстру>-officer для відповідного реєстру в сервісі Keycloak та надати такому користувачеві відповідні права доступу.

Права доступу можуть відрізнятися, згідно з логікою вашого реєстру. Це можуть бути як загальні права для посадових осіб, зокрема роль -officer, так і специфічні, як-от посадова особа, відповідальна за управління ієрархічними структурами — hierarchy-registry-manager.

cp deploy consent data 12
Детальніше про створення користувачів та надання їм прав доступу див. у розділі Внесення користувачів до системи.
cp deploy consent data 13

Список ролей, що передбачає регламент демо-реєстру, доступний у файлах roles/*.yml. Ролі посадової особи знаходяться у файлі roles/officer.yml, ролі отримувачів послуг — у файлі roles/citizen.yml.

Для перегляду процесів, які належать до feature-прикладів, у Keycloak передбачена роль op-regression. У Кабінеті стануть доступними процеси для тестування функціональності, зокрема для перевірки JUEL-функцій, делегатів тощо.

Для перегляду процесів, які належать до reference-прикладів, у Keycloak передбачена роль op-reference.

Ролі регламенту демо-реєстру
roles/officer.yml
roles:
#  feature roles
  - name: officer
    description: Officer role
  - name: task-dispatcher
    description: Task orchestrator
  - name: officer-first-rank
    description: Посадова особа першого рангу
  - name: officer-second-rank
    description: Посадова особа другого рангу
  - name: op-regression
    description: Available all business processes
  - name: op-layouts
    description: Available layouts business processes
  - name: op-sorting
    description: Available sorting business processes
  - name: officer-grant
    description: Role with granted analytic view
  - name: officer-revoke
    description: Role without revoked analytic view
  - name: officer-grant-all
    description: Role with all analytic views
  - name: officer-revoke-all
    description: Role without all analytic views
  - name: citizen
    description: Role for citizen on officer portal for RBAC
  - name: death-officer
    description: Role for RBAC validation
  - name: inn-officer
    description: Role for RBAC validation
  - name: birth-officer
    description: Role for RBAC validation
  - name: personnel-officer-admin
    description: Personnel officer admin role
  - name: officer-moderator
    description: Moderator of manual registration
  - name: hierarchy-registry-user
    description: Користувач реєстру з управлінням ієрархією
  - name: hierarchy-registry-manager
    description: Керівник реєстру з управлінням ієрархією
  - name: head-officer
    description: Head officer
  - name: op-reference
    description: Available all reference business processes

Орієнтуватися, яка роль матиме доступ до тих чи інших процесів, можна за допомогою авторизаційних файлів регламенту bp-auth/*.yml.
Доступ для посадових осіб визначається у файлі bp-auth/officer.yml, для отримувачів послуг — у файлі bp-auth/citizen.yml. Авторизація для зовнішніх систем встановлюється у файлі bp-auth/external-system.yml.

Доступ до бізнес-процесів демо-реєстру для відповідних ролей
bp-auth/officer.yml
authorization:
  realm: "officer"
  ##### Доступ до feature-процесу #####
  process_definitions:
  - process_definition_id: "feature-systemErrorAfterUserTask"
    process_name: "AUTO test process description"
    process_description: "AUTO test process description"
    roles:
      - 'op-regression'
  ##### Доступ до референтного процесу #####
  - process_definition_id: 'reference-upload-update-digital-document'
    process_name: 'Завантаження файлу та його редагування'
    process_description: 'Завантаження файлу та його редагування'
    roles:
      - 'op-reference'
  ##### Доступ до процесу для управління ієрархічною структурою #####
  - process_definition_id: 'reference-hierarchy-management'
    process_name: 'Управління ієрархічною структурою'
    process_description: 'Управління ієрархічною структурою'
    roles:
      - 'hierarchy-registry-manager'

3. Референтні приклади

Опис референтних прикладів моделювання регламенту доступний на сторінках розділу Найкращі практики.

4. Корисні посилання

© 2023 Платформа Реєстрів.