Микросервис Трансформации (ecos-transformations) - самостоятельный микросервис, не требующих развертывания дополнительных баз данных (все шаблоны хранятся в бд ecos-model). Для обеспечения работоспособности необходимы:
- ecos-model:2.13.0
#=== 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
В значениях можно использовать все возможности обращения с атрибутами через :ref:`Records API<Records_API>`computedAttributes
Вычисляемые атрибуты модели.Задается списком атрибутов.Перед генерацией шаблона преобразует полученные атрибуты в моделе согласно типу преобразования.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>). |
В системе предусмотрено действие, позволяющее на основе карточки, сгенерировать документ из шаблона документов и сразу его скачать. Для это необходимо в системе создать новое действие (Подробнее о действиях тут: :ref:`Действия<ui_actions>`) с типом 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
- Непосредственно сам шаблон (или шаблоны с разной локализацией).
Important
Именно такой архив формируется при экспорте шаблона
Экспорт осуществляется с помощью действия Скачать при наведении на необходимый нам шаблон документа.
После нажатия на действие будет осуществляться скачивание zip-архива с шаблоном и его метаданными.
Для автоматической генерации контента из шаблона при создании рекорда необходимо:
- В тип данных добавить :ref:`аспект <aspects_user>`
templated-content
- В конфигурации аспекта выбрать шаблон:
Note
Если при создании рекорда включен аспект templated-content
, но автоматическую генерацию нужно выключить, то можно выставить атрибут templated-content:autoGenerate
в false
.
При создании рекорда автоматическая генерация выполняется синхронно, результат будет записан в атрибут _content
.
Сгенерированный контент будет доступен для скачивания, предпросмотра и сравнения версий.
При генерации документа из шаблона документа, в котором есть условие (т.е. if, else или elseif), возникает ошибка.
так как файл document.xml дробит условие на множество тегов:
Work around для решения проблемы:
Найти условие, разбитое на теги: