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

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

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

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

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

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

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

2. Базові принципи та мотивація для редизайну

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

  • Забезпечення високого рівня сohesion при дизайні сервісів платформи

  • Стандартизація типів сховищ для даних, якими оперує Платформа

  • Тип сховища для даних має відповідати нефункціональним вимогам, які виставляються до операцій над цими даними

3. Обсяг редизайну сервісів

В рамках редизайну, для реалізації функціональних сценаріїв необхідно ввести наступні нові компоненти:

  • Сервіс постачання UI-форм (form-schema-provider)

  • Сервіс валідації даних UI-форм (form-submission-validation)

Кожен компонент має бути інтегрованим в екосистеми реєстру та реалізовувати повною мірою усі cross-cutting вимоги.

Компоненти, які підлягають змінам:

  • Сервіс управління процесами користувачів (user-process-management)

  • Сервіс управління задачами користувачів (user-task-management)

  • Сервіс цифрових документів (digital-documents)

  • Пайплайн публікації регламенту (jenkins)

Компоненти, які підлягають заміщенню / видаленню з виконанням міграції даних:

  • Сервіс постачання UI-форм (form-management-provider)

  • Сховище даних схем UI-форм (form-management-provider-db)

4. Цільовий дизайн системи

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

form-schema-provider

4.1. Компоненти системи та їх призначення в рамках цільового дизайну

Компонент Службова назва Сценарії використання

Сервіс валідації даних UI-форм

form-submission-validation

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

Сервіс постачання UI-форм

form-schema-provider

Обробка запитів на отримання схем UI-форм з боку кабінетів користувачів

Сервіс управління задачами користувачів

user-task-management

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

Сервіс управління процесами користувачів

user-process-management

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

Сервіс-шлюз для інтеграції з зовнішніми системами

bp-webservice-gateway

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

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

digital-documents

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

Пайплайн публікації регламенту

jenkins

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

Розподілене in-memory сховище даних

redis

Зберігання / Кешування даних схем UI-форм

4.2. Налаштування політик міжсервісної взаємодії

В рамках реалізації вимог, необхідно додати відповідні мережеві політики NetworkPolicy, які дозволяють взаємодію для наступних компонентів:

  • kong → form-schema-provider

  • form-submission-validation → form-schema-provider

  • user-process-management → form-submission-validation

  • user-task-management → form-submission-validation

  • digital-documents → form-submission-validation

  • form-schema-provider → redis

4.3. Сервіс постачання схем UI-форм

Даний Java-сервіс відповідає за обробку запитів на отримання схем UI-форм для задач бізнес-процесів. У якості сховища даних використовується Redis Sentinel.

Детальніше з описом Redis Sentinel можно ознайомитись у розділі Відмовостійке key-value сховище даних на базі Redis Sentinel.

4.3.1. Зберігання даних UI-форм

UI-форми зберігаються за допомогою Redis Hash-структури з використанням підходу сегрегації об’єктів через Keyspaces-префікси (<keyspace>:<key>).

Для об’єктів схем UI-форм використовується bpm-form-schemas keyspace.

Приклад паттерну генерації ключа для запису / читання об’єкту:
bpm-form-schemas:{form-key}

4.3.2. API доступу до схем UI-форм

Отримання доступу до API можливе лише в рамках виконання запиту автентифікованого користувача в системі
4.3.2.1. Отримання схеми UI-форми за ідентифікатором [Публічний]
Данний API-роут є публічним та має бути опублікованим для зовнішнього доступу через окремий Kong Route.

GET /api/forms/{form-key}

Параметр Тип Частина запиту Опис

X-Access-Token

JWT

HTTP заголовок

Токен доступу користувача

form-key

Текстовий

Параметр запиту

Унікальний ідентифікатор схеми UI-форми
Приклад відповіді
{
  "type": "form",
  "display": "form",
  "title": "Назва форми задачі",
  "name": "form-key",
  "path": "form-key",
  "components": [
  ]
}
Таблиця 1. Коди помилок
Код Опис

200

OK з поверненням результату даних схеми UI-форми

400

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

401

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

404

Схема UI-форми за вказаним {form-key} відсутня

500

Серверна помилка обробки запиту
4.3.2.2. Створення нової схеми UI-форми [Внутрішній]
Призначенням API-роута є службове використання Пайплайном публікації регламенту для наповнення даними сховища даних схем UI-форм (redis). Роут не доступний для зовнішнього доступу через Kong.

POST /api/forms/

Параметр Тип Частина запиту Опис

X-Access-Token

JWT

HTTP заголовок

Токен доступу користувача
Приклад тіла запиту
{
  "type": "form",
  "display": "form",
  "title": "Назва форми задачі",
  "name": "form-key",
  "path": "form-key",
  "components": [
  ]
}
Таблиця 2. Коди помилок
Код Опис

201

Created з поверненням результату даних схеми UI-форми

400

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

401

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

500

Серверна помилка обробки запиту
4.3.2.3. Внесення змін до існуючої схеми UI-форми [Внутрішній]
Призначенням API-роута є службове використання Пайплайном публікації регламенту для наповнення даними сховища даних схем UI-форм (redis). Роут не доступний для зовнішнього доступу через Kong.

PUT /api/forms/{form-key}

Параметр Тип Частина запиту Опис

X-Access-Token

JWT

HTTP заголовок

Токен доступу користувача

form-key

Текстовий

Параметр запиту

Унікальний ідентифікатор схеми UI-форми
Приклад тіла запиту
{
  "type": "form",
  "display": "form",
  "title": "Назва форми задачі",
  "name": "form-key",
  "path": "form-key",
  "components": [
  ]
}
Таблиця 3. Коди помилок
Код Опис

200

OK з поверненням результату даних схеми UI-форми

400

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

401

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

404

Схема UI-форми за вказаним {form-key} відсутня

500

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

4.4. Сервіс валідації даних UI-форм

Даний NodeJS-сервіс відповідає за валідацію даних згідно правил, визначених у схемі UI-форми за допомогою бібліотеки formio.js.

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

Детальніше з документацією бібліотеки Form.IO можна ознайомитись за посиланням.

4.4.1. API валідації даних UI-форм

Отримання доступу до API можливе лише в рамках виконання запиту автентифікованого користувача в системі. API-роути не доступні для зовнішнього доступу через Kong та використовуються лише внутрішніми сервісами реєстру.
4.4.1.1. Валідація даних згідно визначених у схемі UI-форми правил (Внутрішній)

POST /api/form-submissions/{form-key}/validate

Параметр Тип Частина запиту Опис

X-Access-Token

JWT

HTTP заголовок

Токен доступу користувача

form-key

Текстовий

Параметр запиту

Унікальний ідентифікатор схеми UI-форми, відносно якої необхідно провести валідацію даних
Приклад тіла запиту з даними UI-форми
{
  "data": {
    "field-key1": "Joe",
    "field-key2": "joe@example.com",
    "field-key3": "123123123"
  }
}
Приклад відповіді у разі помилок валідації даних
{
  "name": "ValidationError",
  "details": [
    {
      "message": "Name is required",
      "level": "error",
      "path": [
        "name"
      ],
      "context": {
        "validator": "required",
        "setting": true,
        "key": "name",
        "label": "Name",
        "value": ""
      }
    },
    {
      "message": "Edrpou must have at least 2 characters.",
      "level": "error",
      "path": [
        "edrpou"
      ],
      "context": {
        "validator": "minLength",
        "setting": 2,
        "key": "edrpou",
        "label": "Edrpou",
        "value": "1"
      }
    }
  ]
}
Таблиця 4. Коди помилок
Код Опис

200

OK

400

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

401

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

422

Помилка валідації даних відносно схеми UI-форми

500

Серверна помилка обробки запиту
Після виконання редизайну сервісів, необхідно провести редизайн API валідації задля забезпечення консистентності контрактів по поверненню помилок валідації.
4.4.1.2. Валідація даних окремого поля згідно визначених у схемі UI-форми правил (Внутрішній)

POST /api/form-submissions/{form-key}/fields/{field-key}/validate

На даний момент підтримується лише валідація файлових полів. У разі, якщо {field-key} належить полю іншого типу, система повинна повернути 501 (NOT_IMPLEMENTED).
Параметр Тип Частина запиту Опис

X-Access-Token

JWT

HTTP заголовок

Токен доступу користувача

form-key

Текстовий

Параметр запиту

Унікальний ідентифікатор схеми UI-форми

field-key

Текстовий

Параметр запиту

Унікальний ідентифікатор поля в межах UI-форми
Приклад тіла запиту з даними про завантажений файл UI-форми для валідації
{
  "documentKey": "",
  "filename": "",
  "contentType": "",
  "size": 0
}
Приклад відповіді для валідації файлових полів
{
  "traceId": "<trace-id>",
  "code": 422,
  "message": "The type of the downloaded file is not supported.",
  "details": []
}
Таблиця 5. Коди помилок
Код Опис

200

OK з поверненням результату даних схеми UI-форми

400

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

401

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

404

Схема UI-форми за вказаним {form-key} відсутня

500

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

501

Операція не підтримується системою

4.5. Пайплайн публікації регламенту

Для наповнення даними нового сховища схем UI-форм bpm-form-schemas Redis keyspace в рамках публікації регламенту, необхідно внести зміни у Stage upload-form-changes з використанням внутрішнього API новоствореного сервісу Сервісу постачання UI-форм (form-schema-provider).

5. Бекапування та відновлення даних схем UI-форм

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

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

6. Міграція даних схем UI-форм

На данний момент, схеми UI-форм реєстру зберігаються у сховищі MongoDB form-management-provider-db.

В рамках переходу до нової версії, необхідно провести наповнення даними нового сховища bpm-form-schemas Redis keyspace для кожного реєстру.

6.1. Процедура міграції опція №1:

  • Отримання усіх файлів схем UI-форм регламенту реєстру з <registry-regulation>/forms директорії

  • Створення відповідних записів схем UI-форм через внутрішній API Сервісу постачання UI-форм з використанням алгоритму, визначеного у UploadFormChanges.groovy відповідного кроку Пайплайну публікації регламенту

6.2. Процедура міграції опція №2:

  • Сформувати Gerrit MR зі змінами типу: touch <<registry-regulation>/forms/*.json>

  • Інтегрувати Gerrit MR у master-гілку, таким чином ініціювати запуск "Пайплайну публікації регламенту"

  • Дочекатися проходження кроку upload-form-changes та перевірити наявність записів у bpm-form-schemas Redis keyspace