Призначення ролей та запуск бізнес-процесу за прямим посиланням

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

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

Пряме посилання на бізнес-процес — посилання для запуску бізнес-процесу через GET-запит та можливості передачі даних стартової форми у посиланні.
Основні положення:

  • Використання прямих посилань: прямі посилання можна сформувати для будь-якого доступного користувачу бізнес-процесу.

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

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

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

  • Гнучкість використання: прямі посилання та процеси онбордингу або самореєстрації можуть застосовуватися як окремо, так і у поєднанні в рамках реєстру, відповідно до встановлених обмежень.
Особливості моделювання процесу:

Моделювальники регламенту мають змогу ефективно передавати ключову інформацію через спеціалізований роут у посиланні для входу в різні Кабінети. Це включає передачу processKey, який являє собою назву цільового бізнес-процесу, а також додаткових параметрів (query parameters) в форматі Base64. Ці параметри можуть включати призначену роль користувача серед інших важливих деталей. Попри те, що ці параметри не є обов’язковими, вони забезпечують додаткову гнучкість, оскільки автоматично інтегруються на стартову форму відповідного бізнес-процесу, полегшуючи навігацію та персоналізацію взаємодії користувачів з системою.

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

2. Референтний приклад бізнес-процесу

Де можна знайти приклад бізнес-процесу?

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

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

Приклад BPMN-схеми процесу буде доступний у регламенті демо-реєстру за пошуком по ключовим словам — reference-assign-role-officer та reference-assign-role.

Назви форм ви можете знайти всередині відповідних користувацьких задач (User Task) бізнес-процесів у полі Form key:

  • reference-assign-role-start-form.json

  • reference-role-assigned-info-form.json

  • reference-role-not-assigned-error-info-form.json

У Кабінеті користувача бізнес-процес буде доступний у розділі Доступні послуги > 📂 Бізнес-процеси по призначенню ролей через спеціальні посилання.

assign role via url 06
assign role via url 1
Зображення 1. Загальний вигляд референтного бізнес-процесу

2.1. Моделювання стартової події та форми (Start Event)

Налаштування бізнес-процесу:

Для початку, змоделюйте стартову подію (Start Event) вашого бізнес-процесу. Під час розробки бізнес-процесу, на який буде сформовано унікальне посилання, важливо включити використання стартової форми.

  1. У полі Form key введіть службову назву форми — reference-assign-role-start-form.

  2. У полі Initiator вкажіть initiator. Це забезпечить правильну ініціацію процесу.

assign role via url 2

Налаштування UI-форми:

Тепер перейдемо до моделювання стартової форми. Це важливо, адже саме тут будуть передзаповнені певні параметри, такі як роль, що призначається користувачу.

У налаштуваннях компонента Text Field, на вкладці API, заповніть поле Property Name значенням role. Цей параметр пізніше буде використано для створення JSON із параметрами "ключ-дані", де ключ відповідає назві компонента, що потрібно передзаповнити, а дані — це відповідне значення для передзаповнення.

assign role via url 01

assign role via url 02

2.2. Сервісна задача для отримання системних та реєстрових ролей

Далі, потрібно отримати визначені ролі користувача із Keycloak. У цьому процесі використовується сервісна задача із застосуванням типового розширення делегата Get keycloak roles from user.

Налаштування сервісної задачі:

  • Вкажіть назву задачі. Наприклад, Отримання системних і реєстрових ролей користувача.

Налаштування делегата:

  1. У полі Realm з випадного списку оберіть Officer для надавачів послуг або Citizen для отримувачів послуг.

  2. Username: встановіть значення ${initiator}, таким чином вказавши ініціатора процесу.

  3. Role Type: виберіть тип ролей: REGISTRY ROLES, PLATFORM ROLES, або ALL ROLES.

    Role Type визначає, які саме ролі користувача повертати — чи то всі (системні та реєстрові), лише системні, чи лише реєстрові.

  4. Вкажіть змінну процесу, куди буде поміщено відповідь (rolesResponse), яка буде тимчасовою (transient).

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

assign role via url 3

2.3. XOR-шлюз та потоки процесу

Використовуючи XOR-шлюз, ви зможете ефективно змоделювати розгалуження шляху токена. XOR-шлюз використовується для визначення того, чи вже призначена певна роль користувачу на основі даних з URL.

Умови розгалуження:

  1. Альтернативна гілка (роль вже призначена):

    • Умова виконується, коли користувач вже має призначену роль.

    • Condition > Type: Expression.

    • Condition Expression:

      ${rolesResponse.value.contains(submission('StartFormData').formData.prop('role').stringValue())}

    • У цьому випадку процес завершується, оскільки роль вже наявна у користувача.

    assign role via url 4

  2. Основна гілка (роль ще не призначена):

    • Умова задовольняється, коли роль ще не призначена користувачу.

    • Condition > Type: Expression.

    • Condition Expression:

      ${!rolesResponse.value.contains(submission('StartFormData').formData.prop('role').stringValue())}

    • Якщо роль не призначена, потік рухається до наступної скрипт-задачі, де відбувається підготовка до призначення ролей користувачу.

    assign role via url 5

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

2.4. Скрипт для підготування ролей користувача

  1. Створіть Script Task.

  2. У полі Name вкажіть назву задачі.

  3. Натисніть кнопку Open script editor та внесіть скрипт.

    assign role via url 6

    Скрипт для підготування ролей користувача
    def rolesList = []
rolesResponse.each {
    rolesList << it
}
def roleFromStartForm = submission('StartFormData').formData.prop('role').stringValue()
rolesList << roleFromStartForm

rolesList.each {
    println "RolesToAdd: " + it
}

set_transient_variable('rolesToAdd', rolesList)

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

    Розгляньмо детально поданий скрипт:

  4. Ініціалізація списку ролей:

    • Створюється порожній список rolesList, який буде використовуватися для зберігання ролей.

  5. Заповнення списку із відповіді:

    • Виконується ітерація через об’єкт rolesResponse, який містить набір ролей.

    • Кожна роль із rolesResponse додається до rolesList за допомогою оператора << (який у Groovy використовується для додавання елементів у список).

  6. Отримання ролі зі стартової форми:

    • Отримується роль roleFromStartForm з початкової форми процесу (StartFormData), зокрема з властивості role.

  7. Додавання отриманої ролі до списку:

    • Додана роль з початкової форми також включається до rolesList.

  8. Виведення ролей на екран:

    • Виконується ітерація через rolesList, і кожна роль виводиться на екран (або консоль) за допомогою println. Це дозволяє побачити, які ролі були додані до списку.

  9. Встановлення змінної процесу:

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

2.5. Сервісна задача для додавання ролі з URL користувачу

Далі створіть сервісну задачу (Service Task), застосуйте та налаштуйте шаблон делегата для додавання ролей користувачу — Save user roles.

assign role via url 7

Детальніше про делегат читайте на сторінці Збереження ролей користувачів до Keycloak (Save user roles).

2.6. Подія "Помилка"

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

  1. Створення Error Boundary Event:

    • У бізнес-процесі створіть елемент Error Boundary Event.

    • У полі Code вкажіть код для виключення (exception): java.lang.IllegalArgumentException. Це дозволить визначити специфічну ситуацію помилки, яка може виникнути в процесі.

      assign role via url 8

    Щоб отримати більше інформації про подію "Помилка", перегляньте документацію тут: Подія «Помилка».

  2. Інформування користувачів про помилку:

    • Розробіть користувацьку задачу з формою для відображення повідомлень про помилки. Це допоможе користувачам зрозуміти, що сталася помилка, і які дії вони можуть вжити для її вирішення.

  3. Оброблення неавтентифікованих користувачів:*

    • У випадку, коли користувачі переходять на стартову форму бізнес-процесу за посиланням для неавтентифікованих користувачів, то після автентифікації, система автоматично перенаправляє їх на відповідну стартову форму.

    assign role via url 03

2.7. Користувацька задача про успішне набуття ролі користувачем

Для інформування користувачів про успішне призначення ролі та необхідність повторної автентифікації в Кабінеті, ви можете створити користувацьку задачу (User Task) з відповідною формою.

Застосуйте шаблон делегата User Form.

  1. У полі Form key вкажіть службову назву форму.

  2. У полі Assignee вкажіть ${initiator}. Це означає, що задача буде призначена особі, яка ініціювала бізнес-процес.

assign role via url 9

assign role via url 04

3. Формування посилання та відображення у Кабінетах користувачів

На порталах існує спеціальний маршрут (route), через який можна передати ідентифікатор бізнес-процесу (Business Process, BP) через параметр у посиланні (path parameters) та додаткові дані стартової форми через параметри запита (query parameters).

3.1. Шаблони побудови прямих посилань

Стандартний шаблон для надавачів послуг
https://officer-portal-<registry-name>.<dns-wildcard>/officer/process-list/<business-process-key>/start-form?data=<data>
Стандартний шаблон для отримувачів послуг
https://citizen-portal-<registry-name>.<dns-wildcard>/process-list/<business-process-key>/start-form?data=<data>
Таблиця 1. Пояснення до шаблонів посилань
Частина URL Пояснення

https://officer-portal-<registry-name>.<dns-wildcard>

  • officer-portal-/citizen-portal- — стандартний префікс, вказує на Кабінет.

  • <registry-name> — змінна, замінюється на назву конкретного реєстру чи системи.

  • <dns-wildcard> — змінна, доменне ім’я або піддомен, що використовується.

/officer/process-list/<business-process-key>/start-form

або

/process-list/<business-process-key>/start-form

  • /officer/process-list/ — шлях до списку бізнес-процесів для надавачів послуг.

    АБО /process-list/ — шлях до списку бізнес-процесів для отримувачів послуг.

  • <business-process-key> — змінна, ключ конкретного бізнес-процесу.

  • /start-form - шлях до стартової форми бізнес-процесу.

?data=<data>

  • ?data= — частина URL, ключ для передачі додаткових даних.

  • <data> — змінна, дані у форматі Base64URL, для автоматичного заповнення полів на стартовій формі. Можуть включати різні параметри.

3.2. Процес кодування даних

Для формування посилань із параметрами, що передзаповнюють форму, необхідно використовувати кодування Base64URL. Це можна зробити за допомогою сторонніх сервісів, наприклад https://www.base64encode.org/.

JSON із переданою роллю користувача
{"role": "op-role-to-assign-first"}
Закодований JSON у base64URL
eyJyb2xlIjogIm9wLXJvbGUtdG8tYXNzaWduLWZpcnN0In0
Рекомендовано обирати формат Base64URL при кодуванні.

wn 1 9 7 24

3.3. Формування кінцевих посилань (на прикладі бізнес-процесу у демо-реєстрі)

Стандартне посилання до Кабінету користувача: https://officer-portal-<registry-name>.<dns-wildcard>/officer/login. Воно приводить на сторінку логіну.

При створенні посилання на бізнес-процес із можливістю передзаповнення форми певним параметром необхідно змінити /login на:

  • реалм officer, /process-list, назву бізнес-процесу, стартову форму та додаткові параметри в кодуванні Base64.

У нашому прикладі, щоб передати параметр певної ролі, необхідно сформувати JSON із параметрами ключ-дані, де ключ — назва компонента (role), який необхідно передзаповнити, а дані — це значення для передзаповнення — <role-name>, тобто назва ролі.

Після кодування даних у Base64URL, їх необхідно додати до посилання. В результаті, посилання з параметром ролі op-role-to-assign-first буде виглядати так:

Категорія (Кабінет) Приклад посилання

Для надавачів послуг (officer-portal)

https://officer-portal-demo-registry.domain.com/officer/process-list/reference-assign-role-officer/start-form?data=eyJyb2xlIjogIm9wLXJvbGUtdG8tYXNzaWduLWZpcnN0In0

Для отримувачів послуг (citizen-portal)

https://citizen-portal-demo-registry.domain.com/process-list/reference-assign-role-officer/start-form?data=eyJyb2xlIjogIm9wLXJvbGUtdG8tYXNzaWduLWZpcnN0In0

wn 1 9 7 25

wn 1 9 7 26

3.4. Відображення результатів у Кабінеті

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

assign role via url 05

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

У випадку повторного переходу за посиланням, після виконання процесу, користувача одразу буде перенаправлено на вкладку Надані послуги.