Генерація витягів з кабінету користувача

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

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

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

  • Бізнес-процес, результатом якого є зформований витяг, доступний для завантаження з кабінету та офлайн перегляду

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

Детальніше з дизайном підсистеми звітності можна ознайомитися за посиланням.

1. Базові принципи

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

  • Доступ до інформаційної послуги генерації витягу контролюється на рівні БП та на рівні доступу до даних, які необхідно завантажити для формування витягу

  • Витяг має бути представлений окремим шаблоном на рівні регламенту реєстру та однозначно ідентифікується типом витягу

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

  • Запит на формування витягу до "Підсистеми звітності" має бути підписаним ключем користувача або системним ключем

  • Згенеровані витяги можуть бути завантажені лише користувачем, який замовив інформаційну послугу

  • Згенеровані витяги мають бути доступні для завантаження у визначений проміжок часу у початковому вигляді згідно прав доступу до даних на момент генерації

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

  • Необхідність накладання системного цифрового підпису на витяг визначається адміністратором регламенту на рівні моделювання бізнес-процесу

  • Процес генерації витягу не має блокувати роботу користувача з кабінетом

  • Користувач кабінету має можливість отримати інформацію про статус генерації витягу на сторінці "Послуги у виконанні" та завантажити документ витягу зі сторінки "Замовлені послуги" у разі його готовності

  • Підготовка даних для формування запиту на генерацію витягу моделюється на рівні БП за допомогою допоміжних Search Conditions функціональності платформи.

  • Рекомендовано мінімізувати об’єм даних, який завантажується на рівні БП для формування запиту на генерацію витягу

2. Низькорівневий дизайн взаємодії

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

excerpt generation

2.1. Замовлення інформаційної послуги формування витягу

Інформаційна послуга формування витягу має бути змодельована у вигляді окремого бізнес-процесу з використанням наступних інструментів та можливостей моделювання:

excerpt_generation

2.2. Логічна модель бізнес-процесу формування витягу

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

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

  • Асинхронний підхід до моделювання бізнес-процесу генерації витягів (beforeAsync), при якому користувач після ініціювання запиту на формування витягу перенаправляється на сторінку "Послуг у виконанні", де він може відслідковувати стан генерації витягу або продовжувати роботу з кабінетом. У цьому разі, користувачу потрібно буде самостійно перейти на сторінку "Замовлені послуги" по завершенню бізнес-процесу генерації витягу

excerpt generation bpmn

2.3. Задіяні системні змінні бізнес-процесу

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

Назва системної змінної Опис

SYS_VAR_PROCESS_EXCERPT_ID

Змінна використовується для збереження ідентифікатору витягу, у разі, якщо витяг є результатом надання послуги / виконання бізнес-процесу

SYS_VAR_PROCESS_COMPLETION_RESULT

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

2.4. Отримання згенерованих витягів через кабінет

Результатом бізнес-процесу надання інформаційної послуги є згенерований документ, який збережено у розподіленому об’єктному сховищу Ceph. Додатково, ідентифікатор документу витягу буде збережено у вигляді змінної екземпляру бізнес-процесу SYS_VAR_PROCESS_EXCERPT_ID. Наявність цієї змінної і є ознакою інформаційної послуги, результатом якої є витяг на відміну від інших. Для замовлених послуг з цією ознакою стає доступна окрема опція "Завантажити витяг" у кабінеті користувача, яка дозволяє завантажити цілоьвий документ через "API отримання витягів".

За надання доступу до завантаження згенерованих документів за унікальним ідентифікатором та контроль доступу відповідає окремий бекенд-сервіс "API отримання витягів". З описом контракту API "Підсистеми звітності" можна ознайомитися за посиланням
excerpt_retrieval
Таблиця 1. Коди помилок, які повертаються при невдалій спробі обробки запиту на отримання витягу
Код Опис

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

Тіло відповіді

Унікальний ідентифікатор витягу, за яким можно отримати доступ на завантаження згенерованого документу
Приклад тіла запиту на генерацію витягу (системний підпис накладається на все тіло запиту та передається у вигляді посилання на Ceph документ у HTTP заголовку X-Digital-Signature-Derived)
{
  "excerptType": "subject-laboratories-accreditation-excerpt",
  "requiresSystemSignature": true,
  "excerptInputData": {
    "subjectId": "<UUID>"
  }
}
Приклад відповіді у разі успішного результату виконання запиту на генерацію витягу
{
  "excerptIdentifier": "<UUID>"
}
Таблиця 2. Коди помилок, які повертаються при невдалій спробі обробки запиту
Код Опис

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": "Технічний опис помилки"
}
Таблиця 3. Коди помилок, які повертаються при невдалій спробі обробки запиту
Код Опис

200

OK з поверненням статусу у тілі відповіді

400

Некоректно сформований запит (неправильний формат даних)

401

Помилка автентифікації (відсутній токен доступу)

404

Не знайдено запис трекінга статусу генерації витяга за ідентифікатором

500

Серверна помилка обробки запиту

3.3. Конфігурація типового розширення отримання токена доступу системного користувача

У ряді випадків існує необхідність взаємодії бізнес-процесу з внутрішніми сервісами платформи на рівні service-2-service, а контекст виклику не обов’язково потребує токен доступу користувача, який ініціював бізнес-процес або є виконавцем задач. У цьому разі платформа надає типове розширення для отримання токена доступу від імені системного користувача (сервіс-акаунта) з Keycloak, який дозволяє виконувати внутрішні системні запити / проходити авторизацію.

Конфігураційний параметр Вхідний/Вихідний Службова назва Тип Опис

Токен доступу

out

systemUserAccessToken

string

Токен системного користувача (сервіс-акаунта, створеного для bpms сервісу)