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 способа создавать шаблоны документов в системе:

1. Располагая их в проекте в определенной директории.

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 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>).

Действие сгенерировать и скачать документ

В системе предусмотрено действие, позволяющее на основе карточки, сгенерировать документ из шаблона документов и сразу его скачать. Для это необходимо в системе создать новое действие (Подробнее о действиях тут: Действия) с типом 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-архива с шаблоном и его метаданными.

Автоматическая генерация контента из шаблона

Для автоматической генерации контента из шаблона при создании рекорда необходимо:

1. В тип данных добавить аспект templated-content

2. В конфигурации аспекта выбрать шаблон:

Примечание

Если при создании рекорда включен аспект 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 для решения проблемы:

1. Открыть docx как архив.

   

2. В папке word открыть файл document.xml

   

Найти условие, разбитое на теги:

3. Собрать в один тег:

   

4. Сохранить. Загрузить

Движок «ECOS table»

Данный движок в системе ECOS служит для работы с шаблонами документов в формате xlsx. Движок представляет собой смесь обработчика xlsx файлов и обработчика Freemarker, что дает следующие возможности:

• использование в ячейках полноценного синтаксиса Freemarker для заполнения ячеек значениями;

• использование специального синтаксиса для генерирования строк в xlsx файле.

Общий принцип работы движка:

• сканирует все страницы шаблона, заменяя, где необходимо, значения в ячейках на значения из модели, используя обработчик Freemarker

• при нахождении строк с определенным синтаксисом (для генерации новых строк) начинает генерировать новые строки, заменяя ячейки в них значениями из объектов снутри соответствующего списка из модели. Другими словами, в модели должен быть список с объектами, на основе которого будут сгенерированы строки (число строк будет совпадать с киличеством элементов в списке). При генерировании строки будут использоваться значения объекта списка, для которого генерируется строка.

Синтакчис в ячейках

В ячеках можно полноценно использовать синтаксис обработчика Freemarker.

Конструкция:

Карточка: ${name}

подставит значение переменной name в указанное место, взяв его из модели данных.

Также можно использовать и более сложные конструкции, которые поддерживаются обработчиком Freemarker.

<#if annotations??><#list annotations as annotation>"${annotation.annotation.ru}"<#sep>, </#list></#if>

Синтаксис для генерации строк

Для генерации новых строк в шаблоне необходимо использовать следующую конструкцию:

На том месте, где ожидаются сгенерированные на основе списка объектов строки в первой ячейке пишется следующая конструкция:

#LIST list_name

где list_name - название переменной из модели, в которой записан список объектов.

Следующие строки строятся таким образом, как мы хотим их сгенерировать на основе объектов из списка list_name

Например:

В строках при заполнении ячеек используем имена переменных из объектов данного списка. (Также можем использовать и переменные из общей модели. Если имена у переменной из объекта и из общей моделе совпадут, то возьмется значение из объекта).

После описания шаблонных(ой) строк(и) необходимо поставить в первую ячейку на новой строке конструкцию:

#END

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

Пример

Мы имеем тип данных со следующими атрибутами:

Атрибут empls - является списком пользователей системы.

Для данного типа мы делаем шаблон со следующей моделью:

Перемення empls - хранит список объектов, состоящих из 3 полей, на основе пользователей системы.

Шаблон xlsx выглядит следующим образом:

Где:

• В ячейке А2 мы хотим записать значение из модели с ключом name

• В ячейке А5 мы указываем, что дальше мы хотим строки на основе объектов из списка с ключом empls в моделе

• В ячеках A6-C6 указываем как должны быть заполнены ячейки в сгенерированных строках

• В ячейке А7 мы указываем, что здесь заканчиваются шаблонные строки для списка с ключом empls (т.е. мы можем сделать 2 шаблонные строки и для каждой записи из списка будет генерироваться по 2 строки в итоговом файле)

В итоге, для карточки с данными параметрами:

Будет сгенерирован следующий шаблон: