Автоматична валідація змін до регламенту

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

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

Цей документ описує валідацію змін до регламенту на прикладі виникнення помилок при збірці pipeline MASTER-build-registry-regulations у реєстрах.

Скористайтеся референтними прикладами моделювання регламенту у демо-реєстрі.

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

Як розгорнути демо-реєстр та отримати приклади моделювання, описано на сторінці Розгортання демо-реєстру із референтними прикладами.

Відповідно до архітектури безпеки Платформи та реєстрів, що на ній розгортаються, регламент кожного реєстру має проходити процедуру перевірки коду (Code Review) перед внесенням змін до цільового репозиторію.

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

З метою уникнення подібних помилок, на Платформі реалізована додаткова автоматична валідація змін.

Автоматична валідація змін до регламенту наразі передбачає:

  1. Перевірку регістрів при налаштуванні зовнішніх ключів у моделі даних.

  2. Перевірку регістрів при налаштуванні ролей посадових осіб.

    Значення параметрів необхідно вказувати у нижньому регістрі, тобто всі символи — з маленької літери. Механізм валідації для обох випадків є однаковим.

  3. Перевірку на дублювання та унікальність атрибутів у формах бізнес-процесів.

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

  5. Перевірку наявності бізнес-процесу в регламенті за значенням ідентифікатора.

При внесенні змін до регламенту (див. Операції з регламентом в Gerrit), автоматично запускається процес збірки файлів регламенту, що має назву MASTER-build-registry-regulations.

Якщо не дотримано критеріїв правильності внесення інформації до регламенту, у процесі складання коду станеться помилка.

2. Перевірка регістрів при налаштуванні зовнішніх ключів у моделі даних

У системі реалізовано регламентну валідацію для перевірки регістрів у значенні параметра foreignKeyName в рамках моделювання структур даних реєстру у каталозі data-model.

Якщо в одному з файлів на рівні Фабрики даних (наприклад, data-model/tablesSubjects.xml, що визначає структуру таблиць та зв’язків між ними) значення параметра зовнішнього ключа foreignKeyName вказано у верхньому регістрі (наприклад, foreignKeyName="FK_suBject_subject_id"), то збірка не пройде валідацію та завершиться помилкою на кроці registry-regulations-validation.

Приклад 1. Приклад. Спрацьовування автоматичної валідації для значення параметра foreignKeyName

Розглянемо приклад спрацьовування автоматичної валідації при внесенні змін до файлу data-model/tablesSubjects.xml.

Виконаємо наступні кроки:

  1. Відкрийте файл data-model/tablesSubjects.xml у середовищі розробки та моделювання регламенту.

  2. В рамках моделювання структур даних, у тегу <constraints>, для атрибута foreignKeyName введіть значення "Fk_subject_subject_id", використовуючи верхній регістр.

  3. Перенесіть локальні зміни до цільового репозиторію в Gerrit (див. Операції з регламентом в Gerrit).

  4. Пройдіть процедуру перевірки коду в Gerrit.

    registry regulations auto validation 4

  5. Виконайте злиття змін (git merge) до master-гілки репозиторію.

    registry regulations auto validation 3

    За фактом злиття змін до master-гілки репозиторію в Gerrit, відбудеться автоматичний запуск процесу збірки внесених змін інструментом Jenkins.

  6. Перейдіть до інтерфейсу Jenkins за відповідним посиланням для перегляду процесу збірки.

    registry regulations auto validation 5

    Збірка завершиться помилкою на кроці registry-regulations-validation.

  7. Відкрийте деталі збірки, натиснувши її номер. Далі перейдіть до журналу подій у консолі (Console Output).

    registry regulations auto validation 8

    registry regulations auto validation 7

  8. Ознайомтеся із причинами виникнення помилки. До консолі виводиться відповідне повідомлення та значення параметра, до якого застосовано валідацію:

    [ERROR] Наступні foreign keys містять символи у верхньому регістрі, що неприпустимо: [Fk_subject_subject_id]

    registry regulations auto validation 1

  9. Прокрутіть бігунок униз сторінки та знайдіть повідомлення про результат невдалої збірки:

    ERROR: Registry regulations files did not pass validation
Finished: FAILURE

    registry regulations auto validation 2

3. Перевірка регістрів при налаштуванні ролей посадових осіб

У системі реалізовано регламенту валідацію для перевірки регістрів для значень параметра name у файлі roles/officer.yml. Допускається лише нижній регістр.

Якщо у файлі roles/officer.yml, на рівні бізнес-процесів, значення параметра name, тобто назву ролі посадової особи, вказано у верхньому регістрі (наприклад, name: Officer), то збірка не пройде валідацію та завершиться помилкою на кроці registry-regulations-validation.

Процес спрацьовування валідації дивіться на прикладі перевірки регістрів у каталозі data-model за посиланням.

4. Перевірка на дублювання та унікальність атрибутів у формах бізнес-процесів

У системі реалізовано регламентну валідацію для перевірки атрибутів name, display, title і type на унікальність у каталозі forms. Валідація призначена для того, щоб коректно генерувати назву, тип і шлях знаходження форми у порталах (Кабінетах).

Якщо значення параметрів не є унікальними та дублюються, то збірка регламенту не пройде валідацію та завершиться помилкою на кроці registry-regulations-validation.

Виділять 2 основних критерії у цьому типі валідації:

  1. Атрибути name, display, title і type не повинні дублюватись у каталозі forms.

    Приклад 2. Приклад. Дублювання атрибута у формі
    {
"path": "add-lab-bp-add-lab",
"path": "add-lab-bp-add-lab"
}

  1. Атрибути name, display, title і type мають бути унікальними у каталозі forms при розгортанні регламенту реєстру.

    Приклад 3. Приклад. Неунікальність атрибута у формі
    {
"title": "Додати інформацію про лабораторію",
"title": "Додати інформацію про кота"
}
Процес спрацьовування валідації дивіться на прикладі перевірки регістрів у каталозі data-model за посиланням.

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

У системі реалізовано регламентну валідацію для перевірки значення атрибута process_definition_id на унікальність у каталозі bp-auth. Валідація призначена для того, щоб коректно визначати ідентифікатор бізнес-процесу, до якого надається доступ користувачу.

Якщо значення атрибута process_definition_id в масиві process_definitions не є унікальним, то збірка не пройде валідацію та завершиться помилкою на кроці registry-regulations-validation, а в журналі виводитиметься опис помилки із текстом: "[Process_id] Process_id не унікальний".

Приклад 4. Приклад. Неунікальність значення атрибута 'process_definition_id'
process_definitions:
    - process_definition_id: 'add-lab'
    - process_definition_id: 'add-lab'
Процес спрацьовування валідації дивіться на прикладі перевірки регістрів у каталозі data-model за посиланням.

6. Перевірка наявності бізнес-процесу в регламенті за значенням ідентифікатора

У системі реалізовано регламенту перевірку наявності бізнес-процесу за значенням атрибута process_definition_id у каталозі bp-auth. Валідація призначена для того, щоб адміністратор регламенту міг внести значення лише наявного в системі бізнес-процесу, до якого необхідно призначити доступ.

Якщо значення атрибута process_definition_id в масиві process_definitions не збігається з ідентифікатором вже змодельованого бізнес-процесу, то збірка не пройде валідацію та завершиться помилкою на кроці registry-regulations-validation.

Приклад 5. Приклад. Значення атрибута 'process_definition_id' для бізнес-процесу, що не існує в реєстрі
authorization:
    realm: 'officer'
    process_definitions:
        - process_definition_id: 'add-lab777777777777777'
        process_name: 'Створення лабораторії'
        process_description: 'Регламент для створення лабораторій'
        roles:
          - officer
Процес спрацьовування валідації дивіться на прикладі перевірки регістрів у каталозі data-model за посиланням.