Диагностика проблем

Если сформированный документ пустой, неполный или в нём не хватает значений, причина почти всегда в самом шаблоне: опечатка в имени поля, неверный синтаксис раздела или отсутствующая запись на листе данных. На этой странице собраны самые частые проблемы и способы их диагностики.

Все имена плейсхолдеров в шаблоне берутся из машинных имён, определённых в типе сущности, к которому привязан шаблон. Диагностика почти всегда начинается со сравнения того, что написано в шаблоне, с тем, что определено в типе сущности.

Пустые места там, где должны быть данные

Симптом: в сформированном документе пустые места на месте ожидаемых значений полей.

Вероятные причины:

Опечатка в имени поля

Плейсхолдер {{custmerName}} не совпадает с машинным именем поля customerName (заданным в типе сущности). Нераспознанные плейсхолдеры разрешаются в пустые строки — ошибка не показывается.

Решение: сравните имя плейсхолдера в шаблоне с машинным именем в определении типа сущности в разделе Настройки → Сущности. Машинные имена чувствительны к регистру.

Не тот контекст

Внутри повторяющегося раздела плейсхолдеры разрешаются относительно текущего элемента — вложенного типа сущности, — а не записи верхнего уровня. Плейсхолдер вроде {{dealNumber}} внутри раздела {{#items}} ищет поле с машинным именем dealNumber у типа сущности позиции, а не у типа сущности сделки.

Решение: используйте {{$.dealNumber}}, чтобы обратиться к корневому контексту, или {{../dealNumber}}, чтобы обратиться к родительскому. Подробности — в разделе доступ к внешним полям.

У поля нет значения

Поле есть в типе сущности, но в конкретной записи для него не сохранено значение.

Решение: откройте запись в интерфейсе и убедитесь, что у поля есть значение.

Пустой документ целиком

Симптом: в сформированном файле есть статичный текст и макет шаблона, но каждый плейсхолдер разрешился в пустое место.

Вероятные причины:

Шаблон привязан не к тому типу сущности

Если шаблон привязан к типу сущности A, а машинные имена в его плейсхолдерах относятся к типу сущности B, ни один плейсхолдер не совпадёт.

Решение: проверьте в разделе администрирования, что шаблон привязан к нужному типу сущности.

В записи нет данных

Запись существует, но значения полей в ней не заполнены.

Решение: откройте запись и убедитесь, что в её полях есть данные.

Повторяющийся раздел не даёт строк

Симптом: раздел таблицы или слайдов, который должен повторяться для каждого элемента, ничего не выводит — строки или слайды отсутствуют совсем.

Вероятные причины:

Имя коллекции не совпадает

Тег раздела {{#lineItems}} не совпадает с машинным именем поля-коллекции в данных, которое может быть items. Имя внутри тега # должно быть точным машинным именем поля-коллекции (вложенной сущности или ссылки на несколько записей) в типе сущности.

Решение: откройте определение типа сущности и проверьте машинное имя поля-коллекции. Для предложений стандартный ключ коллекции, как правило, items.

Пустая коллекция

Коллекция существует, но в ней нет элементов. Когда коллекция пуста, повторяющийся раздел удаляется целиком — это правильное поведение, а не ошибка.

Решение: добавьте элементы в коллекцию (например, добавьте позиции в предложение).

Неверное расположение тегов (таблицы DOCX)

В схеме таблицы из трёх строк строки открывающего и закрывающего тегов должны быть отдельными строками. В схеме из одной строки открывающий тег должен стоять в первой ячейке, а закрывающий — в последней.

Решение: проверьте расположение тегов по схемам, описанным в повторяющихся разделах.

Плейсхолдер-изображение показывает текст вместо изображения

Симптом: в результате в фигуре виден текст плейсхолдера (или необработанное значение) вместо изображения.

Вероятные причины:

Смешанное содержимое фигуры

В фигуре есть другой текст, кроме тега плейсхолдера. Чтобы изображение подставилось, плейсхолдер должен быть всем содержимым фигуры.

Решение: удалите из фигуры весь текст, кроме самого тега плейсхолдера.

Поле не является ссылкой на изображение

Значение поля — текстовая строка. Движок вставляет текстовую строку как обычный текст.

Решение: убедитесь, что поле в типе сущности имеет тип «Файл» или «Изображение» (см. типы данных).

Неподдерживаемый формат изображения

Файл изображения в формате, который движок не распознаёт.

Решение: конвертируйте изображение в один из поддерживаемых форматов, перечисленных в плейсхолдерах-изображениях.

Маркеры ошибок XLSX

Шаблоны XLSX устойчивы к ошибкам. Если не удаётся сформировать одну ячейку, в ней будет ERR:, за которым следуют тип и текст ошибки. Если не удаётся сформировать лист целиком, в ячейке A1 этого листа будет RENDER ERROR, за которым следуют название листа и сведения об ошибке. В обоих случаях остальная часть книги формируется как обычно.

Подробности — в разделе устойчивость к ошибкам на странице о шаблонах Excel.

Значения листа _data отсутствуют (XLSX)

Симптом: коллекции, загруженные через лист _data, не дают данных на итоговых листах.

Вероятные причины:

Проверьте, есть ли лист _errors

Откройте сформированную книгу и найдите лист с названием _errors. Если он есть, на нём перечислены все источники данных, которые не удалось загрузить, тип сущности, который источник пытался запросить, выражение фильтра и сообщение об ошибке.

Неверное машинное имя типа сущности

Значение в столбце B листа _data не совпадает с машинным именем ни одного типа сущности в организации.

Решение: сверьте машинное имя с определением типа сущности в Настройки → Сущности.

Неверное выражение фильтра

В выражении в столбце C синтаксическая ошибка, либо оно ссылается на машинное имя поля, которого нет у целевого типа сущности.

Решение: упростите фильтр или временно уберите его и проверьте, что источник данных загружается без него. Синтаксис выражений фильтра описан на странице Лист _data.

Нет права доступа

У пользователя, который формирует документ, нет права на чтение типа сущности.

Решение: проверьте права роли пользователя на этот тип сущности.

Зарезервированный ключ коллекции

Ключ коллекции (столбец A) использует зарезервированное имя — items или filter. Строки с зарезервированными ключами пропускаются.

Решение: переименуйте ключ коллекции.

Плейсхолдер-выражение возвращает пустое значение

Симптом: плейсхолдер-выражение {{=...}} ничего не выводит.

Вероятные причины:

Синтаксическая ошибка

В выражении JavaScript синтаксическая ошибка — например, незакрытая скобка или неопределённая функция.

Решение: проверьте синтаксис выражения. Сначала проверьте простые выражения и усложняйте постепенно.

Неопределённая переменная

Выражение ссылается на машинное имя поля, которого нет в текущем контексте.

Решение: проверьте машинное имя поля в типе сущности и посмотрите, не находится ли выражение внутри повторяющегося раздела (там контекст — тип сущности текущего элемента, а не корневая запись). Подробности синтаксиса — в разделе выражения и форматирование.

Выражение выполняется слишком долго

Выражение, которое выполняется слишком долго, останавливается. Для простой арифметики это маловероятно, но может случиться при очень сложной логике.

Решение: упростите выражение.

Отладочный плейсхолдер DOCX

В шаблонах DOCX специальный плейсхолдер {{debug}} возвращает полный дамп всех данных, доступных шаблону, в формате JSON. Это удобно, чтобы посмотреть:

  • какие поля доступны и каковы их машинные имена,

  • какие значения содержит запись,

  • структуру коллекций (какие поля есть у каждого вложенного элемента — см. вложенные сущности).

Чтобы им воспользоваться, добавьте {{debug}} в абзац шаблона, сформируйте документ и изучите результат. Перед рабочим использованием шаблона уберите этот плейсхолдер.

Плейсхолдер {{debug}} доступен только в шаблонах DOCX.

Чек-лист

Если у сформированного документа есть проблемы, пройдите по этому чек-листу:

  1. Откройте определение типа сущности и выпишите точные машинные имена полей.

  2. Откройте запись и убедитесь, что у нужных полей есть значения.

  3. Откройте файл шаблона и сверьте каждый плейсхолдер с машинными именами — проверьте написание и регистр.

  4. Для повторяющихся разделов проверьте имя ключа коллекции и схему расположения тегов.

  5. Для плейсхолдеров-выражений проверьте синтаксис JavaScript и имена полей, использованные в выражении.

  6. Для плейсхолдеров-изображений проверьте, что фигура содержит только тег плейсхолдера и что поле хранит ссылку на изображение.

  7. При проблемах с листом _data посмотрите в сформированной книге лист _errors.

  8. Для шаблонов DOCX используйте плейсхолдер {{debug}}, чтобы посмотреть доступные данные.

Связанные страницы