Завантаження цифрових документів за зовнішнім посиланням

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

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

Наразі система дозволяє отримувати цифрові документи за зовнішнім посиланням із типом автентифікації NO_AUTH, коли запит виконується до публічних API (детальніше — див. розділ Налаштування інтеграції із зовнішньою системою).

Для отримання цифрових файлів за віддаленою адресою розроблена JUEL-функція save_digital_document_from_url(), яку можна використовувати для спрощення моделювання процесів у скриптах (детальніше — див. розділ Використання у бізнес-процесі).

За обробку цифрових документів на Платформі відповідає Сервіс цифрових документів (digital-document-service).

remote-file-transfer
Зображення 1. Отримання цифрового контенту за віддаленою адресою та подальша обробка всередині реєстру

2. Налаштування інтеграції із зовнішньою системою

Для того, щоб запит на отримання зовнішніх ресурсів міг вийти за межі кластера Платформи, необхідно на рівні реєстру створити Service Entry — точку виходу трафіку за межі системи.

Service Entry створюється автоматично, після того, як адміністратор реєстру налаштує інтеграцію в адміністративній панелі Control Plane. Після застосування змін до конфігурації реєстру та проходження Jenkins-пайплайн MASTER-Build-<registry-name>, підключення до зовнішньої системи буде налаштовано.
За деталями налаштувань у консолі Control Plane зверніться до сторінки Налаштування взаємодії з іншими системами у Control Plane.

  1. Увійдіть до консолі Control Plane як адміністратор реєстру.

  2. Перейдіть до розділу Реєстри та відкрийте необхідний.

  3. Знайдіть секцію Налаштування взаємодії з іншими системами та натисніть + ДОДАТИ ЗОВНІШНЮ СИСТЕМУ.

  4. У новому вікні налаштуйте інтеграцію із зовнішньою системою для подальшої взаємодії згідно з регламентом реєстру.

    Налаштуйте взаємодію через метод автентифікації NO_AUTH. Інші методи автентифікації для цього сценарію недоступні.

    cp ext sys 3

3. Використання у бізнес-процесі

3.1. Загальні відомості та обмеження

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

Для отримання цифрових файлів за віддаленою адресою використовуйте JUEL-функцію save_digital_document_from_url (). Її можна використовувати при розробці Groovy-скриптів у бізнес-процесах.

Функція може приймати 2 вхідні параметри:

  • URL цифрового документа

  • Назва файлу

    Можливо отримати лише один документ за один запит до зовнішнього джерела.

    Обидва параметри є рядком (String), тому моделювальник може передати функції фактично будь-який аргумент:

    Приклад 1. Шаблон функції
    save_digital_document_from_url(String remoteFileUrl, String targetFileName)

Алгоритм роботи функції наступний:

  1. Функція save_digital_document_from_url () виконує запит до відкритого ресурсу за вказаним посиланням та отримує цифровий документ (наприклад, зображення у форматі .jpeg).

  2. Далі передає файл Сервісу цифрових документів (digital-document-service).

  3. Сервіс зберігає файл у зашифрованому вигляді до Об’єктного сховища проміжних даних БП (lowcode-file-storage) та у відповідь отримує метадані — id та checksum документа, які передаються до бізнес-процесу.

Надалі id та checksum можна використати у бізнес-процесі для збереження та подальшого отримання документа з об’єктного сховища даних CEPH.

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

Таблиця 1. Структура тіла відповіді
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
}
Максимальний розмір файлу

Максимальний розмір файлу (max-remote-file-size), який може обробити Сервіс цифрових документів, дорівнює 100 MB. У разі, якщо digitalDocuments.maxFileSize не вказано явним чином, приймається значення у 100 MB як системне обмеження.

Формати файлів, що підтримуються

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

  • "application/pdf": "pdf"

  • "image/png": "png"

  • "image/jpeg": "jpg", "jpeg"

  • "text/csv": csv

  • "application/octet-stream": "asics"

  • "application/pkcs7-signature": "p7s"

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

Скопіюйте вміст .bpmn-файлу та вставте на вкладці Код у розділі Моделі процесів Кабінету адміністратора регламентів.

3.2. Моделювання бізнес-процесу

3.2.1. Скрипт для отримання цифрового документа за зовнішнім посиланням

  1. Створіть скрипт-задачу (Script Task).

  2. У полі Name введіть назву задачі. Наприклад, Отримання файлу з іншої системи.

  3. У полі Script відкрийте Редактор скриптів та напишіть Groovy-скрипт для обробки даних.

    dig doc remote url 1

  4. Використовуйте функцію save_digital_document_from_url (), щоб отримати цифровий документ зі сторонньої системи.

    • Передайте як вхідні параметри функції посилання та назву файлу. Це можна зробити, наприклад, визначивши параметри url та fileName як змінні, присвоївши їм відповідні значення, та використавши у функції.

      dig doc remote url 2

    • Або можна відразу сформувати об’єкт та призначити йому як значення функцію з відповідними вхідними параметрами.

      dig doc remote url 3

      Після обробки отриманих даних на стороні Сервісу цифрових документів, до бізнес-процесу повертаються метадані документа, збереженого у тимчасовому сховищі проміжних даних — id та checksum.

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

    Результат виконання скрипту зберігаємо до змінної documentMetadata, яку надалі використовуємо в іншому скрипті для формування об’єкта, що зберігатиме метадані отриманого документа до постійного сховища CEPH.
    dig doc remote url 4

3.2.2. Користувацька задача для виводу файлу з БД на UI-форму

Після збереження об’єкта із метаданими цифрового документа до основної БД, знаходимо запис за його ID та передаємо об’єкт як змінну на UI-форму Кабінету користувача.

  1. Створіть користувацьку задачу (User Task).

  2. Введіть назву задачі. Наприклад, Переглянути файл з БД на формі.

  3. Застосуйте шаблон делегата зі списку доступних — User form.

  4. У полі Form key введіть службову назву форми, до якої необхідно передати дані. Наприклад, file-saved-from-ext-system-view.

  5. У полі Assignee вкажіть токен ініціатора процесу — ${initiator}.

  6. У полі Form data pre-population вкажіть дані об’єкта із цифровим документом (у нашому прикладі — це зображення), який виведеться на форму. Наприклад, ${response.value.responseBody}.

    dig doc remote url 5

3.3. Моделювання UI-форм

Отриманий цифровий документ за зовнішнім посиланням можна відобразити на UI-формі бізнес-процесу та завантажити на локальну машину для подальшого використання.

Скористайтеся готовою формою для безпосереднього ознайомлення із деталями:

Скопіюйте вміст .json-файлу та вставте на вкладці Код у розділі UI-форми Кабінету адміністратора регламентів.

  1. Створіть UI-форму для бізнес-процесу.

  2. У Конструкторі налаштуйте компонент Text Field для виводу назви файлу.

  3. Далі налаштуйте компонент File для отримання даних (цифрового документа) зі сховища CEPH.

    dig doc remote url 6

    Перейдіть на вкладку API та у полі Property Name вкажіть ключ для пошуку запису в об’єктному сховищі. Наприклад, image.

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

    dig doc remote url 7

    Результат, що повертається на UI-форму, може виглядати так:

    Приклад 2. Цифровий документ, отриманий із CEPH по ключу image

    dig doc remote url 8

3.4. Використання у Кабінеті посадової особи

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

  1. Увійдіть до Кабінету посадової особи.

  2. Запустіть змодельований бізнес-процес.

    dig doc remote url 9

  3. Завантажте отриманий файл на локальну машину для подальшого використання.

    dig doc remote url 10

4. Пов’язані сторінки

5. Додаткові відеоматеріали