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

Выпуски Q.BPM

registry-new.diasoft.ru/release/qbpmui:25012702
registry-new.diasoft.ru/release/qbpmdesigner:24080705
registry-new.diasoft.ru/release/database-qbpmdesigner:24080705
registry-new.diasoft.ru/release/qbpmcockpit:25021006
registry-new.diasoft.ru/release/database-qbpmcockpit:25021006
registry-new.diasoft.ru/release/dqhumantask:25030501
registry-new.diasoft.ru/release/database-dqhumantask:25030501
registry-new.diasoft.ru/release/humantaskui:25031207
registry-new.diasoft.ru/release/qbpetqbpmplayer:25022402
registry-new.diasoft.ru/release/database-qbpetqbpmplayer:25022402

Выпуски Q.UN Пользовательские уведомления (User Notifications)

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

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

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

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

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

3. Зафиксировать изменения. Начнется сборка модуля на обновленном образе
4. Дождаться успешного завершения сборки
5. Обновить модуль на стенде

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

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

Режим работы плеера RUN/DEV/PROD

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

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

При этом контроллеры в 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 согласно описанию выше

Статус 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 на стенде пустой либо имеет некорректное содержание. Необходимо проверить его содержимое на стенде.

Parameter not found: ExpirationDate

Решение: Проверить настройки лицензии

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

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

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

ENGINE-01011 Cannot deploy process definition <someProcess>: there already is a message event subscription for the message with name <someTopicName>

Решение: Проверить в БД Q.BPM Player таблицу act_ru_event_subscr на наличие данных с топиком из лога. Запись с проблемным топиком необходимо удалить из БД.

ENGINE-09005 Could not parse BPMN process

Решение: проверить репозиторий Q.BPM Player на наличие ошибок в диаграммах. Удалить невалидные диаграммы или исправить ошибки. Пересобрать Q.BPM Player.

Авторизация

Error creating bean with name 'springSecurityFilterChain' defined

No qualifying bean of type 'org.springframework.security.oauth2.jwt.JwtDecoder' available: expected single matching bean but found 2: mdpAuthJwtDecoder,fakeJwtDecoder

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, проверить настройки авторизации

Kafka

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

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

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

Failed to create new KafkaAdminClient

Invalid url in bootstrap.servers: qkafka

Решение: Проверить корректность настроек KAFKA_HOST, KAFKA_PORT, KAFKA_URL на стенде

Незаполненные параметры

cause[1]: Could not resolve placeholder 'LPATH' in value "${LPATH}"

Invalid url in bootstrap.servers: ${KAFKA_HOST}:${KAFKA_PORT}​

Решение: Ошибки такого вида говорят о незаполненных или о неправильных значениях указанных в ошибке параметров

Неактуальные версии сервисов платформы В интерфейсе 404 при переходе по пункту меню
Например: Возвращается 404 /api/humantaskui/q-bpm-human-task-list/main.js

Решение: Проверить актуальность платформенных сервисов

Не запускается qbpmdesigner

Expected one result (or null) to be returned by selectOne(), but found: 2

Решение: Проверить на дубли таблицу act_re_procdef

Ошибка 504 в интерфейсе

Http failure response for /api/dqhumantask/dqhumantask/v1/default/human-tasks/counts?wait=true:504 Gateway Time-out

Решение: увеличить значение параметров GATEWAY_CONNECT_TIMEOUT и GATEWAY_RESPONCE_TIMEOUT

Параметры Kafka

spring.kafka.consumer.max-poll-records
По умолчанию значение 500.
Параметр определяет максимальное количество сообщений, которые потребитель (consumer) может получить за один раз. Важно для управления нагрузкой на сервис и оптимизации обработки сообщений.

spring.kafka.consumer.properties.session.timeout.ms
По умолчанию значение 10000 (10 сек).
Параметр указывает время, в течение которого потребитель должен отправить heartbeat (сигнал о том, что он активен) брокеру. Если брокер не получает heartbeat в течение этого времени, он считает, что потребитель отключился и может перераспределить его партиции другим активным потребителям.

KAFKA_PRODUCER_MAX_REQUEST_SIZE или spring.kafka.producer.properties.max.request.size
По умолчанию значение 1000000 байт (1 МБ)
Параметр устанавливает предел на размер одного запроса (сообщения), который продюсер может отправить. Если размер сообщения превышает это значение, продюсер получит ошибку.

spring.kafka.consumer.properties.heartbeat.interval.ms
По умолчанию значение 3000 (3 сек).
Параметр определяет, как часто потребитель будет отправлять heartbeat-сообщения брокеру. Если брокер не получает heartbeat в течение установленного времени session.timeout.ms, он считает, что потребитель отключился.