Подключение микросервиса

Микросервис Трансформации (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 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-архива с шаблоном и его метаданными.

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

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

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

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

Примечание

Если при создании рекорда включен аспект templated-content, но автоматическую генерацию нужно выключить, то можно выставить атрибут templated-content:autoGenerate в false.

При создании рекорда автоматическая генерация выполняется синхронно, результат будет записан в атрибут _content.

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