Transformations микросервис
Примечание
Доступно только в Enterprise версии.
Опциональный Ecos-микросервис ecos-transformations для генерации документов по шаблонам, которые можно подгрузить с проектом или добавить через инструменты администратора.
Подключение микросервиса
Микросервис Трансформации (ecos-transformations) - самостоятельный микросервис, не требующих развертывания дополнительных баз данных (все шаблоны хранятся в бд ecos-model). Для обеспечения работоспособности необходимы:
ecos-model:2.13.0
Параметры подключения через docker-compose.yml
#=== TRANSFORMATIONS ===#
transformations-app-dev:
container_name: transformations-app-dev
image: nexus.citeck.ru/ecos-transformations:1.0.0
ports:
- 8087:8087
environment:
- _JAVA_OPTIONS=-Xmx256m -Xms256m
- SPRING_PROFILES_ACTIVE=dev,swagger
- ECOS_INTEGRATIONS_ONLYOFFICE_HOST=only-office-app
- ECOS_WEBAPP_RABBITMQ_HOST=rabbitmq-dev
- EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE=http://admin:$${jhipster.registry.password}@ecos-registry:8761/eureka
- SPRING_CLOUD_CONFIG_URI=http://admin:$${jhipster.registry.password}@ecos-registry:8761/config
- ECOS_INIT_DELAY=0
depends_on:
- ecos-registry
Создание нового шаблона
Для работы с новыми шаблонами документов в Ecos есть журнал «Шаблоны документов», расположеный он в меню Инструменты в разделе Трансформации:
Существует 2 способа создавать шаблоны документов в системе:
Располагая их в проекте в определенной директории.
Загрузив их через действие Добавить в журнале Шаблоны документов.
Создание шаблона документа в проекте
Для успешного добавления в систему вашего шаблона необходимо учитывать некоторые вещи:
Вместе с самим шаблонов должен храниться файл
meta.yml
, который будет хранить метоинформацию о шаблоне.Особенность наименования файлов:
Если файл шаблона один, то мета-файл называется по шаблону
${Полное_имя_файла_с_расширением}.meta.yml
Пример:
Если файлов шаблона несколько в результате разделения их по локализации, то мета-файл именуется по следующему шаблону
&{Имя_файла_до_указания_локали}.meta.yml
Пример:
Структура мета-файла
Мета-файл должен содержать следующие поля в своей структуре:
Поле
Описание
id
Уникальный идентификатор шаблона в системеid: test-template
engine
Наименования движка, который будет обрабатывать заполнение шаблона(На данный момент существует толькоfreemarker
)engine: freemarker
name
Имя шаблонаname: TestTemplate
mimeType
Тип файла шаблонаmimeType: application/vnd.openxmlformats-officedocument.wordprocessingml.document
model
Представляет собой мапу ключ-значение, где в качестве ключа используется атрибут из шаблона, а в качестве значения атрибут, который возмется из карточки.model: regNumber: idocs:registrationNumber regDate: idocs:registrationDate|fmt('dd.MM.yyyy') initiator: idocs:initiator.cm:firstName
В значениях можно использовать все возможности обращения с атрибутами через Records APIcomputedAttributes
Вычисляемые атрибуты модели.Задается списком атрибутов.Перед генерацией шаблона преобразует полученные атрибуты в моделе согласно типу преобразования.computedAttributes: - id: docInvestigationInfo type: html-to-text
Подробнее тут Вычисляемые атрибуты для шаблонов`tags
Список вспомогательных меток где удобного поискаtags: - Template - Test - Example
Пример:
--- id: test-docx-template engine: freemarker name: TestDocxTemplate mimeType: application/vnd.openxmlformats-officedocument.wordprocessingml.document model: modelValue: ?disp
Файлы должны располагаться в проекте по определенному пути.
Путь для расположения файлов имеет следующий паттерн:
В МКР:
${home_dir}/src/main/resources/eapps/artifacts/transformation/template/
В проектах:
${module_name}/src/main/resources/alfresco/module/${module_name}/transformation/template/
В данных директориях вы можете создавать создавать внутреннюю структуру папок. Поиск артифактов шаблонов происходит рекурсивно по папкам, но начинается именно с этих директорий.
Создание шаблона через журнал
Для создания шаблона документа через журнал необходимо зайти в Инструменты в левом меню, затем в справа в разделе Трансформации выбрать журнал Шаблоны документов и создать новую запись.
Необходимо заполнить следующие поля:
Поле |
Описание |
---|---|
ID |
Уникальный идентификатор шаблона в системе |
Имя |
Имя шаблона |
Движок |
Наименования движка, который будет обрабатывать заполнение шаблона
(На данный момент существует только Freemarker)
|
Шаблоны |
Загружается файл шаблона
Шаблон должен быть добавлен в zip архиве. (Так как именно так шаблоны хранятся в базе. пока так…)
В архиве должен быть файл с шаблоном в формате docx или ftl. Строгих правил к его наименованию нет, но желательно придерживаться общей концепции и называть файл как id шаблона.
Если шаблонов несколько (разделены по локализации), то при названии файлов в конце нужно приписывать суффиксы _ru, _en и т.п.
|
Модель |
Представляет собой мапу ключ-значение, где в качестве ключа используется атрибут из шаблона, а в качестве значения атрибут, который возмется из карточки. |
Вычисляемые атрибуты |
Лист объектов с информацией о вычисляемых атрибутах.
Подробнее тут Вычисляемые атрибуты для шаблонов`
|
Теги |
Список вспомогательных меток для удобного поиска
Подробнее тут Вычисляемые атрибуты для шаблонов`
|
Вычисляемые атрибуты для шаблонов
Вычисляемые атрибуты в метафайле шаблона предназначены для тоже, чтобы совершить какую-то постобработку над значениями, которые пришли в модели, и обновить эти значения в модели или добавить под новыми именами.
Структура записи:
Указания вычисляемых атрибутов начинается с указания ключевого атрибута computedAttributes
в корневой страктуре метафайла, содержащего в себе список объектов следующего вида:
Поле |
Описание |
---|---|
ID |
Уникальный идентификатор атрибута. Именно с этим значением атрибут попадет в итоговую модель.
Если в модели есть аттрибут с таким именем, то значение в модели обновится.
|
type |
Указания типа преобразования значения. |
config |
Представляет собой мапу ключ-значение, из дополнительных параметров конфигурации и их значений.
config:
attribute: test1
Имеет общий параметр для всех видов -
attribute . Данный параметр в качетве значения принимает имя атрибута, значение которого возмется для преобразования.Если данный параметр не задан, то из модели возметря значение атрибута с именем из поля id вычисляемого атрибута.
|
Пример:
model:
test1: ecos:text1
test2: ecos:text2
computedAttributes:
- id: test3
type: html-to-text
config:
attribute: test1
- id: test2
type: html-to-text
Типы вычисляемых атрибутов
Тип |
Описание |
---|---|
html-to-text |
Преобразует входной текст из HTML кода в текст, убирая из него лишние теги (такие как <p>, <br>, <li>). |
Действие сгенерировать и скачать документ
В системе предусмотрено действие, позволяющее на основе карточки, сгенерировать документ из шаблона документов и сразу его скачать. Для это необходимо в системе создать новое действие (Подробнее о действиях тут: Действия) с типом download-by-template
.
Для работы действия необходимо заполнить следующие атрибуты в конфиге действия:
Атрибут |
Значение |
---|---|
resultName |
Имя итогового документа.
resultName: 'test-docx.docx'
Если данный атрибут будет отсутствовать, то возьмется имя документа шаблона.
|
templateRef |
Ссылка на вызываемый шаблон
templateRef: 'transformations/template@test-template'
|
Принцип работы:
Вызывая действие из меню действий карточки система сделает запрос к шаблону, достанет модель из шаблона, заполнит ее соответствующими значениями и отправит все данные в микросервис транснформации, где на основе модели и шаблона сгенерируется документ и вернется обратно на UI, где просто скачается.
Особенность: Если используются зашифрованные поля (зашифрованы в БД и расшифровываются непосредственно у пользователя), то такие поля передадутся в расшифрованном виде и в сгенерированном документе они будут корректно отображаться.
Примеры действий:
---
id: download-by-test-template
type: download-by-template
config:
templateRef: 'transformations/template@test-template''
---
id: download-by-test-docx-template
type: download-by-template
name:
ru: Скачать DOCX шаблон
en: Download DOCX template
config:
templateRef: 'transformations/template@test-docx-template'
resultName: 'test-docx.docx''
Импорт/экспорт шаблонов
Импорт и экспорт шаблонов помогает легко и просто переносить шаблоны документов между стендами. Мы скачиваем необходимые нам шаблоны на одном стенде и импортируем их на другом без особой нагрузки. Также можно сгенерировать архив с шаблоном самому, и импортировать нужный шаблон на стенд в одно несложное действие.
При импорте/экспорте будет осуществляться работа с zip-архивом, который содержит метоинформацию шаблона и непосредственно сам шаблон документа:
Импорт
Импорт шаблонов осуществляется через вариант создания шаблона Импортировать шаблон документа в журнале Шаблон документов:
Для импорта необходимо приложить zip-архив с файлами:
Файл с метаданными от шаблона. Имя файла должно быть сформировано по принципу: Имя_файла.meta.yml
Непосредственно сам шаблон (или шаблоны с разной локализацией).
Важно
Именно такой архив формируется при экспорте шаблона
Экспорт
Экспорт осуществляется с помощью действия Скачать при наведении на необходимый нам шаблон документа.
После нажатия на действие будет осуществляться скачивание zip-архива с шаблоном и его метаданными.
Автоматическая генерация контента из шаблона
Для автоматической генерации контента из шаблона при создании рекорда необходимо:
В тип данных добавить аспект
templated-content
В конфигурации аспекта выбрать шаблон:
Примечание
Если при создании рекорда включен аспект templated-content
, но автоматическую генерацию нужно выключить, то можно выставить атрибут templated-content:autoGenerate
в false
.
При создании рекорда автоматическая генерация выполняется синхронно, результат будет записан в атрибут _content
.
Сгенерированный контент будет доступен для скачивания, предпросмотра и сравнения версий.
Синтаксис условных операторов
В микросервис трансформации перенесена логика из класса DocxFreeMarkerProcessor из проекта ecos-community-core. Расположена в классе DocxFreemarkerTemplateService.
Необходимо обратить внимание на описание сервиса, а именно на синтаксис условных операторов:
Выражения, которые содержат открывающий и закрывающий теги, необходимо оборачивать в теги группировки [#
#]
:
Параметры работы с документом во встроенном редакторе OnlyOffice
В действии, в url, через «&config=JSON» необходимо прописать конфиг, предварительно сгенерировав его в encodeURIComponent прямо в браузере:
В данном примере мы разрешаем пользователю редактировать только определённые поля, и при этом убираем возможность скачать файл.
Варианты конфигурации редактора описаны в официальной документации
Для создания документа с редактируемыми полями необходимо исходный .docx файл локально открыть в редакторе OnlyOffice и сохранить в формате .docxf
Открыть уже в этом формате, и с помощью вкладки Формы → Текстовое поле, разметить необходимые поля.
При этом нужно убедиться, что «Заполнитель» и «Значение по умолчанию» пустые (для избежание проблем вёрстки и изменения цвета текста после генерации по шаблону)
Отметив необходимые поля, необходимо снова сохранить документ в формате .docx, открыть в Word, заполнить необходимыми тегами и сохранить:
Далее опять открыть с помощью OnlyOffice и через вкладку Защита→ Защитить документ:
Указать пароль и «Заполнение форм»:
В итоге получаем готовый .docx файл, который перед тем как загружать в систему, следует поправить, пользуясь статьей Временное решение ошибки при генерации шаблона с условиями
Временное решение ошибки при генерации шаблона с условиями
При генерации документа из шаблона документа, в котором есть условие (т.е. if, else или elseif), возникает ошибка.
так как файл document.xml дробит условие на множество тегов:
Work around для решения проблемы:
Открыть docx как архив.
В папке word открыть файл document.xml
Найти условие, разбитое на теги:
Собрать в один тег:
Сохранить. Загрузить