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

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

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

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

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

2. Актори та ролі користувачів

Розробник регламенту

3. Функціональні сценарії

Вивантаження файлу за віддаленою адресою та завантаження до Об’єктного сховища проміжних даних БП у скриптових задачах бізнес-процесів

4. Загальні принципи та положення

Ініціювання вивантаження та збереження файлу з БП через JUEL-функцію виконується під системним користувачем
Збереження файлів за віддаленою адресою дозволено лише для службового / внутрішнього використання у межах виконання бізнес-процесу
Розмір файлів, які можуть бути вивантажені обмежено налаштуваннями на рівні системи
Вивантаження та збереження файлів виконується за межами бізнес-процесу Сервісом цифрових документів
Збережені через JUEL-функцію цифрові документи підлягаються видаленню по завершенню виконання бізнес-процесу

5. Технічний дизайн рішення

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

Вивантаження файлів за віддаленою адресою потребує наявності відповідного Istio Service Entry, який було створено в автоматичному або ручному режимі.

В цільовому рішенні, для вивантаження файлів з віддаленої системи у процесі виконання БП, технічний адміністратор реєстру попередньо має налаштувати відповідну зовнішню систему через адмін-консоль згідно дизайну arch:architecture-workspace/platform-evolution/registry-regulation-secrets.adoc.

5.1. API збереження цифрового документу за віддаленою адресою

Призначенням API-роута є вивантаження файлу, який знаходиться за віддаленою адресою у межах налаштованих обмежень за розміром та подальше його збереження до Об’єктного сховища проміжних даних БП.

Вивантаження файлу з віддаленого сервера та завантаження до об’єктного сховища має бути реалізовано з використанням стрімінгу та відповідних обмежень на використання пам’яті серверного додатка.

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

Не публічний / для внутрішньої міжсервісної взаємодії

5.1.2. Специфікація API-роута

POST /internal-api/documents/{processInstanceId}/

Таблиця 1. Заголовки запиту
Заголовок	Тип	Опис
X-Access-Token	JWT	Токен доступу

Таблиця 2. Параметри запиту
Параметр	Тип	Частина запиту	Опис
processInstanceId	Текстовий	Параметр запиту	Ідентифікатор бізнес-процесу, в рамках якого виконується завантаження файла
remoteFileLocation	URL	Параметр запиту	Віддалене розташування файлу для вивантаження
filename	Текстовий	Параметр запиту	Назва файлу

Таблиця 3. Структура тіла відповіді
Json Path	Тип	Опис
$.id	UUID	Унікальний ідентифікатор цифрового документу, зформований з використанням генератора псевдо-випадкових чисел
$.name	Текстовий	Оригінальне ім’я файла
$.type	Текстовий	Тип контенту файла (application/pdf, image/png, image/jpeg, etc.)
$.checksum	Тестовий	Автоматично згенерований геш на контент файла з використанням SHA256 алгоритму
$.size	Числовий	Розмір файла

Приклад відповіді

{
  "id": "{UUID}",
  "name": "{fileName}",
  "type": "{contentType}",
  "checksum": "{sha256}",
  "size": 0
}

Таблиця 4. Коди відповіді
Код	Опис
201	Created з поверненням тіла відповіді
400	Некоректно сформований запит
401	Помилка автентифікації (відсутній токен доступу)
422	Помилка валідації (недопустимий розмір файлу, тощо.)
500	Серверна помилка обробки запиту

5.2. Системні налаштування

Розширити конфігурацію Сервісу цифрових документів додатковими налаштуваннями:

max-remote-file-size - Обмеження на розмір файлу для вивантаження за віддаленою адресою (default: 10MB)

6. Моделювання регламенту реєстру

6.1. Розширення для моделювання

Необхідно реалізувати наступну JUEL-функцію:

save_digital_document_from_url(String remoteFileUrl, String targetFileName): DocumentMetadata

Структура об’єкту мета-даних цифрового документа

class DocumentMetadata {
  String id       // Унікальний ідентифікатор цифрового документу
  String name     // Оригінальне ім’я файла
  String type     // Тип контенту файла
  String checksum // SHA256-геш на контент файлу
  Long size       // Розмір файла
}

6.2. Референтні приклади моделювання

Приклад використання save_digital_document_from_url при розробці скриптової задачі бізнес-процесу

try {
  def documentMetadata = save_digital_document_from_url("http://...", "digital-document.ext") // Temporary save file to object storage

  def fileReference = [
    id: documentMetadata.id,
    checksum: documentMetadata.checksum
  ]
} catch (ValidationException ex) {
 // File size exceeded "max-remote-file-size" value
}

BE / Camunda

8.2. План розробки

Розширення API Сервісу цифрових документів службовим роутом вивантаження та збереження файлів
Розширення / реалізація Java-клієнта для Сервісу цифрових документів
Реалізація JUEL-функції для завантаження файлів від імені системного користувача у Сервіс цифрових документів
Розробка інструкцій для розробника регламенту та референтних прикладів