Трансформация содержимого документов

Примечание

Доступность отдельных компонентов трансформации зависит от состава и условий поставки, а также от подключённых конвертеров.

Трансформации выполняются в микросервисе ecos-transformations.

Spring настройки для микросервиса трансформаций:

ecos:
  webapp:
    task:
      executors:
        transformations:
          corePoolSize: 10 # количество потоков трансформации

Конвертация — частный случай трансформации, который подразумевает изменение содержимого из одного формата в другой.

Для офисных форматов используется конвертер OnlyOffice. Также есть локальные конвертеры, в том числе image-to-pdf для поддерживаемых растровых изображений. Он преобразует JPEG, PNG, GIF, BMP и TIFF в PDF, включая обработку многостраничного TIFF, без обращения к OnlyOffice.

Если конвертер не задан явно, выбирается первый зарегистрированный конвертер, поддерживающий исходный и целевой MIME-типы. При совпадении MIME-типов содержимое копируется без конвертации. Наличие компонента не означает поддержку произвольной пары форматов.

Автоматический предпросмотр дополнительно проверяет возможность нативного отображения: изображения с нативным предпросмотром пропускаются до поиска конвертера. Явная трансформация изображения в PDF при этом может быть доступна.

OnlyOffice

Настройки:

ecos:
  integrations:
    onlyoffice:
      host: only-office-app # хост, на котором доступен сервер OnlyOffice
      port: 80              # http порт для работы с OnlyOffice
      path: ""
      secure: false         # true для HTTPS
      connectTimeoutSeconds: 30
      readTimeoutSeconds: 60
      callbackLifetimeSeconds: 600
      pollingIntervalMs: 2000
      pollingMaxAttempts: 300

Поддерживаемые пары форматов определяются таблицей возможностей конвертера; сервер OnlyOffice должен быть доступен из микросервиса трансформаций.

Типы источников контента (input)

Идентификатор

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

Описание

entity-content

entityRef: EntityRef — ссылка на сущность, из которой нужно загрузить контент; в JSON задаётся строкой
attribute: String — атрибут с контентом. Пустое значение передаёт выбор основного контента в Content API
index: Int — индекс элемента множественного контента, по умолчанию 0

Загрузка контента из свойства документа

template

entityRef: EntityRef — ссылка на сущность, на основе которой будет вычислен шаблон
templateRef: EntityRef — ссылка на шаблон

Генерация содержимого на основе шаблона

Типы трансформаций (transformations)

Ниже перечислены основные компоненты. В сервисе также зарегистрированы merge и applyImage; их конфигурации отличаются от приведённых здесь.

Идентификатор

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

Описание

convert

converter: String — идентификатор конкретного конвертера. Если не задан, вычисляется автоматически
toMimeType: String — MIME type содержимого, которое требуется получить по итогу конвертации
sourceConfig: ObjectData — дополнительные настройки источника для конвертера, по умолчанию пустой объект; интерпретация зависит от конвертера

Конвертирование содержимого из одного MIME type в другой

barcode

entityRef: EntityRef — сущность для получения данных штрихкода. Если не задана, используется сущность входного контента
barcodeAttribute: String — атрибут штрихкода; по умолчанию пустой
layout — размещение, по умолчанию BOTTOM_CENTER
pages — страницы: ALL, FIRST или LAST; по умолчанию ALL
altText: Boolean — отображение текста штрихкода, по умолчанию true
width, height, marginX, marginY, scale — параметры размера, отступов и масштаба; scale по умолчанию 1
backgroundColor, textColor — цвета фона и текста, по умолчанию #FFFFFF и #000000

Добавление штрихкода в PDF. При другом MIME-типе или отсутствии сущности-источника возникает ошибка. Все параметры имеют значения по умолчанию, поэтому config можно опустить.

Типы целей трансформации (output)

Идентификатор

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

Описание

temp-file

—

Загрузка результата во временный файл. Как правило используется, если результат требуется скачать.

mutate

entityRef: EntityRef — ссылка на мутируемую сущность
attribute: String — целевой атрибут для содержимого. По умолчанию _content
additionalAttributes: ObjectData — объект дополнительных атрибутов для мутации, по умолчанию пустой

Выполнить мутацию с итоговым содержимым. Может быть использован как для создания новых сущностей, так и для изменения существующих.

Общий вид конфигурации для трансформации

Общий вид описания трансформации состоит из трёх частей:

  • input — описание источника контента;

  • transformations — список трансформаций в порядке очереди;

  • output — описание цели для итогового контента.

Пример:

  1. Берём основное содержимое у сущности emodel/anysrc@123-123-123;

  2. Преобразовываем его в pdf;

  3. Добавляем баркод;

  4. Загружаем результат во временный файл.

{
  "input": {
    "type": "entity-content",
    "config": {
      "entityRef": "emodel/anysrc@123-123-123"
    }
  },
  "transformations": [
    { "type": "convert", "config": { "toMimeType": "application/pdf" } },
    { "type": "barcode" }
  ],
  "output": {
    "type": "temp-file"
  }
}

В примере config для barcode опущен: используются параметры по умолчанию и сущность входного контента. Последовательность важна — перед добавлением штрихкода результат должен иметь MIME-тип application/pdf. Для исходного формата необходим поддерживающий конвертер.

UI действие

Действие для трансформации описано в разделе UI действий с ID transform здесь