DocxTemplateHandler

Материал из RunaWFE
Перейти к навигации Перейти к поиску

Генерация документов на основе шаблона docx

Версия 4.5.0

© 2015-2023, ООО "Процессные технологии"

# Обзор

Обработчик ru.runa.wfe.office.doc.DocxHandler предназначен для генерации документа на основании шаблона.

Обработчик может выполняться в режиме строгого соответствия (strict-mode=true), что соответствует ошибке при любой ошибке в шаблоне или отсутствии определённых в шаблоне переменных в процессе, или нет, что указывается в конфигурации обработчика.

Замечание. Символы в названиях переменных (двоеточие, последовательность ' as ') могут вызывать ошибки обработки.

# Настройка

См. office.properties в руководстве по настройке. Свойства docx.placeholder.start, docx.placeholder.end определяют синтаксис управляющих инструкций. Далее в этом тексте использованы конструкции ${ и }.

# Замена текста

Выражения вида

${Переменная}

будут заменены на значение переменной Переменная, в формате, определённом в Среде разработки.

Замечание. Для формирования перевода строки переменная должна содержать последовательность \r\n

# Доступ к элементам карт и списков

Доступ к элементам контейнерных типов осуществляется с помощью квадратных скобок [].

В качестве индекса списка может выступать целочисленное значение или переменная.

В качестве ключа карты может выступать строковое значение или переменная.

Примеры:

карта[ключ1]
${список[3]}

# Доступ к полям типов Пользователь, Группа, Исполнитель

Вывод полей осуществляется стандартным способом. Например, для вывод Ф.И.О. из переменной запустившийПроцесс типа "Пользователь"

${запустившийПроцесс.fullName}

Замечание. В ранних версиях 4.0.6- в конфигураторе можно было указать другой формат при замене переменной. Этот функционал будет доступен в режиме обратной совместимости 4.2.0-, но в этом случае не доступны текущие возможности. Обработчик принимает решение перехода в режим обратной совместимости на основании наличия такой конфигурации.

# Доступ к коду 4.2.2+

Доступ к коду осуществляется с помощью groovy.

Примеры:

${groovy:ru.runa.wfe.commons.CalendarUtil.formatDate(VARIABLE_NAME)}

# Работа с изображениями

Путём стандартной замены можно заменить указатель в шаблоне

${image1}

на значение файловой переменной, хранящей изображение.

Замечание. Если файловая переменная хранит не изображение (или изображение в неизвестном формате) - будет ошибка обработки шаблона.

# Итераторы

При работе с контейнерами используются следующие итераторы:

  • indexes для списков итерация по индексам (начиная с 0)
  • numbers нумерация для списков (начиная с 1 = {index+1})
  • items для списков итерация по значениям
  • keys для карт итерация по ключам
  • values для карт итерация по значениям

# Работа с таблицами

Замечание. В ранних версиях 4.0.6- в конфигураторе настраивались таблицы. Этот функционал будет доступен в режиме обратной совместимости 4.2.0-, но в этом случае не доступны текущие возможности. Обработчик принимает решение перехода в режим обратной совместимости на основании наличия в конфигурации таблиц.


В шаблоне нужно создать таблицу с заранее определённым количеством столбцов. Обратите внимание что настроенный стиль таблицы при данной замене должен быть сохранён. Строки по этим столбцам могут быть сгенерированы автоматически, используя карты или списки. Для этого требуется поместить в ячейку каждой строки значение в одном из форматов

${VARIABLE} 
${ITERATOR:VARIABLE}
${ITERATOR:VARIABLE as SELECTOR}

, где ITERATOR название типа итератора; в случае отстутствия используются итераторы по умолчанию items, values для соответствующих типов переменных.

VARIABLE название контейнерной переменной (типа Карта или Список)

SELECTOR название поля или атрибута, которое будет взято от переменной, хранящей текущее значение итератора; в случае отстутствия используется значение итератора

In case of maps linked by key sorting is carried out by keys. It's necessary to fill the first row with the some of the following in order for the rest of the rows to be filled with containers elements.

Variants of first row cells: Необходимо заполнить первую строку таблицы указанием на контейнеры, чтобы остальные строки заполнились значениями элементов этих контейнеров.

Примеры (каждая строк должна соответствовать одной ячейке первой строки):

${indexes:список}
${items:список}
${numbers:список}
${items:списокПользователей as fullName}
${список}
${keys:карта}
${карта}
${values:карта}
${values:картаСГруппами as name}

В случае отображения карт, связанных по ключу, сортировка осуществляется по ключам. Пример для связных карт карта1 и карта2 с ключами ключи1=ключи2. Первая строка таблицы первая ячейка ${keys:карта1}, вторая ячейка ${values:карта1}, третья ячейка ${values:карта2}. Все остальное заполнится автоматически.


Как уже было описано выше, в качестве SELECTOR может быть использован атрибут или название поля, взятое от переменной. Это очень удобно в случае использования списка пользовательского типа.

Например, есть тип "Фурнитура" с атрибутами "Наименование" и "Количество". Есть список фурнитур, хранящийся в переменной вида Список(Фурнитура). Для отображения этого списка в таблице с колонками "Наименование" и "Количество" используем конструкции:

${items:Список as Наименование} 

и

${items: СписокФурнитура as Количество}

расположенные в соответствующих столбцах таблицы. Пример процесса, использующего данные конструкции: Файл:СписокФурнитурDOCX.par


Замечание4.1.0-. Синтаксис с указанием названия поля или атрибута имел вид: ${ITERATOR:VARIABLE SELECTOR}.

# Объединение ячеек по вертикали 4.4.0+

При генерации таблицы значение "-||-" (можно изменить с помощью настройки) трактуется как соединение с соответствующей ячейкой из предыдущей строки.

# Работа с переменными пользовательских типов

При замене используется синтаксис с точкой, являющейся разделением атрибутов переменной пользовательского типа.

Пример:

${car 1.name}

# Дополнительные возможности

# Циклы βeta

Цикл определяется 3-мя элементами: начало цикла, блок цикла и окончание цикла.

Начало цикла имеет формат

${ITERATOR:VARIABLE as ITERATOR_VARIABLE}

, где ITERATOR название типа итератора

VARIABLE название контейнерной переменной (типа Карта или Список)

ITERATOR_VARIABLE название переменной, хранящей текущее значение итератора, значение зависит от типа итератора

Блок цикла может содержать только текст. Доступ к переменной, хранящей текущее значение итератора аналогично стандартной замене.

Замечание. Блок цикла не допускает наличие таблиц.

Замечание. Блок цикла не допускает вложенных циклов.

Замечание4.1.0-. Синтаксис с переменной-значением итератора имел вид: ${ITERATOR:VARIABLE ITERATOR_VARIABLE}.

Окончание цикла имеет формат

${/ITERATOR}

, где ITERATOR название типа итератора, соответствующее началу цикла

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

Примеры:

${items:список as значение}
 ${значение}
${/items}
${indexes:список as индекс}
 значение = ${список[индекс]} для элемента ${индекс}
${/indexes}
${keys:карта as ключ}
 ${ключ} = ${карта[ключ]}
${/keys}
${values:карта as значение}
 ${значение}
${/values}

# Ветвления планируется

${if (карта.size() == 0)}
 карта пустая
${if (карта.size() > 100)}
 карта достаточно заполнена
${if else}
 введите данные
${/if}

# Проверка шаблона docx 4.4.1+

В версии RunaWFE 4.4.1 в случае заданного docx шаблона как

  • файла в процессе (использование в задаче сценарии) - выполняется автоматическая проверка структур шаблона на соответствие переменным бизнес-процесса
  • файла в системе (использование в задаче бота) - выполняется автоматическое определение входных параметров на основе используемых конструкций в docx шаблоне

# Проверка структур шаблона docx используемого в задаче сценария на соответствие переменным бизнес-процесса

Для создания шаблона в процессе используется ссылка "Создать" (доступна в случае входного параметра "Файл в процессе").

Script docx t 1.png


В открывшемся окне редактора docx необходимо задать шаблон используя конструкции, описанные ранее в данном документе.

Пример шаблона

Script docx t 2.png


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

Script docx t 3.png


Из рисунка выше видно, что в шаблоне используются конструкции с последовательностями, которые не соответствуют названиям переменных в БП и атрибутов пользовательских типов этих переменных, а именно:

  • "Данные документа.Список позиций в документе"

В БП существует переменная "Данные документа" пользовательского типа "Данные документа"

Script docx t 4.png

но атрибут "Список позиций в документе" называется иначе - "Список позиций"

Script docx t 5.png


  • "Заказ.Договор на поставку.Поставщик" с атрибутами "Наименование" и "Телефон"

В БП существует переменная "Заказ" пользовательского типа "Заявка", имеющего атрибут "Договор на поставку". А вот атрибут "Поставщик" в БП имеет иное название "Поставщик деталей"

Script docx t 6.png

Применив в шаблоне docx правильные названия переменных, ошибки на вкладке с замечаниями будут очищены и БП будет возможно экспортировать на сервер.

# Определение входных параметров задачи бота на основе используемых конструкций в docx шаблоне

В версии RunaWFE 4.1.1 в задаче бота с обработчиком Word в случае использования шаблона docx в виде файла в системе, входные параметры задачи определяются автоматически на основе используемых в шаблоне конструкций.

Для создания шаблона в задаче бота используйте ссылку "Создать"

Bot task docx t 1.png


В открывшемся окне редактора docx необходимо задать шаблон используя конструкции, описанные ранее в данном документе.

Например,

Bot task docx t 2.png


После сохранения шаблона и задачи бота, необходимо обновить входные параметры

Bot task docx t 3.png


Переменные используемые в шаблоне будут автоматически определены и вынесены в раздел входных параметров.

Bot task docx t 4.png


Процесс обновления параметров необходимо повторять после каждого изменения шаблона.

Если список входных параметров будет отличаться от найденных в шаблоне переменных, то будет выдано соответствующее сообщение.

Bot task docx t 5.png

Bot task docx t 6.png