ProcessMaker полгода спустя: процессы живы, а интеграции уже нет

MAATRIX

Первый месяц после разворачивания ProcessMaker на своём сервере — время, когда всё выглядит идеально: кейсы бегут по маршруту, задачи назначаются нужным людям, скрипт-коннекторы дёргают внешний CRM или бухгалтерскую систему без единой ошибки. Проходит полгода — и внезапно оказывается, что часть автоматических шагов молчит. При этом сам процесс не встал: пользователи по-прежнему открывают формы, согласовывают заявки, двигают кейсы дальше. Ломается не движок BPM, а тонкий слой снаружи — авторизация к внешним системам, доставка вебхуков, совместимость скрипт-задач с обновлённой версией. Разберём, почему это происходит именно так и что проверять, чтобы не узнавать о проблеме от рассерженного менеджера, у которого заявка на закупку неделю как не улетела в 1С.

Почему ядро процессов не замечает, что интеграция сломалась

В ProcessMaker (речь о ветке 4.x, построенной на Laravel/Vue) есть два принципиально разных слоя работы. Первый — движок кейсов: продвижение по BPMN-диаграмме, назначение задач пользователям и группам, хранение переменных процесса. Это синхронная, почти всегда стабильная часть — она опирается на базу данных и веб-сервер и крайне редко деградирует сама по себе за счёт времени. Второй слой — интеграции: скрипт-задачи (Script Task), веб-сервисные задачи (Web Service / Data Connector), исходящие и входящие вебхуки, экспорт в PDF через внешние сервисы, SSO-провайдеры.

Проблема в том, что эти два слоя логически не связаны напрямую. Если скрипт-задача, дёргающая внешний API, падает с ошибкой, кейс в большинстве конфигураций не завершается аварийно — он либо остаётся «висеть» на этом узле, ожидая ретрая или ручного вмешательства, либо (если задача настроена как fire-and-forget через очередь) вовсе продвигается дальше, а ошибка тихо оседает в логе очереди. Пользователь на следующем шаге видит нормальную форму и не подозревает, что где-то позади него не создалась запись в CRM или не ушло уведомление партнёру.

Отсюда и типичная картина через 5-6 месяцев эксплуатации: HR-процесс найма работает, заявки на отпуск согласовываются, а вот интеграция с внешней системой учёта рабочего времени, которая должна была создавать запись при каждом одобрении, молчит уже три недели. Никто не заметил, потому что сам процесс в интерфейсе ProcessMaker выглядит завершённым.

OAuth-токены и Data Connectors: где чаще всего рвётся

Большинство интеграций в ProcessMaker к внешним SaaS-системам (CRM, ERP, почтовые сервисы, платёжные шлюзы, корпоративные каталоги) настроены через Data Connectors с авторизацией по OAuth2 или API-ключу. Именно здесь чаще всего копится проблема, которая стреляет спустя месяцы:

• Refresh-токен истекает по неактивности. У части провайдеров (например, у Google в режиме тестового OAuth-приложения) refresh-токен живёт ограниченный срок и аннулируется, если приложение не прошло верификацию или простаивало без обращений. Если интеграция дергается редко (раз в день или реже), токен может протухнуть, а вы узнаете об этом не в момент истечения, а в момент следующего вызова.
• Клиентский секрет (client secret) имеет срок действия. У Azure AD / Microsoft Entra ID секреты приложений создаются с ограниченным сроком годности (администратор мог поставить, скажем, 12 или 24 месяца при регистрации). Через полгода-год он либо истёк, либо истечёт скоро — и это решение принимал не тот человек, который сейчас поддерживает ProcessMaker.
• Провайдер меняет политику токенов без предупреждения интегратора. Внешние сервисы периодически ужесточают TTL access-токенов, требуют повторного согласия (re-consent) после обновления scope, или меняют формат ответа при обновлении токена — всё это не связано с ProcessMaker напрямую, но выглядит как «интеграция сломалась сама».
• Учётная запись, от имени которой настроен коннектор, теряет права. Уволенный сотрудник, чей персональный аккаунт использовался при первичной настройке OAuth-коннектора (частая практика при быстром старте), деактивируется в внешней системе — и коннектор перестаёт авторизовываться, хотя формально всё настроено правильно.

Симптом почти всегда один: запрос из Data Connector начинает возвращать 401 Unauthorized или 403 Forbidden вместо ожидаемых данных, при этом ни конфиг ProcessMaker, ни сама интеграционная логика не менялись ни разу. Похожий разбор инцидента с протухшим токеном — с деталями, откуда берётся тишина в мониторинге, — есть в статье про сервис, который лежал 40 минут из-за одного просроченного токена: механика с ProcessMaker та же, только вместо всего сервиса «падает» один узел процесса.

Исходящие и входящие вебхуки: два разных места отказа

ProcessMaker может как отправлять вебхуки при событиях кейса (создание, завершение, изменение статуса), так и принимать входящие вебхуки, которые запускают или продвигают процесс извне. Это два разных направления с разными типичными поломками.

Исходящие вебхуки обычно рвутся из-за смены на стороне получателя: партнёр обновил свой API и сменил формат ожидаемого payload, поменял URL эндпоинта, включил проверку подписи запроса, которой раньше не было. ProcessMaker честно шлёт запрос по старому контракту, получает 4xx/5xx в ответ — и если ретраи не настроены или исчерпаны, событие просто теряется.

Входящие вебхуки — источник более коварных проблем, потому что они завязаны на инфраструктуру самого сервера, а не только на логику ProcessMaker:

• Истёк TLS-сертификат на эндпоинте, принимающем вебхук. Если сертификат выпущен вручную или автопродление (например, через certbot) сломалось после обновления системы, партнёрская система, которая проверяет валидность TLS перед отправкой, начинает получать ошибку рукопожатия и молча прекращает попытки — часто без ретраев и без уведомления вашей стороны.
• Изменился путь через reverse proxy. При переносе на новый сервер, смене конфигурации nginx или обновлении Docker Compose файла ProcessMaker маршрут /api/1.0/webhook/... (или другой, специфичный для вашей настройки) мог перестать проксироваться правильно — обычно после правки конфигурации «попутно», не в рамках задачи по интеграциям.
• Firewall или security group подрезали доступ. Если IP-диапазоны внешнего сервиса, шлющего вебхуки, обновились (что нередко у крупных SaaS-провайдеров раз в несколько месяцев), а у вас настроен белый список по IP, а не только по токену/подписи — вебхуки просто не долетают до сервера.

Похожий класс проблем — когда сама очередь обработки входящих запросов не справляется или отваливается по нагрузке — разобран в статье про то, почему n8n не принимает webhook: диагностика по слоям (DNS → TLS → reverse proxy → приложение) применима почти без изменений и к ProcessMaker.

Что меняют обновления ProcessMaker молча

Самостоятельно хостимый ProcessMaker обновляется вручную — через новый образ Docker, composer update для пакетов или полноценную миграцию на следующую минорную версию. Каждое такое обновление — точка риска именно для интеграционного слоя, реже для самого движка кейсов:

Версия PHP в образе меняется. Если вы переходите на новый Docker-образ ProcessMaker, в нём может быть обновлена версия PHP. Скрипт-задачи, написанные несколько лет назад с использованием устаревших или удалённых функций PHP, начинают падать с ошибками уровня выполнения — при этом BPMN-диаграмма и назначение задач не меняются ни на бит.

Формат хранения переменных процесса или конфигурации коннектора обновляется миграцией. Крупные обновления иногда переносят структуру данных на новую схему. Если коннектор был создан или отредактирован не через штатный интерфейс (например, массовым импортом при переносе с другого окружения), автоматическая миграция может отработать не так, как для коннектора, созданного вручную в UI.

Собственные плагины и пакеты теряют совместимость. Кастомные пакеты (packages), написанные под конкретную мажорную версию ProcessMaker, после обновления ядра могут либо не загружаться вовсе, либо загружаться, но с частично сломанной функциональностью — а сообщение об этом попадает не в интерфейс пользователя, а в лог приложения, куда никто не смотрит без повода.

Очередь фоновых задач (queue worker) не перезапускается после обновления. Часть асинхронной работы ProcessMaker — рассылка уведомлений, часть скрипт-задач, обработка отложенных действий — выполняется воркером (php artisan queue:work, часто под supervisor или как отдельный контейнер). Если после docker compose up -d или рестарта сервера воркер не поднялся автоматически, движок кейсов продолжает работать (веб-интерфейс отвечает нормально), а вся асинхронная часть просто перестаёт разгребаться — и это тоже незаметно снаружи первые дни или недели.

Если объём и сложность процессов у вас уже перерастают то, что комфортно тянуть на ProcessMaker (десятки параллельных BPMN-схем, тяжёлая оркестрация микросервисов, необходимость версионировать процессы как код), стоит присматриваться к более тяжёлым Java-платформам вроде Camunda — там другой набор компромиссов между гибкостью и порогом входа, но и инфраструктурные требования выше.

Как диагностировать: логи, очередь, аудит кейса

Порядок, который экономит часы разбирательства, когда «что-то не приехало»:

1. Проверить лог приложения. В типичной Docker Compose установке:

docker compose logs --tail=200 processmaker
docker compose exec processmaker tail -n 200 storage/logs/laravel.log

Ошибки авторизации к внешним API (401/403), таймауты и исключения PHP из скрипт-задач обычно видны здесь напрямую, с указанием, какая именно задача и в каком кейсе упала.

2. Проверить состояние очереди фоновых задач. Если используется Redis-очередь с Horizon или обычный queue:work:

docker compose exec processmaker php artisan queue:failed

Растущий список неудавшихся задач (failed jobs) с ошибками вида cURL error 28 (таймаут) или 401 Unauthorized — прямой признак того, что проблема не разовая, а системная и продолжается уже какое-то время.

3. Проверить аудит конкретного кейса. В интерфейсе ProcessMaker у каждого кейса есть история выполнения по узлам — если конкретный скрипт-узел или веб-сервисная задача помечены статусом ошибки, а следующий узел всё равно активен, значит логика процесса не остановилась на ошибке (это осознанный выбор при проектировании BPMN, но именно он маскирует проблему от пользователей).

4. Отдельно проверить TLS-сертификат, если речь о входящих вебхуках.

echo | openssl s_client -connect your-domain:443 -servername your-domain 2>/dev/null | openssl x509 -noout -dates

Если notAfter уже в прошлом или наступит в ближайшие дни — это самостоятельная причина молчания входящих вебхуков, никак не связанная с логикой ProcessMaker.

5. Свериться напрямую с документацией внешнего провайдера по TTL токенов. Универсального правила нет: у одних сервисов access-токен живёт час, а refresh-токен — бессрочно при регулярном использовании, у других (особенно в тестовом/sandbox-режиме приложения) счёт идёт на дни. Ориентироваться нужно на конкретного провайдера, а не на усреднённые цифры из интернета.

Регламент: что проверять каждые несколько недель

Минимальный набор действий, который снимает большую часть внезапности и укладывается в 20-30 минут в месяц:

Отдельно стоит завести таблицу (даже в самом простом виде — гугл-таблица или заметка) с перечнем всех внешних интеграций, у кого из провайдеров какой TTL токена и секрета, и с датой, когда секрет был выпущен. Это единственный способ узнать о приближающемся истечении заранее, а не постфактум — сам ProcessMaker такой сводки не строит. Общая идея регулярной проверки внешних зависимостей до того, как о ней сообщит контрагент, подробнее разобрана в статье про мониторинг обязательных интеграций — там речь о другом классе интеграций, но принцип «узнать раньше клиента» тот же.

Частые вопросы