Історичність виконання бізнес-процесів

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

1. Загальний контекст

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

Додатково, для реалізації вимог аудиту, формується окремий лог значущих подій History Event Stream, який за замовчуванням зберігається в History Database групу таблиць сховища.

Об’єм та рівень генерації подій налаштовується за допомогою HistoryLevel, який визначається за допомогою властивості camunda.bpm.history-level

Властивість camunda.bpm.history-level може бути визначена тільки один раз при первинному запуску додатку Camunda. Для того, щоб змінити цю властивість, треба також змінити рівень історичних подій у базі даних Camunda

UPDATE ACT_GE_PROPERTY SET VALUE_ = ?
WHERE NAME_ = 'historyLevel';
Можливі значення camunda.bpm.history-level:

  • NONE (VALUE_ = 0) — запис історичних подій в БД не проводиться, таким чином мінімізується вплив на швидкодію

  • ACTIVITY (VALUE_ = 1) — генеруються значущі історичні події над об’єктами: PROCESS, ACTIVITY, TASK

  • AUDIT (VALUE_ = 2) — додатково генеруються події над змінними БП

  • FULL (VALUE_ = 3) — додатково генерується історія змін змінних БП. Не рекомендовано для використання по причині найбільшого впливу на швидкодію

Зберігання історичних даних у сховище History Database є синхронним, а об’єм та рівень генерації подій налаштовується за допомогою HistoryLevel. Важливим також є той факт, що ріст історичних даних не обмежено за замовчуванням.

На даній діаграмі послідовності схематично зображено алгоритм дій фіксації історичних подій у процесі виконання БП:

Diagram

2. Антипаттерни використання історичності

Існує декілька антипаттернів використання історичності, які напряму впливають на швидкодію Сервісу виконання бізнес-процесів:

  • Використання History Database у якості сховища довгострокового збереження історичних даних з ціллю подальшого формування пошукових запитів

  • Використання надлишкового рівня логування подій HistoryLevel, який спричиняє суттєвий ріст кількості синхронних операцій на збереження та ріст об’єму історичних даних

  • Відсутність контролю за ростом об’єму історичних даних в History Database

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

  • Використання History Database для обслуговування сценаріїв перегляду історичних даних через кабінет користувача

3. Принципи, закладені в дизайн рішення підтримки історичності

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

  • Налаштування мінімально достатнього для обслуговування системи адміністратором та службою підтримки рівня логування подій HistoryLevel

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

  • Обмеження життєвого циклу історичних даних (TTL) часом виконання відповідних БП з метою використання даних у якості допоміжних для служби підтримки

  • Формування окремого потоку значущих історичних подій виконання БП та їх асинхронна публікація через брокера повідомлень Kafka з ціллю подальшої обробки та збереження

  • Обробка повідомлень історичних подій БП, отриманих через брокера повідомлень Kafka та їх збереження в окреме Сховище історичних даних виконання БП у денормалізованій формі

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

  • Реалізація сценаріїв перегляду історичних даних з використанням Сховище історичних даних виконання БП

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

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

bpm history

4.1. Компоненти обслуговування історичності

4.1.1. Публікація історичних подій

З метою мінімізації впливу на швидкодію виконання бізнес-процесів та формування окремого сховища історичних даних, необхідно реалізувати Process Engine Plugin з компонентом Process History Event Publisher, який буде обробляти події з HistoryLevel=AUDIT від BPMN Core Engine та публікувати їх в окремий топік брокера повідомлень Kafka.

Розглянути можливість реалізації кастомного рівня логування історичних подій для публікації повідомлень у Kafka згідно з наступними правилами:

Ресурс Тип події Ідентифікатор ресурсу Операція збереження

Process Instance

START, UPDATE, END

-

INSERT OR UPDATE BPM_HISTORY_PROCESS BY PROCESS_INSTANCE_ID

Task Instance

CREATE, UPDATE, COMPLETE

-

INSERT OR UPDATE BPM_HISTORY_TASK BY ACTIVITY_INSTANCE_ID

Variable Instance

CREATE, UPDATE, DELETE

Системні змінні: sys-var-process-completion-result, sys-var-process-excerpt-id

UPDATE BPM_HISTORY_PROCESS BY PROCESS_INSTANCE_ID

4.1.2. Збереження опублікованих історичних подій

З метою збереження історичних даних виконання бізнес-процесів, необхідно реалізувати компонент User Process History Event Subscriber, який буде відповідальний за обробку повідомлень топіка історичних подій брокера повідомлень Kafka та подальше збереження в окреме сховище у денормолізованому вигляді.

4.1.3. API доступу до історичних даних

З метою надання користувачам кабінетів доступу до їх персональних історичних даних про виконання бізнес-процесів та задач, необхідно реалізувати окремий компонент User Process History Management, який надає необхідний API для обслуговування історичних запитів автентифікованих користувачів.

4.2. Взаємодія компонентів системи

На даній діаграмі послідовності схематично зображено алгоритм дій фіксації історичної події у процесі виконання БП:

Diagram

5. API доступу до історичних даних виконання бізнес-процесів користувача

5.1. Отримання поточних ініційованих бізнес-процесів

Отримання доступу до даних можливе лише в рамках виконання запиту автентифікованого користувача в системі.

Ідентифікатор користувача, отриманий з X-Access-Token HTTP-заголовка запиту, безумовно використовується у якості обов’язкового критерія для формування вибірки даних за полем "startUserId".

При формуванні запитів на вибірку даних бізнес-процесів безумовно додається критерій на отримання БП верхнього рівня (SUPER_PROCESS_INSTANCE_ID IS NULL)

GET /api/process-instances

Параметр Тип Частина запиту Опційність Значення за замовчуванням Опис

X-Access-Token

JWT

HTTP заголовок

Ні

-

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

offset

Числовий

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

Так

0

Зміщення запису

limit

Числовий

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

Так

10

Обмеження кількості записів

sort

Текстовий

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

Так

desc(endTime)

Поле та порядок сортування записів. Приклад: asc(<field>) / desc(<field>)
Приклад відповіді
[
    {
      "processInstanceId":  "",
      "superProcessInstanceId": "",
      "processDefinitionId": "",
      "processDefinitionKey": "",
      "processDefinitionName": "",
      "businessKey": "",
      "startTime": "",
      "startUserId": "",
      "status": {
        "code": "",
        "title": ""
      }
    }
]
Таблиця 1. Коди помилок
Код Опис

200

OK з поверненням результату виконання запиту

400

Некоректно сформований запит (неправильний формат даних)

401

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

500

Серверна помилка обробки запиту
Діаграма послідовності запиту поточних даних бізнес-процесів
Зображення 1. Діаграма послідовності запиту поточних даних бізнес-процесів
Таблиця 2. Локалізація статусів
Технічний статус Локалізований статус

ACTIVE

У виконанні

PENDING

Очікує виконання задачі

SUSPENDED

Призупинено адміністратором

5.2. Отримання історії ініційованих бізнес-процесів

Отримання доступу до історичних даних можливе лише в рамках виконання запиту автентифікованого користувача в системі.

Ідентифікатор користувача, отриманий з X-Access-Token HTTP-заголовка запиту, безумовно використовується у якості обов’язкового критерія для формування вибірки даних за полем "startUserId".

При формуванні запитів на вибірку історичних даних бізнес-процесів безумовно додається критерій на отримання БП верхнього рівня (SUPER_PROCESS_INSTANCE_ID IS NULL)

GET /api/history/process-instances

Параметр Тип Частина запиту Опційність Значення за замовчуванням Опис

X-Access-Token

JWT

HTTP заголовок

Ні

-

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

offset

Числовий

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

Так

0

Зміщення запису

limit

Числовий

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

Так

10

Обмеження кількості записів

sort

Текстовий

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

Так

desc(endTime)

Поле та порядок сортування записів. Приклад: asc(<field>) / desc(<field>)
Приклад відповіді
[
    {
      "processInstanceId":  "",
      "superProcessInstanceId": "",
      "processDefinitionId": "",
      "processDefinitionKey": "",
      "processDefinitionName": "",
      "businessKey": "",
      "startTime": "",
      "endTime": "",
      "startUserId": "",
      "excerptId": "",
      "status": {
        "code": "",
        "title": ""
      }
    }
]
Таблиця 3. Коди помилок
Код Опис

200

OK з поверненням результату виконання запиту

400

Некоректно сформований запит (неправильний формат даних)

401

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

500

Серверна помилка обробки запиту
Діаграма послідовності запиту історичних даних бізнес-процесів
Зображення 2. Діаграма послідовності запиту історичних даних бізнес-процесів
Таблиця 4. Локалізація статусів
Технічний статус Локалізований статус

completionResult != null

Значення completionResult

COMPLETED

Надання послуги завершено

EXTERNALLY_TERMINATED

Відмінено адміністратором

5.3. Отримання історії виконаних задач бізнес-процесів

Отримання доступу до історичних даних можливе лише в рамках виконання запиту автентифікованого користувача в системі.

Ідентифікатор користувача, отриманий з X-Access-Token HTTP-заголовка запиту, безумовно використовується у якості обов’язкового критерія для формування вибірки даних за полем "assignee".

GET /api/history/tasks

Параметр Тип Частина запиту Опційність Значення за замовчуванням Опис

X-Access-Token

JWT

HTTP заголовок

Ні

-

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

offset

Числовий

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

Так

0

Зміщення запису

limit

Числовий

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

Так

10

Обмеження кількості записів

sort

Текстовий

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

Так

desc(endTime)

Поле та порядок сортування записів. Приклад: asc(<field>) / desc(<field>)
Приклад відповіді:
[
    {
      "activityInstanceId":  "",
      "taskDefinitionKey": "",
      "taskDefinitionName": "",
      "processInstanceId": "",
      "processDefinitionId": "",
      "processDefinitionKey": "",
      "processDefinitionName": "",
      "startTime": "",
      "endTime": "",
      "assignee": ""
    }
]
Таблиця 5. Коди помилок
Код Опис

200

OK з поверненням результату виконання запиту

400

Некоректно сформований запит (неправильний формат даних)

401

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

500

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

6. Налаштування історичності даних в Сервісі виконання бізнес-процесів

6.1. Фіксація історичних подій бізнес-процесів

В процесі експлуатації системи може виникати необхідність залучення служби підтримки для дослідження помилок та причин зупинки виконання бізнес-процесів користувачів. Для забезпечення можливостей використання адміністративного інтерфейсу Camunda Cockpit з метою перегляду стану бізнес-процесу та його змінних рекомендовано встановлення рівня логування історичних подій за необхідністю за допомогою властивості camunda.bpm.database-history-level.

Можливі значення camunda.bpm.database-history-level:

  • NONE (запис історичних подій в БД не проводиться, таким чином мінімізується вплив на швидкодію)

  • ACTIVITY (фіксуються значущі історичні події над об’єктами: PROCESS, ACTIVITY, TASK)

  • AUDIT (додатково фіксуються події над змінними БП)

  • FULL (додатково логується історія змін змінних БП. Не рекомендовано для використання по причині найбільшого впливу на швидкодію)

За замовченням, рекомендовано встановити наступні налаштування:

  • camunda.bpm.history-level: AUDIT

  • camunda.bpm.database-history-level: ACTIVITY

Налаштування потребують корегування в залежності від стабільності системи та необхідності підвищення швидкодії / рівня деталізації подій в системі.
З метою подальшої оптимізації швидкодії, існує можливість підключення кастомного рівня логування історичних подій у вигляді реалізації TypeBasedHistoryLevel інтерфейсу та реєстрації в Process Engine конфігурації.
Для визначення рівня фіксації історичних подій не слід використовувати camunda.bpm.history-level оскільки ця проперті визначає рівень створення історичних подій, а не рівень фільтрування їх перед обробленням. Слід використовувати кастомну проперті camunda.bpm.database-history-level.

6.2. Автоматичне видалення історичних подій

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

Для поліпшення швидкодії та зменшення росту об’єму історичних даних, необхідно впровадити наступні налаштування для Сервісу виконання бізнес-процесів задля впровадження автоматичного процесу видалення застарілих даних за Removal-Time-based стратегією:

Налаштування Значення Опис

historyCleanupEnabled

true

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

historyCleanupStrategy

removalTimeBased

Стратегія видалення історичних даних за принципом removal time = base time + TTL

historyRemovalTimeStrategy

end

Встановлення base time для формування removal time часу видалення історичних даних БП

historyTimeToLive

P1D

Встановлення TTL для формування removal time часу видалення історичних даних БП

historyCleanupBatchWindowStartTime

20:00

Ініціювання процесу автоматичного видалення кожного дня, починаючи з вказаного часу

historyCleanupBatchWindowEndTime

22:00

Закінчення автоматичного видалення кожного дня у вказаний час

historyCleanupDegreeOfParallelism

1

Ступінь паралелізації процесу видалення (кількість залучених потоків)

historyCleanupBatchSize

500

Кількість екземплярів БП для яких виконується видалення історичних даних в рамках однієї транзакції

7. Модель історичних даних виконання бізнес-процесів

У контексті роботи з історичними даними, існує два основних сценарії взаємодії користувача через кабінет:

  • Отримання історії ініційованих користувачем та завершених бізнес-процесів

  • Отримання історії виконаних задач користувача

Для оптимізації виконання запитів, історичні дані необхідно зберігати у денормалізованому вигляді в окремому сховищі:

  • BPM_HISTORY_PROCESS - історичні дані бізнес-процесів

  • BPM_HISTORY_TASK - історичні дані задач

Відношення/зв’язок між таблицями не встановлено навмисно, оскільки в результаті денормалізації містять весь необхідний набір атрибутів для обслуговування історичних запитів та наповнюються даними незалежно одна від одної.
Diagram