Руководство администратора

Выпуски Q.BPM

Актуальные версии образов:

• registry-new.diasoft.ru/release/qbpmui:24062802
• registry-new.diasoft.ru/release/qbpmdesigner:24071606
• registry-new.diasoft.ru/release/database-qbpmdesigner:24071606
• registry-new.diasoft.ru/release/qbpmcockpit:24071205
• registry-new.diasoft.ru/release/database-qbpmcockpit:24071205
• registry-new.diasoft.ru/release/dqhumantask:24070401
• registry-new.diasoft.ru/release/database-dqhumantask:24070401
• registry-new.diasoft.ru/release/humantaskui:24071410
• registry-new.diasoft.ru/release/qbpetqbpmplayer:24071503
• registry-new.diasoft.ru/release/database-qbpetqbpmplayer:24071503

Создание эталонной базы данных проекта

Перед созданием проекта необходимо подготовить эталонную базу данных проекта. Для этого необходимо определить список существующих схем БД, которые будут использоваться в проекте.

Список модулей и их БД:

1. QBPD - Дизайнер бизнес-процессов и бизнес-правил (Business Process Designer): qbpmdesigner
2. QC - Управление бизнес-процессами (Cockpit): qbpmcockpit
3. QHT - Пользовательские задания (Human Task): dqhumantask
4. QBPET - Средства исполнения бизнес-процессов (Q.BPM Player): qbpetqbpmplayer
5. QAL - Список заявок (Application List): qbpmapplist

Создание репозитория и сборки микросервиса на базе Q.BPM Player

Для создания прикладных микросервисов на базе Q.BPM Player должен быть использован базовый образ Q.BPM Player. Алгоритм создания репозитория и сборки для прикладного микросервиса следующий:

• Для каждого разворачиваемого микросервиса на базе Q.BPM Player (далее модуль) в GitLab должен быть создан собственный отдельный репозиторий;

  Структура репозитория микросервиса должна быть следующая: Каталог модуля

  • Проект (main)
    • Ресурсы (resource)
      • Схемы (schemas)
        • Схема – файл .json
      • Процесс – файл .bpmn
  • Docker
    • Dockerfile-database.txt
    • Dockerfile-service.txt
    • properties.properties
  • pom.xml

• В репозитории модуля должен быть расположен каталог проекта «main», где нет java кода, каталог «Docker» и файл pom.xml;

• В каталоге «main» должен быть расположен каталог «resource», где должны содержаться только ресурсы (процесс + схема (объект)). Для хранения схем в каталоге «resource» должен быть выделен каталог «schemas». Хранение схем (объектов) в отдельном каталоге необходимо для обеспечения однозначной идентификации бизнес-объекта, необходимого для запуска модуля. Таким образом, библиотека динамических атрибутов однозначно определяет схему, необходимую для запуска модуля. В частных случаях сервис может стартовать без схем;

• В каталоге «Docker» должны быть расположены Dockerfile-database.txt и Dockerfile-service.txt - инструкции для сборки docker-образа Q.BPM Player. В файлах Dockerfile-database.txt и Dockerfile-service.txt должно быть указано расположение хранилища, где хранится образ Q.BPM Player определенной версии, указано расположение файл.jar и параметры запуска;

• Пример GIT QHT/qhtbpm (opens in a new tab);

• Далее настройка Jenkins файла полностью идентична настройка MSA и процесс выпуска построен точно так же.

Обновление базового образа Q.BPM Player

Для обновления базового образа плеера необходимо:

1. Перейти в репозиторий плеера в каталог docker
2. В файлах Dockerfile-database.txt и Dockerfile-service.txt указать актуальную версию образа из registry-new.diasoft.ru/release

3. Зафиксировать изменения. Начнется сборка модуля на обновленном образе
4. Если в docker указана версия release, достаточно перезапустить сборку
5. Обновить модуль на стенде

Параметры Q.BPM Player:

• QBPM_PROCESS_INPUT_TOPICS - через точку с запятой топики для подписки
• QBPM_PROCESS_OUTPUT_TOPICS - через точку с запятой топики, в которые разрешена отправка (Пример: QBPM_PROCESS_OUTPUT_TOPICS = dsTaskCreateEvent;dsTaskCancelEvent;dsTaskActionEvent)
• QBPM_MODE - режим работы плеера dev/prod/run
• QBPM_DLQ_TOPICS - создание топиков с постфиксом dlq - по умолчанию false (true - создание включено; false - создание выключено)
• QBPM_LIMIT_DEFINITION_VERSIONS_ENABLED - автоудаление бизнес-процессов - по умолчанию false (true - автоудаление включено; false - автоудаление выключено)
• QBPM_LIMIT_DEFINITION_VERSIONS_COUNT - количество сохраненных процессов (по умолчанию 10)

Режим работы плеера dev/prod/run

Реализовано разделение диаграмм по областям/неимспейсам/профилям на два режима работы (в каждом из режимов у диаграмм параметр tenantId будет соответствующий):

1. DEV - все версии диаграмм помечаются специальной меткой. Активизируется job, который "чистит" активные процессы - завершает (будут иметь статус "Внешне завершенный") все активные экземпляры процессов, если они исполняются более 12ч. Также спустя один день исполнения экземпляра процесса по нему очищается история - удаляются записи в сервисе qbpetqbpmplayer таблицы: act_hi_*
2. PROD - режим по умолчанию, платформа работает, как и раньше. Публикуются диаграммы, хранится полная история и т.п.
3. RUN - все версии диаграмм помечаются специальной меткой. Активизируется job, который "чистит" активные процессы - завершает (будут иметь статус "Внешне завершенный") все активные экземпляры процессов, если они исполняются более 5 минут. Очищается история - удаляются записи в сервисе qbpetqbpmplayer таблицы: act_hi_*

При этом контроллеры в Swagger также разделены по профилям и не пересекаются.

Режим, настройка конфигурации QBPM_MODE, устанавливается вручную через конфиги Kubernetes. Эта доработка дает несколько плюсов и решает ряд проблем:

1. Проведение показов и важных презентаций в режиме PROD. Избавляет от демонстрации множества версий, на которых происходила отладка (мусор).
2. В режиме DEV можно удалять версии, как и сколько угодно. Режим PROD для использования финальной, рабочей, стабильной версии диаграммы (без возможности всякого удаления версий диаграмм).
3. Уменьшение потребления памяти сервисом.

Дополнительные возможности - реализация функционала тестового запуска экземпляра диаграммы. Кнопка Play открывает модальное окно, в котором указываются входные и выходные параметры, после чего можно запустить на исполнение экземпляр диаграммы в режиме RUN. Данный режим позволяет отлаживать небольшие "кусочки" большой диаграммы, которые разбиваются на подмножество диаграмм. Таким образом позволяя найти и устранить все дефекты при проектировании. При таком тестовом запуске все активные экземпляры диаграмм будут завершены, если исполняются более 5 минут. Также спустя один день исполнения экземпляра процесса по нему очищается история - удаляются записи в сервисе qbpetqbpmplayer таблицы:act_hi_*.

Для того чтобы произвести тестовый запуск экземпляра процесса, необходимо в модальном окне у входных параметров заполнить столбец "Тестовое значение".

Хранение истории выполнения процессов

Для экономии памяти в БД можно настроить очистку истории выполненных процессов. Количество дней хранения истории выполнения процессов записывается в act_re_procdef.history_ttl_

Задать значение history_ttl_ - History Time To Live можно несколькими способами:

1. Можно полностью выключить хранение истории. В Дизайнере бизнес-процессов в свойствах процесса включить параметр Не хранить историю выполнения процесса. Настраивается отдельно на каждом процессе.
2. Задать количество дней хранения истории. В Дизайнере бизнес-процессов в свойствах процесса задать значение для параметра Время жизни истории. Настраивается отдельно на каждом процессе.
3. Задать в Q.BPM Player режим работы через параметр QBPM_MODE
4. Добавить в Мониторинг бизнес-процессов (qbpmcockpit) параметр QBPM_HISTORY_TIME_TO_LIVE и указать ему значение в днях. (Пример QBPM_HISTORY_TIME_TO_LIVE: P1D)

Возможности логирования и уровни

logging:
    config: classpath:log4j2.xml
level:
    root: ${LOGGING_ROOT_LEVEL:INFO} // логирование абсолютно всего
    ru.diasoft.micro: ${LOGGING_DIASOFT_LEVEL:${LOGGING_ROOT_LEVEL:INFO}} // логирование классов Диасофта
    org.hibernate.type: ${LOGGING_HIBERNATE_LEVEL:INFO} #To log values set TRACE // логирование запросов в БД
    org.apache.kafka.clients: ${LOGGING_KAFKA_LEVEL:INFO} // логирование кафка-клиента
    org.springframework.kafka.listener: ${LOGGING_KAFKA_LEVEL:INFO} // логирование лиснеров
    org.camunda.bpm.engine: ${LOGGING_CAMUNDA_LEVEL:INFO} // логирование всех действий камунды
    org.springframework.transaction: ${LOGGING_TRANSACTION_LEVEL:INFO} // логирование транзакций

Логирование всегда должно быть включено. По умолчанию логирование устанавливает в уровень ERROR, допускается использование всех модулей. Для режима PROD- рекомендуется выставлять уровень ERROR и только на необходимый модуль. Для режима DEV или RUN- рекомендуется выставлять уровень ALL, модуль "root".

Доступные режимы логирования:

• INFO - только информативные сообщения и то, что логируется в коде с уровнем INFO;
• ERROR - выводится информация по всем ошибкам;
• WARN - информация о различных предупреждениях;
• ALL - максимальный уровень, который выводит абсолютно все;
• DEBUG - режим отладки

Q.BPM Руководство по установке и запуску сервисов

Настройка проектного стенда и конфигурации для него в репозитории

devops_configs (opens in a new tab)

Настраивать можно по аналогии с веткой [omniplatform] (https://gitflex.diasoft.ru/devops/devops_configs/-/tree/omniplatform/devops/stages/dev (opens in a new tab)) Необходимо создать свою ветку: название ветки = название неймспейса

Настройка конфигурации сервисов

Примеры общих настроек неймспейса (БД PostgreSQL):

• config.yml - config.yml (opens in a new tab)
• Настройки БД всего стенда - dbservers.properties (opens in a new tab)
• Настройки шлюза - mdpgateway.properties (opens in a new tab)
• Настройки rulelist для работы шлюза в новом формате (opens in a new tab) - rulelist.yaml (opens in a new tab)

Примеры необходимых настроек для модулей:

1. Q.BPM UI (Рутовое приложение)
   • Настройки QBPM UI (стандартная авторизация через mdpauth)
   Пример содержимого конфигурационного файла
   • Настройки QBPM UI (Keycloak авторизация)
   Пример содержимого конфигурационного файла
2. QBPD - Дизайнер бизнес-процессов и бизнес-правил (Business Process Designer)
   qbpmdesigner.properties
3. QC - Управление бизнес-процессами (Cockpit)
   qbpmcockpit.properties
4. QHT - Пользовательские задания (Human Task)
   dqhumantask.properties
5. QHT - Пользовательские задания UI (Human Task UI)
   humantaskui.properties
6. QBPET - Средства исполнения бизнес-процессов (Q.BPM Player)
   qbpetqbpmplayer.properties

Настройка авторизации

Настройка лицензии

После 10.03.2023 в сервисах Q.BPM включена проверка на лицензирование.
Для оформления лицензии необходимо направить запрос на «CTL - входящие обращения ctl@diasoft.ru»

Модули, которые должны быть указаны в лицензии:

• QBPD - Управление бизнес процессами (qbpmdesigner)
• QC - Мониторинг бизнес-процессов (qbpmcockpit)
• QHT - Пользовательские задачи (dqhumantask)
• QBPET - Средства исполнения бизнес-процессов (qbpetqbpmplayer)

Настройка в неймспейсе через Kubernetes

1. Открыть Kubernetes, раздел Config Maps
2. Найти конфигурацию с наименованием share-config-volume
3. Открыть на редактирование
4. 
5. Найти в разделе data параметр license.xml:
6. 
7. Если данный параметр отсутствует - добавить параметр с названием license.xml
8. В значение параметра добавить все содержимое полученного файла license.xml
9. Сохранить конфигурацию share-config-volume по кнопке Update
10. В system-config либо в конфигурацию сервиса добавить параметр LPATH: /share/config/
11. Проверить значение параметра LPATH в сервисах Q.BPM. При необходимости изменить значение на корректное, либо отключить (удалить) параметр
12. После настройки параметра перезапустить сервисы Q.BPM

Настройка аутентификации в Kafka через SSL (Secure Sockets Layer)

Описание параметров

• KAFKA_SECURITY_PROTOCOL - протокол, по которому сервис подключается к брокеру, по умолчанию ”PLAINTEXT для включения SSL необходимо задать значение ”SSL”.
• KAFKA_TRUSTSTORE_LOCATION - путь до хранилища доверенных сертификатов, по умолчанию пустой, значение должно начинаться с указания протокола ”file:// после этого указывается полный путь до файла.
• KAFKA_TRUSTSTORE_PASSWORD - пароль от хранилища доверенных сертификатов, по умолчанию пустой.
• KAFKA_KEYSTORE_LOCATION - путь до хранилища приватных ключей, по умолчанию пустой, правила заполнения аналогично KAFKA_TRUSTSTORE_LOCATION.
• KAFKA_KEYSTORE_PASSWORD - пароль от хранилища приватных ключей, по умолчанию пустой.
• KAFKA_KEY_PASSWORD - пароль от приватного ключа, по умолчанию пустой.

Параметры необходимо добавить в файл с настройками сервиса на стенде и в файл, который загружается на стенд при установке/обновлении сервиса (application.properties или application.yaml)

Настройка сервисов для работы с Keycloak-авторизацией

Для использования ВPM-сервисов на стенде с Keycloak необходимо:

1. Настроить стенд для работы с keycloak

2. Установить актуальные версии Q.BPM сервисов и платформенных сервисов, необходимых для работы Q.BPM

3. В Kubernetes в сервисных конфигурационных файлах добавить параметры

   Параметры

4. Удалить в конфигурационных файлах параметр AUTH_PROVIDER=digitalq

5. В системном конфигурационном файле добавить параметр KUBERNETES_LEGACY_MOD=true

6. В BPM-сервисах включить параметр SECURITY_ENABLED=true

7. Параметры для добавления технического пользователя в Q.BPM Player

   Параметры

8. После выполнения настроек перезапустить сервисы Пример настроенного стенда (opens in a new tab)

Завершающий этап

После выполненных настроек необходимо запустить сборку пересоздания стенда (RecreateNamespace), которая была создана для вашего неймспейса. Должен подняться стенд.

Запуск сервисов

Рекомендуемые значения ресурсов для запуска сервиса:

Проверить настройки в Deployment сервиса в разделе resources/limits. Рекомендуемые лимиты для сервисов Q.BPM:

          resources:
            limits:
              cpu: '2'
              memory: 2Gi

Параметры пула выделения памяти:

JAVA_XMS: 1g
JAVA_XMX: 2g

• JAVA_XMS - начальный пул выделения памяти
• JAVA_XMX - максимальный пул выделения памяти

Сколько выделено памяти, будет видно при запуске сервиса. Если не настроить параметры JAVA_XMS и JAVA_XMX, по умолчанию их значения следующие:

JAVA_XMS: 64m
JAVA_XMX: 512m

Распространенные ошибки при запуске сервисов

Сервис перезапускается с ошибкой Killed в логе:

• Решение: Поднять лимиты в деплойменте сервиса

Сервис перезапускается с ошибкой Java heap space в логе:

• Решение: Проверить настройки JAVA_XMS и JAVA_XMX согласно описанию выше

Сервис не запускается

Error creating bean with name 'springSecurityFilterChain' defined

• Решение: Неправильно заданы параметры ALLOW_ALL_FOR_DEBUG и SECURITY_ENABLED

Статус ImagePullBackOff у пода:

Failed to pull image <image name:tag>: rpc error: code = NotFound desc = failed to pull and unpack image <image name:tag>: failed to resolve reference <image name:tag>: <image name:tag>: not found

Решение: Прописать актуальный образ из реестра образов

JPA_DIALECT

Failed to initialize JPA EntityManagerFactory: Unable to load class [jsonb-node]

Решение: Неправильно задано значение параметра JPA_DIALECT

Лицензия:

Error creating bean with name 'LStart': Invocation of init method failed; nested exception is java.lang.Exception: Signature is invalid

Решение: Неправильно задан параметр LPATH. Проверить значение параметра LPATH. Также данная ошибка может возникать, если файл лицензии неправильной структуры

Error creating bean with name 'LStart': Invocation of init method failed; nested exception is java.lang.Exception: Expired

Решение: Истек срок лицензии. Лицензию необходимо обновить.

Error creating bean with name 'LStart': Invocation of init method failed; nested exception is java.lang.Exception: Error reading file

Решение: Раздел license.xml на стенде пустой либо имеент некорректное содержание. Необходимо проверить его содержимое на стенде.

При невыполненной проливке БД или некорректной проливке в интерфейсе будет возникать ошибка:

ResultSet; SQL [n/a]; nested exception is org.hibernate.exception.SQLGrammarException: could not extract ResultSet

Решение: Проверить лог проливки database. При необходимости выполнить проливку заново. Успешно выполненной проливкой является наличие сообщения: The DB-manager worked SUCCESSFULLY

Q.BPM Player не запускается

The deployment contains definitions with same key '<key value>' (id attribute), this is not allowed

Решение: Открыть репозиторий с bpm-плеером. Проверить процессы в каталоге src/main/resources на наличие повторяющихся ключей. Убрать повторение. Пересобрать bpm-плеер.

Авторизация

Failed to instantiate [javax.servlet.Filter]: Factory method 'springSecurityFilterChain' threw exception; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'mdpAuthJwtDecoder' defined in class path resource [ru/diasoft/micro/mdp/lib/qoauth/QSecurityConfig.class]

Решение: обновить версию mdpauth, проверить настройки авторизации (opens in a new tab)

Сервис не может создать топики:

Failed to create topics. error: Creating topics with default partitions/replication factor are only supported in CreateTopicRequest version 4+. The following topics need values for partitions and replicas: [qpbcd-pbc-ext-bussiness-platform-platform-type-reply]

Решение: В Config Maps сервиса добавить параметр spring.cloud.stream.kafka.binder.replication.factor: '1' Для Kafka версии ниже 2.4 значение -1. На версии от 2.4 значение 1

Отправка сообщения в Kafka

Expiring 1 record(s) for <имя топика>:120000 ms has passed since batch creation

Решение: в параметрах сервиса Kafka выставить настройку min.insync.replicas = 1