crm.clientright.ru/modules/OnlyOfficeTemplates

OnlyOfficeTemplates

Модуль генерации документов из DOCX-шаблонов с подстановкой полей CRM (аналог PDFMaker). Результат — PDF (по умолчанию) или DOCX. При сохранении в Документы в формате DOCX документ можно редактировать через OnlyOffice (кнопка «Nextcloud» / open_file_v2).

Возможности

• Шаблоны DOCX хранятся в отдельной папке S3 (crm2/OnlyOfficeTemplates/templates/{Module}/{templateId}/...).
• Редактирование по аналогии с PDFMaker: слева — OnlyOffice Editor, справа — метаданные + панель плейсхолдеров (поиск и copy-to-clipboard).
• Плейсхолдеры в шаблоне: {{fieldname}} для полей записи, {{ModuleName__fieldname}} для связанных модулей (Account, Contact и т.д.).
• В виджете карточки записи: выбор шаблона, формата (PDF/DOCX), действия «Скачать» и «Сохранить в Документы».
• При выборе PDF результат конвертируется через OnlyOffice Conversion API.
• Модуль портативный: можно развернуть в другом инстансе CRM без привязки к текущему crm_extensions.

Требования

• PHP с расширениями: zip, xml, curl (или allow_url_fopen для Conversion API).
• Composer-зависимости: phpoffice/phpword, aws/aws-sdk-php (уже в корне проекта).
• Доступ к S3-совместимому хранилищу и (для PDF) к OnlyOffice Document Server (Conversion API).

Установка

1. Скопируйте папку modules/OnlyOfficeTemplates и layouts/v7/modules/OnlyOfficeTemplates в целевой CRM.
2. Настройте переменные окружения или конфиг (см. раздел «Конфигурация»).
3. Выполните установку БД и виджетов одним из способов:
   • Через скрипт (рекомендуется):
     php modules/OnlyOfficeTemplates/install.php
     из корня CRM (или откройте в браузере соответствующий URL с правами администратора).
   • Через Module Manager: упакуйте модуль в zip с manifest.xml и импортируйте.
4. Добавьте шаблоны: загрузите DOCX в S3 в папку {OOT_S3_PREFIX}/templates/{Module}/{id}/{filename}.docx и добавьте запись в vtiger_oot_templates (имя, модуль, s3_key, file_name, owner), либо используйте экшен UploadTemplate (см. ниже). Старый путь {OOT_S3_PREFIX}/templates/{id}/{filename}.docx продолжает работать для существующих записей.

Конфигурация

Модуль читает настройки из:

1. Внешний конфиг (если есть): crm_extensions/file_storage/config.php — используются S3-данные оттуда.
2. Переменные окружения (.env в crm_extensions или в корне):
   • S3_ACCESS_KEY, S3_SECRET_KEY, S3_ENDPOINT, S3_BUCKET — доступ к S3.
   • OOT_S3_PREFIX — префикс папки модуля в S3 (по умолчанию crm2/OnlyOfficeTemplates).
   • OOT_ONLYOFFICE_CONVERT_URL — URL Conversion API (например https://office.example.com:9443/ConvertService.ashx или /converter).
   • ONLYOFFICE_DOCUMENT_SERVER или OOT_ONLYOFFICE_DOCUMENT_SERVER — URL OnlyOffice Document Server для редактора (например https://documentserver). Нужен для экрана редактирования шаблона (слева форма, справа OnlyOffice). Document Server должен иметь доступ по HTTP(S) к CRM (для загрузки документа и callback).
   • OOT_DOCUMENT_SECRET — секрет для подписи URL документа (рекомендуется в продакшене). Если задан, в ссылку на документ добавляется токен; без него GetDocument доступен без проверки.
   • OOT_DOCUMENTS_S3_PREFIX — префикс для файлов, сохраняемых в Документы (по умолчанию crm2/CRM_Active_Files/Documents).

• OOT_USE_DOCX_RENDERER — включить генерацию DOCX через внешний docx-renderer (true/false, по умолчанию false).
• OOT_DOCX_RENDERER_URL — базовый URL сервиса (например http://127.0.0.1:3015).
• OOT_DOCX_RENDERER_API_KEY — API-ключ для docx-renderer.
• OOT_DOCX_RENDERER_TIMEOUT — timeout HTTP-запроса в секундах (по умолчанию 25).
• OOT_DOCX_RENDERER_FALLBACK — fallback на legacy генерацию при ошибке (true по умолчанию).
• OOT_DOCX_RENDERER_MODULE_WHITELIST — whitelist модулей (CSV), для поэтапного включения.
• OOT_DOCX_RENDERER_TEMPLATE_WHITELIST — whitelist template id (CSV), для точечного запуска.

Без OnlyOffice Conversion API доступна только выдача DOCX (формат PDF не будет работать). Без Document Server редактирование шаблона в OnlyOffice недоступно, но можно загружать готовые DOCX через «Загрузить файл».

Редактирование и загрузка шаблонов

• Через OnlyOffice (как в PDFMaker): «Добавить шаблон» → создаётся черновик → открывается экран: слева редактор шаблона, справа метаданные и панель плейсхолдеров. Документ по сохранению/закрытию отправляется в S3 через callback. Список шаблонов: имя — ссылка на редактирование.
• Загрузить файл: кнопка «Загрузить файл» открывает форму: имя, модуль, выбор DOCX; отправка в UploadTemplate.
• Вручную: загрузите DOCX в S3 по пути {OOT_S3_PREFIX}/templates/{Module}/{template_id}/{имя_файла}.docx и вставьте запись в vtiger_oot_templates.

Безопасный rollout и откат

• Рекомендуем включать OOT_USE_DOCX_RENDERER=true только для 1 модуля и 1-2 шаблонов через whitelist.
• Мониторинг: cache/logs/OnlyOfficeTemplates_runtime.log и cache/logs/OnlyOfficeTemplates_callback.log.
• Мгновенный откат: OOT_USE_DOCX_RENDERER=false (legacy-поток продолжит работу).

Структура БД

• vtiger_oot_templates — id, name, module, s3_key, file_name, owner, created_at, settings (JSON, опционально).
• vtiger_oot_templates_seq — при необходимости для генерации id (опционально).

Портативность

Модуль не изменяет ядро CRM и не зависит от наличия crm_extensions. Все пути и ключи задаются через конфиг/переменные окружения. В другом инстансе достаточно задать свои S3_, OOT_ и (при необходимости) ONLYOFFICE_* и выполнить установку (install.php или импорт пакета).