Генерація витягів з кабінету користувача
🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію. |
Для забезпечення вимог надання інформаційних послуг на базі платформи, реалізована підтримка двох підходів до моделювання бізнес-процесів в залежності від способу відображення даних через кабінет користувача:
-
Бізнес-процес, результатом якого є відображення даних через UI-форму кабінету
-
Бізнес-процес, результатом якого є зформований витяг, доступний для завантаження з кабінету та офлайн перегляду
Данний технічний дизайн зфокусований на вимогах підтримки інформаційних послуг, результатом яких є генерація витягу з реєстру на рівні Low-code платформи.
Детальніше з дизайном підсистеми звітності можна ознайомитися за посиланням. |
1. Базові принципи
-
Витяги можуть бути згенеровані тільки в рамках надання інформаційних послуг через бізнес-процеси
-
Доступ до інформаційної послуги генерації витягу контролюється на рівні БП та на рівні доступу до даних, які необхідно завантажити для формування витягу
-
Витяг має бути представлений окремим шаблоном на рівні регламенту реєстру та однозначно ідентифікується типом витягу
-
В рамках одного бізнес-процесу може бути згенерований тільки один витяг з урахуванням прав доступу користувача, який ініціював БП до даних
-
Запит на формування витягу до "Підсистеми звітності" має бути підписаним ключем користувача або системним ключем
-
Згенеровані витяги можуть бути завантажені лише користувачем, який замовив інформаційну послугу
-
Згенеровані витяги мають бути доступні для завантаження у визначений проміжок часу у початковому вигляді згідно прав доступу до даних на момент генерації
-
На згенеровані витяги може бути накладено системний цифровий підпис в залежності від типу інформаційної послуги та даних, на базі яких формується витяг
-
Необхідність накладання системного цифрового підпису на витяг визначається адміністратором регламенту на рівні моделювання бізнес-процесу
-
Процес генерації витягу не має блокувати роботу користувача з кабінетом
-
Користувач кабінету має можливість отримати інформацію про статус генерації витягу на сторінці "Послуги у виконанні" та завантажити документ витягу зі сторінки "Замовлені послуги" у разі його готовності
-
Підготовка даних для формування запиту на генерацію витягу моделюється на рівні БП за допомогою допоміжних Search Conditions функціональності платформи.
-
Рекомендовано мінімізувати об’єм даних, який завантажується на рівні БП для формування запиту на генерацію витягу
2. Низькорівневий дизайн взаємодії
На даній діаграмі зображено задіяні для реалізації вимог сервіси платформи, взаємодію між ними у розрізі напрямків та типів потоків даних. Додатково зображено важливі особливості, які необхідно прийняти до уваги в рамках реалізації та моделювання.
2.1. Замовлення інформаційної послуги формування витягу
Інформаційна послуга формування витягу має бути змодельована у вигляді окремого бізнес-процесу з використанням наступних інструментів та можливостей моделювання:
-
Синхронний або асинхронний підхід до генерації витягу в рамках бізнес-процесу
-
Типове розширення для отримання інформації про статус генерації витягу
-
Типове розширення отримання токена доступу системного користувача
-
Системні змінні екземпляру бізнес-процесу, які використовуються для відображення результату формування витягу та встановлення асоціації між екземпляром бізнес-процесу та згенерованим документом
2.2. Логічна модель бізнес-процесу формування витягу
На даній діаграмі зображено логічну модель бізнес-процесу формування запиту на генерацію витягу. Підтримується два підходи до організації UX з боку користувача:
-
Синхронний підхід до моделювання бізнес-процесу генерації витягів (sync), при якому користувач після ініціювання через кабінет має дочекатися завершення процесу генерації після чого система автоматично перенаправять його на сторінку "Замовлені послуги", на якій є можливість завантажити витяг, згенерований в рамках початкового бізнес-процесу. Цей підхід пришвидшує користувачу доступ до завантаження, але, в той же час, може бути використаний для витягів, час генерації яких не погіршує UX у розрізі часу очікування
-
Асинхронний підхід до моделювання бізнес-процесу генерації витягів (beforeAsync), при якому користувач після ініціювання запиту на формування витягу перенаправляється на сторінку "Послуг у виконанні", де він може відслідковувати стан генерації витягу або продовжувати роботу з кабінетом. У цьому разі, користувачу потрібно буде самостійно перейти на сторінку "Замовлені послуги" по завершенню бізнес-процесу генерації витягу
2.3. Задіяні системні змінні бізнес-процесу
З ціллю підтримки асоціації між ініційованим єкземпляром бізнес-процесу та згенерованим документом витягу, використовуються змінні процесу, які зберігаються в історичну таблицю операційного сховища бізнес-процесів.
Назва системної змінної | Опис |
---|---|
SYS_VAR_PROCESS_EXCERPT_ID |
Змінна використовується для збереження ідентифікатору витягу, у разі, якщо витяг є результатом надання послуги / виконання бізнес-процесу |
SYS_VAR_PROCESS_COMPLETION_RESULT |
Опис результату виконання, який вказується адміністратором регламенту при моделюванні бізнес-процесу |
2.4. Отримання згенерованих витягів через кабінет
Результатом бізнес-процесу надання інформаційної послуги є згенерований документ, який збережено у розподіленому об’єктному сховищу Ceph. Додатково, ідентифікатор документу витягу буде збережено у вигляді змінної екземпляру бізнес-процесу SYS_VAR_PROCESS_EXCERPT_ID. Наявність цієї змінної і є ознакою інформаційної послуги, результатом якої є витяг на відміну від інших. Для замовлених послуг з цією ознакою стає доступна окрема опція "Завантажити витяг" у кабінеті користувача, яка дозволяє завантажити цілоьвий документ через "API отримання витягів".
За надання доступу до завантаження згенерованих документів за унікальним ідентифікатором та контроль доступу відповідає окремий бекенд-сервіс "API отримання витягів". З описом контракту API "Підсистеми звітності" можна ознайомитися за посиланням |
Код | Опис |
---|---|
200 |
OK з поверненням згенерованого файлу витягу |
400 |
Некоректно сформований запит (неправильний формат даних) |
401 |
Помилка автентифікації (відсутній токен доступу) |
404 |
Не знайдено файл витягу за ідентифікатором |
500 |
Серверна помилка обробки запиту |
2.5. Авторизація доступу користувачів до згенерованих витягів
Доступ до згенерованого витягу повинен мати лише користувач, який автентифікований у системі та який ініціював замовлення інформаційної послуги формування витягу через бізнес-процес згідно прав доступу, налаштованим на рівні регламенту.
3. Типові розширення моделювання
3.1. Конфігурація типового розширення генерації витягів
З ціллю надання можливостей моделювання інформаційних послуг, результатом яких є згенерований документ витягу, використовується окреме типове розширення Java Delegate у каталозі моделювання, за допомогою якого можно визначити всі необхідні параметри запиту на генерацію.
До виклику автоматично додаються системні змінні контексту виклику у якості HTTP заголовків:
-
X-Source-System - Назви підсистеми, яка виконує запит ("Low-code Platform")
-
X-Source-Application - Назва компоненти підсистеми, яка ініціює запит ("business-process-management")
-
X-Source-Business-Process - Назва бізнес-процесу, яку визначив адміністратор регламенту при моделюванні (Process Name)
-
X-Source-Business-Process-Definition-Id - Унікальний ідентифікатор бізнес-процесу, яку визначив адміністратор регламенту при моделюванні (Process Id)
-
X-Source-Business-Process-Instance-Id - Автоматично згенерований унікальний ідентифікатор екземпляру бізнес-процесу, в рамках якого виконується запит (Генерується автоматично, максимальна довжина 64 символи)
-
X-Source-Business-Activity - Назва сервісної задачі, яку визначив адміністратор регламенту при моделюванні (Name)
-
X-Source-Business-Activity-Definition-Id - Унікальний ідентифікатор сервісної задачі, яку визначив адміністратор регламенту при моделюванні (Id)
-
X-Source-Business-Activity-Instance-Id - Автоматично згенерований унікальний ідентифікатор екземпляру сервісної задачі бізнес-процесу, в рамках якої виконується запит. (Максимальна довжина 64 символи)
Додатково, розширення додає наступні автоматично згенеровані HTTP заголовоки:
-
X-Digital-Signature-Derived - Посилання на Ceph документ в якому зберігається системний підпис, який автоматично накладено на тіло запиту
Конфігураційний параметр | Вхідний/Вихідний | Службова назва | Тип | Частина запиту | Опис |
---|---|---|---|---|---|
Токен доступу |
in |
X-Access-Token |
string |
HTTP заголовок |
Токен користувача, під яким виконується запит на генерацію витягу |
Оригінальний документ запиту з підписом |
in |
X-Digital-Signature |
string |
HTTP заголовок |
Посилання на Ceph документ, в якому збережено оригінальний запит користувача та підпис |
Тип звіту |
in |
excerptType |
string |
Частина JSON документу тіла запиту |
Тип витягу, який необхідно згенерувати в рамках бізнес-процесу |
Накладання системного підпису |
in |
requiresSystemSignature |
boolean |
Частина JSON документу тіла запиту |
Необхідність накладання системного підпису для заданого типу звіту |
Вхідні дані для генерації |
in |
excerptInputData |
map |
Частина JSON документу тіла запиту |
Набір данних, які необхідно передати у якості параметрів для генерації витягу |
Ідентифікатор витягу |
out |
excerptIdentifier |
string |
Тіло відповіді |
Унікальний ідентифікатор витягу, за яким можно отримати доступ на завантаження згенерованого документу |
{
"excerptType": "subject-laboratories-accreditation-excerpt",
"requiresSystemSignature": true,
"excerptInputData": {
"subjectId": "<UUID>"
}
}
{
"excerptIdentifier": "<UUID>"
}
Код | Опис |
---|---|
200 |
OK з поверненням ідентифікатора витягу, за яким можна отримати статус генерації |
400 |
Некоректно сформований запит (невідомий тип витягу, відсутність необхідних полей або неправильний формат переданих даних) |
401 |
Помилка автентифікації (відсутній токен доступу або цифровий підпис) |
403 |
Недостатньо прав для виконання операції |
500 |
Серверна помилка обробки запиту |
3.2. Конфігурація типового розширення для отримання інформації про статус генерації витягів
З ціллю надання можливостей моніторингу статусу виконання запиту на генерацію витягу, використовується окреме типове розширення Java Delegate у каталозі моделювання, за допомогою якого можно визначити всі необхідні параметри запиту та отримати актуальний статус формування документу.
Додатково, до виклику автоматично додаються системні змінні контексту виклику у якості заголовків:
-
X-Source-System - Назви підсистеми, яка виконує запит ("Low-code Platform")
-
X-Source-Application - Назва компоненти підсистеми, яка ініціює запит ("business-process-management")
-
X-Source-Business-Process - Назва бізнес-процесу, яку визначив адміністратор регламенту при моделюванні (Process Name)
-
X-Source-Business-Process-Definition-Id - Унікальний ідентифікатор бізнес-процесу, яку визначив адміністратор регламенту при моделюванні (Process Id)
-
X-Source-Business-Process-Instance-Id - Автоматично згенерований унікальний ідентифікатор екземпляру бізнес-процесу, в рамках якого виконується запит (Генерується автоматично, максимальна довжина 64 символи)
-
X-Source-Business-Activity - Назва сервісної задачі, яку визначив адміністратор регламенту при моделюванні (Name)
-
X-Source-Business-Activity-Definition-Id - Унікальний ідентифікатор сервісної задачі, яку визначив адміністратор регламенту при моделюванні (Id)
-
X-Source-Business-Activity-Instance-Id - Автоматично згенерований унікальний ідентифікатор екземпляру сервісної задачі бізнес-процесу, в рамках якої виконується запит. (Максимальна довжина 64 символи)
Конфігураційний параметр | Вхідний/Вихідний | Службова назва | Тип | Частина запиту | Опис |
---|---|---|---|---|---|
Токен доступу |
in |
X-Access-Token |
string |
HTTP заголовок |
Токен системного користувача, який було отримано в рамках окремого єтапу БП |
Ідентифікатор витягу |
in |
excerptIdentifier |
string |
Параметр запиту |
Унікальний ідентифікатор документу витягу, за яким можно отримати інформацію про статус генерації |
Статус генерації витягу |
out |
status |
string |
Тіло відповіді |
Статус генерації документу витягу (IN_PROGRESS, COMPLETED, FAILED) |
{
"excerptIdentifier": "<UUID>"
}
{
"status": "COMPLETED"
}
{
"status": "FAILED",
"statusDetails": "Технічний опис помилки"
}
Код | Опис |
---|---|
200 |
OK з поверненням статусу у тілі відповіді |
400 |
Некоректно сформований запит (неправильний формат даних) |
401 |
Помилка автентифікації (відсутній токен доступу) |
404 |
Не знайдено запис трекінга статусу генерації витяга за ідентифікатором |
500 |
Серверна помилка обробки запиту |
3.3. Конфігурація типового розширення отримання токена доступу системного користувача
У ряді випадків існує необхідність взаємодії бізнес-процесу з внутрішніми сервісами платформи на рівні service-2-service, а контекст виклику не обов’язково потребує токен доступу користувача, який ініціював бізнес-процес або є виконавцем задач. У цьому разі платформа надає типове розширення для отримання токена доступу від імені системного користувача (сервіс-акаунта) з Keycloak, який дозволяє виконувати внутрішні системні запити / проходити авторизацію.
Конфігураційний параметр | Вхідний/Вихідний | Службова назва | Тип | Опис |
---|---|---|---|---|
Токен доступу |
out |
systemUserAccessToken |
string |
Токен системного користувача (сервіс-акаунта, створеного для bpms сервісу) |