Настройка администратора

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

Выпуски Q.BPM

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

  • registry-new.diasoft.ru/release/qbpmui:24050501
  • registry-new.diasoft.ru/release/qbpmdesigner:24053001
  • registry-new.diasoft.ru/release/database-qbpmdesigner:24053001
  • registry-new.diasoft.ru/release/qbpmcockpit:24042501
  • registry-new.diasoft.ru/release/database-qbpmcockpit:24042501
  • registry-new.diasoft.ru/release/dqhumantask:24052304
  • registry-new.diasoft.ru/release/database-dqhumantask:24052304
  • registry-new.diasoft.ru/release/humantaskui:24052201
  • registry-new.diasoft.ru/release/qbpetqbpmplayer:24061105
  • registry-new.diasoft.ru/release/database-qbpetqbpmplayer:24061105

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

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

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

  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
Dockerfile-database.txt
Dockerfile-service.txt
  1. Зафиксировать изменения. Начнется сборка модуля на обновленном образе
  2. Если в docker указана версия release, достаточно перезапустить сборку
  3. Обновить модуль на стенде
⚠️

Версии образа в Dockerfile-database.txt и Dockerfile-service.txt обязательно должны совпадать

Параметры 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_*.

empty

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

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

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

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

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

Если в Q.BPM Player не выставлен режим работы (QBPM_MODE=run/dev/prod), в таком случае значение для act_re_procdef.history_ttl_ будет проставляться из qbpmcockpit в параметре QBPM_HISTORY_TIME_TO_LIVE

💡

Таблицы истории выполнения процессов не будут очищены, пока процесс активный.

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

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 - режим отладки
⚠️

В режиме 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):

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

  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
⚠️

Для работы сервисов Q.BPM потребуется установка актуальных версий платформенных сервисов

  • mdpsettings
  • mdpgateway
  • mdpauth
  • mdpemployee
  • mdpdepartments
  • mdpusers
  • mdproles
  • mdprefs
  • mdpsenders
💡

Актуальные версии платформенных сервисов запрашивать у команды "Инструменты и платформа Back-end разработки"

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

После 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. empty
  5. Найти в разделе data параметр license.xml:
  6. empty
  7. Если данный параметр отсутствует - добавить параметр с названием license.xml
  8. В значение параметра добавить все содержимое полученного файла license.xml
  9. Сохранить конфигурацию share-config-volume по кнопке Update
  10. В system-config либо в конфигурацию сервиса добавить параметр LPATH: /share/config/
  11. Проверить значение параметра LPATH в сервисах Q.BPM. При необходимости изменить значение на корректное, либо отключить (удалить) параметр
  12. После настройки параметра перезапустить сервисы Q.BPM
⚠️

Файл лицензии также необходимо подложить в devops_configs вашего проекта в каталог share_templates/config_templates
И убедиться, что в devops_configs в каталоге properties настроен для сервисов параметр LPATH

Настройка аутентификации в 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. Выполнить шаги согласно инструкции (opens in a new tab)

  2. Установить актуальные версии сервисов

  • qbpmdesigner
  • qbpetqbpmplayer
  • dqhumantask
  • qbpmcockpit
  • qunnotification
  • mdpemployee
  • mdpdepartments
  • mdpusers
  • mdproles
  • mdprefs
  1. Если необходим справочник сотрудников и подразделений с qwork - в платформенных сервисах mdpemployee и mdpdepartments в dbsecret настроить подключение к БД qwork

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

  • QOAUTH_MODE
  • RESOURCE_SERVER_ID
  • AUTH_SERVER_PUBLIC_KEY
  1. Убрать параметр AUTH_PROVIDER=digitalq

  2. В системной конфиг-мапе добавить параметр KUBERNETES_LEGACY_MOD=true

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

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

  • KEYCLOAK_AUTH_URL
  • KEYCLOAK_CLIENT_ID
  • KEYCLOAK_CLIENT_SECRET
  • KEYCLOAK_SCOPE
  • KEYCLOAK_GRANT_TYPE
  • TECH_AUTH_SERVICE_NAME // имя сервиса авторизации
  • TECH_USERNAME // логин технического пользователя
  • TECH_PASSWORD // пароль технического пользователя
  1. После выполнения настроек перезапустить сервисы Пример настроенного стенда (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

empty

⚠️

Нельзя выставлять параметры JAVA_XMS и JAVA_XMX выше лимитов в деплойменте сервиса. В таком случае сервис не запустится.

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

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

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

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

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

Failed to pull image "registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101": rpc error: code = NotFound desc = failed to pull and unpack image "registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101": failed to resolve reference "registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101": registry-new.diasoft.ru/dvt/development/dev/qbpmdesigner:24010101: 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 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'

Авторизация

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