Перейти к содержанию

Генератор документов и бизнес-процессы

Активити «Генерация документа из шаблона» подключается к бизнес-процессам Битрикс24: сделкам, лидам, компаниям, контактам, смарт-процессам и счётам. Страница отвечает на главный практический вопрос — почему процесс завершается, а документа нет, и как это диагностировать.

Главное правило диагностики

Приложение вызывается только когда процесс дошёл до шага «Генерация документа из шаблона». Если шага нет в журнале бизнес-процесса — процесс до генератора не дошёл, и искать причину нужно в самом бизнес-процессе, а не в приложении.

Как работает активити

Активити выполняется асинхронно: Битрикс24 передаёт параметры шага в приложение, приложение генерирует документ и возвращает управление процессу (USE_SUBSCRIPTION=Y). Если генерация завершилась с ошибкой, в возвращаемое свойство error записывается её текст — процесс при этом продолжает идти по обычной ветке, а не падает.

Параметры шага

Параметр Обязательно Описание
template_id да ID шаблона. Можно узнать в списке загруженных шаблонов в приложении
entity да Тип базового объекта: crm_deal (сделка), crm_company, crm_contact, crm_item_XXX для смарт-процесса, где XXX — entityTypeId конкретного смарт-процесса
bx_id да ID базового объекта — число или переменная, например {{ID}}, если генерация идёт для того объекта, на котором запущен процесс
result_field нет Код поля для сохранения документа в формате DOCX: UF_CRM_123 для сделок/компаний/контактов, ufCrm11_222 для смарт-процессов
result_field_pdf нет Код поля для сохранения PDF-версии (формат кода тот же)
Возврат error — Текст ошибки генерации, если она произошла

Диагностика: БП завершается, а документа нет

Пошаговый алгоритм диагностики.

Шаг 1. Откройте журнал бизнес-процесса

В карточке элемента → Бизнес-процессы → журнал конкретного запуска. Журнал показывает, на каком шаге процесс завершился и с каким результатом.

flowchart TD
    A["БП завершён, документа нет"] --> B{"Шаг «Генерация документа<br/>из шаблона» есть в журнале?"}
    B -- "Нет" --> C["Процесс не дошёл до генератора.<br/>Ищите причину в предыдущих шагах БП:<br/>паузы, условия, статусы"]
    B -- "Да" --> D{"В возвращённом свойстве<br/>error есть текст?"}
    D -- "Да" --> E["Ошибка генерации: проверьте<br/>template_id, entity, поля сохранения"]
    D -- "Нет" --> F["Генерация прошла успешно —<br/>документ ищите в поле карточки,<br/>а не в списке файлов"]

Шаг 2. Проверьте шаги до генератора

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

  • Шаг «Пауза» до даты. Если дата уже прошла или поле пустое, пауза проходит мгновенно и процесс уходит дальше по цепочке — внешне выглядит как «сразу завершился».
  • Условия и статусы. Процесс сворачивается в ветку без шага генерации: условие сработало иначе, чем ожидалось (пустое поле, не тот статус элемента).
  • Лимит одновременных экземпляров процесса на элемент (по умолчанию — 2). Незавершённые экземпляры, оставшиеся после прежних зацикливаний, блокируют запуск новых: остановите зависшие процессы в карточке элемента (раздел «Бизнес-процессы» → меню запущенного процесса → «Остановить»).
  • Остановка по ошибке на предыдущем шаге. Журнал помечает такой шаг красным.

Шаг 3. Проверьте настройки шага генерации

Ошибки, которые приложение возвращает в свойстве error, почти всегда сводятся к трём:

Симптом Причина Что делать
«Поле сохранения не найдено» Указан неверный тип базового объекта — у каждого смарт-процесса свой entityTypeId Узнайте entityTypeId своего смарт-процесса (см. ниже) и укажите корректный crm_item_XXX
«Шаблон не найден» Неверный template_id — шаблон удалён, принадлежит другому порталу или ещё не загружен Сверьте ID в списке шаблонов в приложении
Шаг проходит, но документ сохраняется «не туда» Неверный ID базового объекта: должен быть ID элемента, для которого запущен процесс, — используйте переменную {=Document:ID} Укажите в параметре bx_id значение {=Document:ID} вместо ручного числа
Документ сгенерирован, но в карточке его не видно Неверный код поля сохранения (result_field / result_field_pdf) Проверьте формат кода: UF_CRM_123 для сделок/компаний/контактов, ufCrm11_222 для смарт-процессов; поле должно существовать у сущности

Как узнать entityTypeId смарт-процесса

EntityTypeId — числовой идентификатор смарт-процесса на портале. Способы узнать:

  1. Откройте список элементов смарт-процесса — entityTypeId виден в URL страницы (.../type/<entityTypeId>/...).
  2. В настройках смарт-процесса (CRM → Настройки → Смарт-процессы) идентификатор указан в карточке процесса.
  3. В роботах и активити Битрикс24 тип базового объекта выбирается из списка — сверьте строку вида crm_item_<entityTypeId> с фактическим entityTypeId.

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

Процесс запускается снова и снова, генерируя один и тот же документ. Что это? Это зацикливание бизнес-процесса, а не сбой генератора: генератор сохраняет документ в поле элемента, Битрикс24 видит изменение элемента и перезапускает процесс с автозапуском «при изменении элемента». Уберите триггер «при изменении» из шаблона БП или исключите из него сохранение документов. Каждый круг при этом выглядит в журнале как новый запуск процесса.

Поддержка говорит «все генерации успешны», а у меня документов нет. Успешные генерации видны приложению; процессы, которые не дошли до шага генерации, приложению не видны в принципе. Диагноз ставится только по журналу БП — шаг 1 выше.

Где взять ID шаблона? В приложении: список загруженных шаблонов → колонка/поле ID. Тот же ID указывается в параметре template_id шага.

Сгенерировал документ кнопкой в приложении — в карточке его нет. Кнопка в интерфейсе приложения записывает документ только в журнал генерации. В поля карточки документ сохраняет исключительно шаг бизнес-процесса с настроенными result_field / result_field_pdf. Это же ответ на вопрос «почему в карточке один файл, а в журнале два запуска».

Можно ли сохранить и DOCX, и PDF? Да — заполните оба параметра: result_field (DOCX) и result_field_pdf (PDF). Коды полей могут совпадать по формату, но это два разных поля карточки.

Обращайтесь к нашим специалистам

По любым вопросам настройки и расширения имеющегося функционала приложений обращайтесь в нашу службу поддержки.

Мы всегда поможем вам решить вашу задачу.