Сервіс цифрових документів

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

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

2. Функціональні вимоги

  • Завантаження цифрових документів користувачами через UI-форми задач бізнес-процесів

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

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

3. Базові принципи реалізації

  • Завантаження або вивантаження документів можливе лише через UI-форму задачі бізнес-процесу

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

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

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

  • У якості сховища даних, сервіс цифрових документів використовує розподілене об’єктне сховище Ceph та оперує документами в окремому бакеті "lowcode-file-storage"

  • Усі документи, які завантажені в рамках бізнес-процесу, зберігаються у вигляді Ceph-об’єктів під ключами з ознакою групування за префіксом (process/{processInstanceId}/{id})

  • Тимчасовість збереження реалізується завдяки автоматичному механізму видалення документів, які були завантажені в рамках БП у разі його завершення

Назва бакету "lowcode-file-storage", який використовується для збереження цифрових документів має бути визначена на рівні конфігурації.
Включення "digital-document-service" в Istio Service Mesh під питанням.

4. Взаємодія компонентів системи

context

5. Сценарії взаємодії

file_storage

5.1. Генерація ідентифікаторів цифрових документів

Кожен цифровий документ у підсистемі "Low-code" визначається унікальним ідентифікатором файлу в рамках тенанта реєстру, зформований з використанням генератора псевдо-випадкових чисел (cad2e994-0e32-4a9f-9959-b420e20d4522) та який зберігається у вигляді окремого атрибуту мета-даних Ceph-об’єкта id.

var uuid = UUID.randomUUID();

Генерація ключа для збереження Ceph-об’єкта документу виконується згідно конвенції process/{processInstanceId}/{id}, де _processInstanceId - це ідентифікатор бізнес-процеса у виконанні.

5.2. Генерація гешів цифрових документів

При завантаженні файлів, система автоматично генерує геш з використанням SHA256 алгоритму (з використанням бібліотеки Apache Commons Codecs), як більш безпечного по відношенню до MD5. При збереженні документу в Ceph, згенерована checksum записується у вигляді атрибуту на рівні мета-даних Ceph-об’єкта та використовується у процесі підпису даних UI-форми користувача.

var sha256hex = DigestUtils.sha256Hex(data);
Розглянути можливість оптимізації шляхом інкрементального формування гешу у процесі обробки потоку данних при збереженні в Ceph.

5.3. Авторизація доступу

Доступ до API сервісу цифрових документів надається лише автентифікованим користувачам системи, які мають одну з ролей:

  • officer

  • citizen

У зв’язку з тим, що система дозволяє роботу з документами користувачам тільки через UI-форми задач бізнес-процесів, це накладає ряд додаткових умов на отримання доступу до завантаження, вивантаження та отримання мета-даних файлів, зокрема:

  • Користувач може завантажувати документи в рамках бізнес-процесу тільки при наявності активної задачі, для якої він встановлений у якості assignee

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

5.4. Валідація цифрових документів при завантаженні

При завантаженні файлів через поля типу "File" на UI-формі задачі бізнес-процесу, повинні застосовуватись валідаційні правила, налаштовані в інтерфейсі адміністрування регламенту реєстру.

На данний момент для файлових полів підтримуються наступні налаштувавння обмежень:

  • File Pattern - обмеження за типом файлу (application/pdf, image/png, image/jpeg)

  • File Maximum Size - обмеження за розміром файлу

file_validation

5.5. Автоматичне видалення цифрових документів при завершенні бізнес-процесу

Цифрові документи, які зберігаються в окремому Ceph-бакеті "lowcode-file-storage" мають життєвий цикл пов’язаний із виконанням бізнес-процесу, в рамках якого вони були завантажені або зчитані з Дата Фабрики.

Згідно прийнятої конвенції генерації, всі вони зберігаються у вигляді об’єктів, ключі яких мають вигляд process/{processInstanceId}/{id}.

Для забезпечення видалення файлів при завершенні бізнес-процесу, розроблено окремий ExecutionListener який реагує на відповідну подію та проводить видалення об’єктів з бакету для яких виконується умова наявності у ключі префікса вигляду process/{processInstanceId}, де _processInstanceId - це ідентифікатор екземпляра процесу, який підлягає завершенню з будь-якої з наступних причин:

  • COMPLETED

  • INTERNALLY_TERMINATED

  • EXTERNALLY_TERMINATED

5.6. Структура Ceph-об’єкту для збереження цифрового документа

Назва атрибуту Атрибут JSON-документа Атрибут Ceph об’єкта Значення

Ключ Ceph-об’єкта

key

Унікальний ідентифікатор Ceph-документу для збереження файла в області доступу поточного бізнес-процесу. Автоматично формується на базі згенерованого id згідно конвенції process/<processInstanceId>/<id>

Ідентифікатор цифрового документу

id

UserMetaData.id

Унікальний ідентифікатор файла, зформований з використанням генератора псевдо-випадкових чисел (cad2e994-0e32-4a9f-9959-b420e20d4522)

Назва файлу

name

UserMetaData.name

<Назва файлу>

Тип контента

type

Content-Type (UserMetaData.type)

application/pdf, image/png, image/jpeg

Розмір

size

Content-Length (UserMetaData.size)

<Розмір файлу>

Контент документа

content

input

<Контент файла>

Геш документа

checksum

(UserMetaData.checksum)

Згенерований SHA256-геш файла

6. Опис API сервісу

6.1. Завантаження файла цифрового документу

POST /documents/{processInstanceId}/{taskId}/{fieldName}
Таблиця 1. Параметри шляху адреси
Назва Опис

processInstanceId

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

taskId

Ідентифікатор задачі користувача, в рамках виконання якої виконується завантаження файла через UI-форму

fieldName

Унікальна назва файлового поля UI-форми задачі користувача, для якого виконується завантаження файла
Таблиця 2. Заголовки запиту
Назва Обов’язковий Значення Опис

X-Access-Token

Так

{Access Token}

Токен доступу до системи користувача, який виконує завантаження файла

Content-Type

Так

multipart/form-data

Тип даних запиту для завантаження файла
Таблиця 3. Структура відповіді на запит
Назва Опис

id

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

name

Оригінальне ім’я файла

type

Тип контенту файла

size

Розмір файла

checksum

Автоматично згенерований геш на контент файла з використанням SHA256 алгоритму

url

Адреса для вивантаження файла, яка автоматично формується на базі параметрів поточного запиту в обробці, контекста запиту та id
Приклад запиту:
POST /documents/{processInstanceId}/{taskId}/{fieldName}
---------------573cf973d5228
Content-Disposition: form-data; filename="{filename}"
Content-Type: {mime-type}

PDF file content
---------------573cf973d5228--
Приклад відповіді:
200 OK
Content-Type: application/json
{
    "id": "{id}",
    "name": "{filename}",
    "type:": "{mime-type}",
    "size": 1000,
    "checksum": "{sha256-hash}",
    "url": "https://.../documents/{processInstanceId}/{taskId}/{fieldName}/{id}"
}
Таблиця 4. Коди відповідей, які повертаються при обробці запиту
Код Опис

200

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

400

Некоректно сформований запит

401

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

403

Недостатньо прав для виконання операції

422

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

500

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

6.2. Вивантаження цифрового документу

GET /documents/{processInstanceId}/{taskId}/{fieldName}/{id}
Таблиця 5. Параметри шляху адреси
Назва Опис

processInstanceId

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

taskId

Ідентифікатор задачі користувача, в рамках виконання якої виконується вивантаження файла через UI-форму

fieldName

Унікальна назва файлового поля UI-форми задачі користувача, для якого виконується вивантаження файла

id

Унікальний ідентифікатор цифрового документу
Таблиця 6. Заголовки запиту
Назва Обов’язковий Значення Опис

X-Access-Token

Так

{Access Token}

Токен доступу до системи користувача, який виконує вивантаження файла

Content-Type

Так

application/pdf, image/jpeg, image/png

Тип даних, який очікується у відповідь на запит
Приклад відповіді:
200 OK
Content-Type: application/pdf | image/jpeg | image/png
Content-Disposition: attachment; filename="sample.pdf"
Content-Length: 1000
File binary content
Таблиця 7. Коди відповідей, які повертаються при обробці запиту
Код Опис

200

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

400

Некоректно сформований запит

401

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

403

Недостатньо прав для виконання операції

404

Не знайдено документ за ідентифікатором

500

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

6.3. Пошук цифрових документів

POST /documents/{processInstanceId}/{taskId}/search
Таблиця 8. Параметри шляху адреси
Назва Опис

processInstanceId

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

taskId

Ідентифікатор задачі користувача, в рамках виконання якої виконується завантаження файла через UI-форму
Таблиця 9. Заголовки запиту
Назва Обов’язковий Значення Опис

X-Access-Token

Так

{Access Token}

Токен доступу до системи користувача, який виконує запит на пошук доступних документів

Content-Type

Так

application/json

Тип даних, який очікується у відповідь на запит
Таблиця 10. Структура елементів масиву у відповіді на запит
Назва Опис

id

Унікальний ідентифікатор цифрового документу

name

Оригінальне ім’я файла

type

Тип контенту файла

size

Розмір файла

checksum

Автоматично згенерований геш на контент файла з використанням SHA256 алгоритму

url

Адреса для вивантаження файла, яка автоматично формується на базі параметрів поточного запиту в обробці
Приклад тіла запиту:
{
    "documents": [
      {
        "id": "{id1}",
        "fieldName": "{fieldName1}"
      },
      {
        "id": "{id2}",
        "fieldName": "{fieldName2}"
      }
    ]
}
Приклад відповіді:
200 OK
Content-Type: application/json
[
    {
        "id": "{id}",
        "name": "{filename}",
        "type:": "{mime-type}",
        "size": 1000,
        "checksum": "{sha256-hash}",
        "url": "https://.../documents/{processInstanceId}/{taskId}/{fieldName}/{id}"
    }
]
Таблиця 11. Коди відповідей, які повертаються при обробці запиту
Код Опис

200

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

400

Некоректно сформований запит

401

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

403

Недостатньо прав для виконання операції

500

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