Налаштування форми користувача: User form

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

1. Загальна інформація
2. Перед початком
3. Налаштування
- 3.1. Налаштування завдання користувача
- 3.2. Налаштування делегата
4. Приклад
5. Пов’язані сторінки

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

1. Загальна інформація

Інтеграційне розширення User form дозволяє налаштовувати форми користувачів у рамках бізнес-процесів, додаючи різні властивості до завдання користувача (User Task).

Таблиця 1. Короткі відомості про делегат
Назва	Пояснення
Бізнес-назва інтеграційного розширення	User form
Службова назва інтеграційного розширення	`${formUserTaskTemplate}`
Назва файлу в бібліотеці розширень	userTaskTemplate.json

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

При моделюванні бізнес-процесів із використанням сторонніх застосунків, важливо інтегрувати каталог типових розширень з нашого репозиторію. Завітайте до business-process-modeler-extensions, щоб завантажити необхідні файли. Наприклад, для таких інструментів, як Camunda Modeler, у вашій теці /element-templates мають бути включені відповідні JSON-файли. Для детальних інструкцій, будь ласка, перегляньте Встановлення типових розширень.

3. Налаштування

Делегат User form призначений для використання у завданнях користувача (User Task) бізнес-процесу. Він дозволяє налаштувати форми користувача з різними параметрами.

Розширення використовується для визначення задачі, що НЕ потребує валідації КЕП-підписом надавача або отримувача послуг.

3.1. Налаштування завдання користувача

Створіть завдання типу User Task у вашому бізнес-процесі.
Назвіть завдання, наприклад, Форма користувача.
Застосуйте шаблон делегата, обравши User form зі списку в налаштуваннях завдання.

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

Form key

У полі Form key вкажіть службову назву UI-форми. Це поле обов’язкове і має бути заповненим. Воно чітко пов’язує UI-форму і користувацьку задачу бізнес-процесу.

Assignee

У полі Assignee вкажіть виконавця завдання. Зробити це можна кількома способами:

Наприклад, ви можете призначити задачу ініціатору бізнес-процесу, вказавши ${initiator}.

Для використання ${initiator} у задачах користувача (як звичайних, так і таких, що потребують валідації підписом КЕП), у стартовій події бізнес-процесу необхідно визначити ініціатора процесу зі значенням initiator.

Також ви можете призначити виконавця попереднього завдання користувача. Для цього ви можете використати JUEL-функцію completer(), передавши ID попередньої задачі та використавши метод userName. Наприклад:
```
${completer('previous user task ID').userName}
```
- completer() — назва JUEL-функції.
- 'previous user task ID' — ID попередньої задачі користувача.
- userName — метод, який передає ідентифікатор користувача з Keycloak.
Вкажіть значення ідентифікатора користувача напряму (константа), щоб призначити задачу одному чітко визначеному користувачу. Наприклад, userID.

Ідентифікатором користувача є параметр preferred_user_name, встановлений у Keycloak.

Якщо визначено Assignee, то поля Candidate users та Candidate roles потрібно залишати порожніми (див. нижче). Якщо Assignee не вказано, то потрібно обов’язково вказати або список користувачів, або список ролей, яким буде доступна до виконання поточна задача. Інакше задача не буде відображатися у доступних до виконання в рамках вашого бізнес-процесу.

Candidate users

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

(Рекомендовано). Передайте список користувачів як рядок через змінну.

Для цього попередньо використайте делегат Пошук користувачів реєстру за атрибутами: Search registry users by attributes, за допомогою якого ви зможете отримати список користувачів у вигляді комплексного об’єкта. Не всі поля із цього об’єкта потрібні для визначення Candidate users. Тому результат, який повернеться в делегат, потрібно спочатку зберегти, наприклад, у змінну usersResponse, потім перетворити скриптом список в рядок із username, визначених через кому. Потім результат виконання скрипту потрібно записати в нову змінну як рядок, наприклад, usersList, і передати її в полі Candidate users. Наприклад, ${usersList}.
(Альтернативно). Передайте список користувачів як константу, тобто вкажіть username одного або більше користувачів з Keycloak через кому. Наприклад:
```
username1,username2,username3
```

Candidate roles

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

Передайте список ролей як рядок через змінну. Для цього використовуйте один із доступних делегатів:
- Отримання ролей з Keycloak-реалму: Get Keycloak roles by realm
- Отримання ролей користувача з Keycloak: Get Keycloak roles from user
  
  За допомогою одного з цих делегатів ви зможете отримати список усіх ролей певного користувача або список усіх ролей з певного Keycloak-реалму. Список повертається у наступному форматі:
  Приклад відповіді зі списком ролей у форматі JSON
  [ "user", "admin", "hierarchy-registry-manager", "personnel-officer-admin", "reviewer" ]
  Не всі ролі зі списку можуть бути потрібними для визначення Candidate roles. Тому результат, який повернеться в делегаті, потрібно спочатку зберегти, наприклад, у змінну roles, потім скриптом отримати список лише тих ролей, які потрібні для виконання завдання. Потім результат виконання скрипту потрібно записати в нову змінну як рядок, наприклад, availableRoles, і передати її в полі Candidate roles. Наприклад, ${availableRoles}.

Передайте список ролей як константу, тобто вкажіть одну або більше ролей з Keycloak через кому. Наприклад:

user,admin,manager

Наприклад, бізнес-процес з умовною назвою bp1 зможе ініціювати лише користувач з роллю officer-bp1, але задачу у цьому процесі, яка доступна ролям user,admin,manager, зможуть виконати лише користувачі, які мають одну з вказаних ролей в Keycloak, бо така роль визначена у переліку Candidate roles.

Form data pre-population

Поле Form data pre-population забезпечує автоматичне заповнення форми даними, які були введені на одній з попередніх користувацьких задач. Вказати значення для цього поля можна двома способами:
- Передайте дані як змінну. Для цього потрібно спочатку взяти дані на одній з попередніх форм за допомогою скрипту. Результат виконання скрипту можна записати як об’єкт, наприклад, у змінну formData. Потім ви можете передати сформований об’єкт як змінну ${formData} у поле Form data pre-population.
- Передайте дані за допомогою функції submission(). Це можна зробити за допомогою виразу:
  ${submission('Previous user task ID').formData}
  - submission() — назва JUEL-функції.
  - 'Previous user task ID' — ID будь-якої попередньої задачі користувача, змодельованої у бізнес-процесі, і яка містить подібний набір полів — ідентична або майже ідентична.
  - formData — метод, який дозволяє отримати дані на UI-формі у бізнес-процес й передати їх на іншу форму.
    
    Це забезпечує зв’язок між діями виконавця попередньої задачі та цією задачею.

Form variables

Form variables (змінні форми) у бізнес-процесах та UI-формах використовуються для зберігання та передачі даних між різними етапами процесу та інтерфейсом користувача. Вони забезпечують взаємодію між користувачем і бізнес-логікою, а також між різними частинами бізнес-процесу. Найбільш прикладним випадком використання form variables є заповнення UI-форми даними, які вже є у системі, що полегшує роботу користувача. Наприклад, якщо користувач заповнює форму розподілення певних задач бізнес-процесу для певних ролей зі списку доступних у системі, form variables можуть використовуватись для автоматичного заповнення відповідних полів із випадного списку ролей.

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

Відкрийте налаштування форми, перейдіть на вкладку Data та налаштуйте наступні параметри:
1. У полі Data source type введіть Custom.
2. У полі Custom Values вкажіть values = formVariables.officerUsers.
У полі Form variables бізнес-процесу вкажіть змінну officerUsers, яка буде передана на форму.

Більш детально про змінні форм ви можете дізнатися у розділі Моделювання форм за допомогою formVariables.

4. Приклад

Ось приклад, який показує, як відповідний делегат використовується у бізнес-процесі:

Зображення 1. Приклад. Налаштування делегата User form

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

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

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

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

Ви можете використати один із багатьох прикладів процесів за пошуком по ключовим словам — reference-parallel-tasks-officers-diff-rls.

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