Валідація порожніх обов’язкових полів на рівні шаблонів у бізнес-процесі

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

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

При моделюванні бізнес-процесів використовуються Шаблони елементів для типових BPMN елементів (сервісні задачі, задачі користувача тощо) з описом відповідного контракту. Для вхідних параметрів такого роду шаблонів налаштовується валідація, яка відпрацьовує на стороні клієнта у Вебінтерфейсі моделювання регламенту. Проте в рамках реалізації правила валідації були застосовані не для всіх необхідних параметрів Шаблонів елементів Через це відсутність обов’язкового поля моделювальник побачить тільки при виконанні бізнес-процесу, а не при його моделюванні. Необхідно застосувати правила валідації в рамках чинного рішення для всіх Шаблонів елементів та додатково розробити механізм серверної валідації.

2. Концепти

  • Шаблони елементів - Camunda element templates, які спрощують процес моделювання бізнес-процесів. Детальніше за посиланням

  • Пайплайн перевірки регламенту - Jenkins Code Review pipeline, який запускається при внесенні змін у версію-кандидат, або безпосередньо в МР в Gerrit

  • Пайплайн публікації регламенту - Jenkins Build pipeline, який запускається при внесенні змін в мастер версію регламенту реєстру

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

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

  • Валідація вхідних параметрів шаблонів задач у Пайплайні перевірки регламенту при моделюванні регламенту

  • Валідація вхідних параметрів шаблонів задач у Пайплайні публікації регламенту при моделюванні регламенту

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

  • Валідація вхідних параметрів шаблонів задач у Пайплайні публікації регламенту при розгортанні регламенту на продакшен оточенні

4. Ролі користувачів

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

  • Адміністратор реєстру

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

5.1. Серверна валідація

  • Серверна валідація Шаблонів елементів проходить за загальними принципами валідації регламенту реєстру на Пайплайні публікації регламенту та Пайплайні перевірки регламенту

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

  • Валідація вхідних параметрів Шаблонів елементів повинна виконуватися за допомогою утиліти registry-regulations-validator-cli

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

  • Для правил валідації використовується та сама версія Шаблонів елементів, що і для Веб-інтерфейсу моделювання регламенту

  • Версія Шаблонів елементів відповідає версії реєстру. Тобто Шаблонів елементів можуть бути змінені тільки в момент оновлення версії реєстру

  • Для збереження Шаблонів елементів використовується ConfigMap, яка оновлюється при оновленні версії реєстру

  • Для опису правил валідації використовується стандарний механізм element templates (constraints)

  • В рамках поточного рішення підтримується тільки notEmpty constraint валідація (100% випадків використання в версії платформи 1.9.5)

5.2. Валідація у Веб-інтерфейсі моделювання регламенту (поточний стан)

  • При розробці шаблону задач можна вказати тип поля вхідного параметра

  • Валідація на клієнті підтримується тільки при вказанні типу вхідного параметра

  • В Camunda версії 7.x є можливість не вказувати тип вхідного параметра

  • На даний момент підтримуються наступні типи вхідних параметрів: String, Text, Boolean, Dropdown and Hidden

  • Для переліку шаблонів задач в платформі потрібне використання типу Map, який не підтримується в Camunda версії 7.x/8.x

  • Якщо не вказувати тип вхідного параметра, у моделювальника буде можливість самостійно обрати тип Map зі списку

  • Типізовані вхідні параметри показуються в секції Custom Properties, в той час, як нетипізовані - в секції Input Parameters

Camunda 8.x не підтримує нетипізовані вхідні параметри. Деталі тут
300
Зображення 1. Панель моделювання. Типізовані параметри
300
Зображення 2. Панель моделювання. Нетипізовані параметри
300
Зображення 3. Панель моделювання. Змішані параметри

6. Високорівневий дизайн рішення

component
Зображення 4. Компонентна діаграма
delivery current
Зображення 5. Діаграма розгортання (поточна)
delivery target
Зображення 6. Діаграма розгортання (цільова)
Валідація параметрів шаблонів елементів у валідаторі регламенту
Зображення 7. Валідація параметрів шаблонів елементів у валідаторі регламенту

7. Журнал рішень

  • Підхід до валідації:

    • Було порівняно 2 підходи до валідації Шаблонів елементів на рівні Пайплайну публікації регламенту та Пайплайну перевірки регламенту:

      • Правила валідації параметрів зберігаються безпосередньо в самому файлі BPMN

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

    • Основні принципи, за якими був обраний 2 підхід:

      • Централізований підхід до зберігання правил валідації

      • Збереження стандартної BPMN/camunda схеми для bpmn файлів для сумісності

      • Унеможливлювання для моделювальника виключити правила валідації при використанні Шаблону елемента

  • Валідація на клієнті:

    • Був проведений POC за результатами якого було виявлено що кастомізація панелі моделювальника можлива тільки при форку бібліотеки bpmn-js-properties-panel

    • Прийнято рішення не форкати бібліотеку для можливості оновлення до нових версій і залишити валідацію на клієнті без змін

    • Подальше розширення панелі моделювальника для автопідказок можливе без форку бібліотеки

  • Підхід до розгортання ConfigMap з переліком Шаблонів елементів переробити і зробити файли з шаблонами частиною registry-configuration компонента

8. Обсяг робіт

8.1. Попередня декомпозиція

  • [DEVOPS] Перенести файли з element templates в репозиторій registry-configuration зі створенням OpenShift ConfigMap

  • [DEVOPS] [FE] Перейменувати ConfigMap з element templates на business-process-modeler-element-templates

  • [FE] Переробити логіку по зчитуванню значення з ConfigMap (замість js файлу - загальний json)

  • [DEVOPS] Додати крок з валідацією регламенту в пайплайн перевірки регламенту

  • [DEVOPS] Прибрати post-upgdade скрипт з common-web-app для наповнення ConfigMap з element templates

  • [BE] Додати валідацію параметрів шаблонів елементів у валідатор регламенту (в скоупі тільки тип обмеження notEmpty з можливим подальшим розширенням)

  • [BE] Додати типізацію вхідних параметрів в Шаблонах елементів з необхідною валідацією (перехід на змішаний підхід вхідних параметрів)

  • [FE] Додати блокування збереження зміни у Веб-інтерфейсі моделювання регламенту якщо не пройшлв валідація по Шаблону елементів

8.2. Поза скоупом

  • Кастомізація панелі моделювальника яка потребує форку бібліотеки:

    • Додавання нового типу вхідного параметру Map

    • Блокування збереження зміни у Веб-інтерфейсі моделювання регламенту якщо не пройшлв валідація по Шаблону елементів

    • Об’єднання двох секція Inputs (нетипізовані вхідні параметри) та Custom Properties (типізовані) в одну

  • Підтримка серверної валідації для типів, які не підтримуються стандартним механізмом element templates

  • Підтримка серверної валідації по патерну (regexp), minLength та maxLength

9. Обмеження рішення

  • Валідація на клієнті залишається неповною через відсутність підтримки типу параметру Map

  • Валідація на бекенді проходить асинхронно в пайплайні публікації (нема швидкого фідбеку для користувача)

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